Backlog.md

用 Git 里的 Markdown 任务文件，让人和 AI 一起管项目

开源 🏷️定价信息待确认 ⚠️ 链接可跳转，访问体验不确定自动化工作流 🍴 复刻 479 🐛 待处理 101 👀 关注 20

访问官网 ↗ GitHub ↗

GitHub 星标 ★ 7292

维护状态活跃

是否开源开源

定价模式 🏷️定价信息待确认

项目预览

项目数据

分类自动化工作流

开发团队MrLesk

官网地址https://backlog.md

GitHubhttps://github.com/MrLesk/Backlog.md

定价模式🏷️定价信息待确认

价格说明定价信息待确认

访问状态⚠️ 链接可跳转，访问体验不确定

是否开源是

开源协议MIT

主要语言TypeScript

技术栈/模型agent,agentic-ai,management,markdown,project,task-manager,tasks

GitHub 星标★ 7292

上线时间2025-06-04 00:00:00

代码更新2026-11-04

仓库体积48.5 MB

本站数据更新2026-11-06

维护状态活跃

收录时间2026-09-22

浏览次数2

项目介绍

Backlog.md 是一个面向人类与 AI Agent 协作的项目管理工具，把任务、需求、决策记录全部以 Markdown 文件形式存放在 Git 仓库中。它解决的核心问题是：当 AI 编程助手参与开发时，任务状态和上下文散落在聊天记录、issue 和文档里，难以追踪和版本化。Backlog.md 用纯文本任务文件作为唯一事实来源，让人类和 Agent 都能直接读写同一份任务列表，并借助 Git 的提交、分支、合并能力记录每次变更。核心能力包括：创建和更新任务、按状态和优先级组织 backlog、在命令行中快速检索和操作任务、让 AI Agent 通过读写 Markdown 文件参与任务流转。由于不依赖数据库和专有服务，团队可以沿用现有 Git 工作流，把项目管理变成可审查、可回滚的代码化流程。

Star 增长趋势

本站每日记录该项目 GitHub 星标变化，观测越久曲线越完整

数据来源：GitHub API 逐日快照 · 收录于 2026-09-22 · 当前星标 ★ 7292

技术标签

agent agentic-ai markdown

使用教程

难度：入门约 10 分钟部署方式：命令行工具 6 步

环境要求

Node.js 环境（使用 npm 全局安装时需要）
建议准备一个 Git 仓库（Git 是可选的，可用 --no-git 跳过）
macOS 用户可选 Homebrew，使用 Nix 的用户需已启用 flakes

安装与启动步骤

1全局安装 CLI

通过 npm 全局安装 backlog.md 命令行工具，安装完成后即可在任意目录使用 backlog 命令。
```
npm i -g backlog.md
```
2初始化项目

在目标 Git 仓库目录下运行初始化向导，会询问如何连接 AI 工具（CLI 指令 / MCP / 跳过），并创建项目内的 backlog 目录。
```
backlog init
```
3自定义任务前缀

默认生成 TASK-1 这类 ID，可在初始化时通过 --task-prefix 指定前缀，本仓库示例使用 back，生成 BACK-1。
```
backlog init --task-prefix back
```
4无 Git 项目初始化

不想依赖 Git 时使用 --no-git，创建纯文件系统项目，配置会强制关闭 checkActiveBranches、remoteOperations 和 autoCommit。
```
backlog init --no-git
```
5调整配置项

运行不带参数的配置向导，逐步设置分支准确性、Git 工作流、ID 格式、编辑器、Web UI 端口等；跳过则使用内置安全默认值。
```
backlog config
```
6让 Agent 读取指令

初始化向导推荐选择 CLI instructions，它会生成一个简短说明文件，指示 AI Agent 运行该命令获取项目任务上下文。
```
backlog instructions overview
```

关键配置

配置项	必填	说明	示例
`backlog_directory`	否	指定任务 Markdown 文件的存放目录，相对于项目根路径	`my-backlog`
`autoCommit`	否	控制任务变更是否自动提交到 Git；无 Git 项目下强制为 false	`false`
`checkActiveBranches`	否	跨分支任务读取的准确性开关；无 Git 项目下强制为 false	`true`
`defaultPort`	否	Web UI 默认监听端口	`3000`
`defaultEditor`	否	打开任务文件时使用的编辑器集成	`code`
`zeroPaddedIds`	否	任务 ID 是否补零格式化	`false`

如何确认成功

运行 backlog --version 能输出版本号，且项目内已生成 backlog 目录与配置文件，说明安装和初始化成功。

常见问题

Q：必须安装 Git 才能用吗？

A：不必。Git 是可选的，运行 backlog init --no-git 即可创建纯文件系统项目，相关 Git 相关配置会自动关闭。

Q：有哪些安装方式？

A：README 提供三种：npm i -g backlog.md、brew install backlog-md、nix run github:MrLesk/Backlog.md。Nix 支持 x86_64-linux、aarch64-linux 和 aarch64-darwin。

Q：怎样让 AI 工具接管任务？

A：初始化向导中可选 CLI instructions（推荐）或 MCP connector，后者可自动配置 Claude Code、Codex、Gemini CLI、Kiro 或 Cursor。

Q：Cursor 应该怎么选？

A：选择 AGENTS.md，或运行 backlog init --agent-instructions cursor，两者目标文件相同；已有的 AGENTS.md 内容会被保留。

注意事项

配置文件优先读取 backlog.config.yml，其次是 backlog/config.yml 或 .backlog/config.yml，最后使用内置默认值。
配置优先级为：CLI 参数 > 项目配置文件 > 内置默认值。
任务文件是纯 Markdown，随 Git 提交、分支、合并自然版本化，属于项目本地内容。
Intel macOS 用户无法使用 Nix 方案，请改用 npm、Bun 或 Homebrew 安装。