Backlog.md

让 AI Agent 在你的代码仓库里持续工作。

Markdown Tasks · Git Native · Human Review · AI Memory

🇺🇸 English

npm i -g @kuwork/backlog.md 或 bun add -g @kuwork/backlog.md 或 brew install backlog-md（上游）或 nix run github:MrLesk/Backlog.md（上游）

---

AI 会写代码，但谁告诉它下一步该做什么？

Backlog.md 把任务、验收标准、实施计划和执行记录保存为仓库里的 Markdown 文件。

AI Agent 可以从任务开始工作，人类可以在关键节点审查和批准，而每一次结对执行产生的知识，还可以继续沉淀到 LLM Wiki。

从任务规划，到 AI 执行，再到项目知识沉淀

---

Backlog.md 让任何含 Git 仓库的文件夹都能成为独立的项目看板
由纯 Markdown 文件和零配置 CLI 驱动。
为规范驱动的 AI 开发量身打造 —— 通过结构化任务让 AI 智能体产出可预期的结果。

---

Why Backlog.md?

AI 编程正在改变软件开发。

问题已经不再只是：

“AI 能不能写代码？”

而是：

“如何让 AI 在一个真实项目里，持续、可控、可审查地工作？”

Backlog.md 用一个简单的原则解决这个问题：

把 AI 的工作变成可以阅读、可以审查、可以追踪的任务。

🧠 AI Native

Backlog.md 为 Claude Code、Codex、Gemini CLI、Kiro 以及其他支持 CLI / MCP 的 AI Agent 提供结构化工作流。

📝 Markdown Native

每一个任务都是普通的 .md 文件。

没有专有数据库。

没有黑盒。

任务可以被人阅读，也可以被 Git diff、review、commit 和追踪。

🔀 Git Native

Backlog 和代码放在同一个项目里。

your-project/
├── src/
├── tests/
├── backlog/
│   ├── tasks/
│   ├── docs/
│   ├── decisions/
│   └── wiki/
└── ...

任务与代码一起进入版本控制。

🔒 Local & Offline First

数据保存在项目本地。

没有强制云端账号，没有订阅要求。

---

AI Agent 是怎样工作的？

Backlog.md 不只是让 AI “接任务”。

它把 AI 工作拆成几个可以被人类检查的阶段：

flowchart LR
    A["💡 Idea<br/>我想做什么"] --> B["🤖 AI<br/>拆解任务"]
    B --> C["📋 Task Spec<br/>描述 + 验收标准"]
    C --> D{"👤 Review #1<br/>任务是否正确？"}
    D -->|修改| B
    D -->|批准| E["🔎 AI Research<br/>研究代码库"]
    E --> F["📝 Implementation Plan<br/>实施计划"]
    F --> G{"👤 Review #2<br/>计划是否合理？"}
    G -->|修改| E
    G -->|批准| H["⚙️ AI Implementation<br/>开始编码"]
    H --> I["🧪 Test & Verify"]
    I --> J{"👤 Review #3<br/>结果是否符合预期？"}
    J -->|继续修正| H
    J -->|完成| K["🧠 Wiki<br/>知识沉淀"]

Loading

三个关键的人类审查点

01 — Review the Spec

AI 写代码之前，先审查：

• 任务描述
• 验收标准
• 任务边界

02 — Review the Plan

AI 研究代码库之后，把实施计划写进任务。

你批准之后，AI 才开始编码。

03 — Review the Result

代码完成之后：

• Review diff
• 运行测试
• 检查验收标准
• 验证最终结果

人类负责方向和判断，AI 负责拆解和执行。

---

功能特性

• 📝 本地 Markdown 任务 —— 每个事项都是一份纯 .md 文件
• 🤖 为 AI 而生 —— 兼容 Claude Code、Gemini CLI、Codex、Kiro 及任何其他支持 MCP 或 CLI 的 AI 助手
• 📊 即时终端看板 —— backlog board 在终端中实时呈现看板
• 🌐 现代 Web 界面 —— backlog browser 启动精致的 Web UI，让任务管理一目了然
• 🌍 多语言界面 —— Web UI 支持英语、日语、简体中文、繁体中文，在设置中一键切换
• 🧠 LLM Wiki 知识库 —— AI 自动维护的结对笔记本，支持摄取、查询与健康检查
• 📄 富文本粘贴与文档上传 —— 从 Word、网页直接粘贴为 Markdown，支持 .docx 上传与图片自动提取
• 📅 跟踪甘特图 —— 基于 plannedStart / plannedEnd / actualStart / actualEnd 时间字段的可视化时间线，计划与实际双层对比
• 🔍 强大的搜索功能 —— backlog search 可在任务、文档和决策间进行模糊搜索
• 📋 丰富的查询命令 —— 轻松查看、列出、筛选或归档任务
• ✅ 完成定义默认值 —— 为每个新任务添加可复用的检查清单
• 📤 看板导出 —— backlog board export 创建可共享的 Markdown 报告
• 🔒 100% 隐私保护 & 离线储存 —— backlog 完全存储在您的仓库内部，所有操作都在本地完成
• 💻 跨平台 —— 支持 macOS、Linux 和 Windows
• 🆓 MIT 许可证 & 开源 —— 个人或商业用途均免费

---

🧠 LLM Wiki 知识库

Backlog.md 内置由 LLM 自动维护的 Wiki 知识库，让人类与 AI 的每一次结对执行都沉淀为可复用的知识结晶。

结对编程思路

人类主导策略 → AI 拆解任务 → 结对执行 → 知识自动沉淀到 Wiki

头脑风暴 → doc → AI 规划 → tasks → 结对执行 → wiki

层级	载体	内容	所有者
规划层	backlog/docs/	开发策略、技术方案	人类主导，AI 辅助
执行层	backlog/tasks/	具体任务、验收标准	AI 创建，人类审核
记忆层	backlog/wiki/	知识结晶、模式提取	AI 维护，人类审阅

如何使用

Wiki 由 LLM 全自动维护，无需手动创建文件。

安装 Wiki Skill

Backlog.md 将 Wiki 工作流打包成 llm-wiki-for-backlog skill。要让当前 AI 助手识别并使用 Wiki 触发词，先安装 skill：

backlog wiki install claude   # Claude Code / Claude Desktop
backlog wiki install codex    # OpenAI Codex CLI
backlog wiki install agents   # 通用 Agents 目录

使用 --dry-run 预览安装步骤，--force 覆盖已存在的安装。

在对话中触发以下关键词，AI 即会接管：

触发词	作用
build wiki / init wiki / 搭建知识库	初始化 Wiki 目录结构，注入工作流指引
ingest / process source / 摄取	将 backlog 源文件（tasks/docs/decisions 等）吸入 Wiki
wiki query / 知识库查询	基于已积累的知识回答问题、生成报告
lint wiki / health check / 检查 wiki	扫描矛盾、孤儿页面和过时内容

Wiki 遵循非正式、轻量、AI 维护、可质疑四大原则——它不是企业知识库，而是你和 AI 的"结对笔记本"。

---

快速入门

# 安装
bun i -g @kuwork/backlog.md
# 或：npm i -g @kuwork/backlog.md
# 或：brew install backlog-md

# 在任何 Git 仓库中初始化
backlog init "My Awesome Project"

# 或无 Git 初始化，用于本地/非代码项目
backlog init "Personal Planning" --no-git

初始化向导会询问您希望如何接入 AI 工具：

• CLI 指令（推荐）—— 创建简短的指令文件，告诉智能体运行 backlog instructions overview。
• MCP 连接器 —— 如果您更偏好 MCP，可以自动配置 Claude Code、Codex、Gemini CLI、Kiro 或 Cursor。
• 跳过 —— 不设置 AI；仅将 Backlog.md 作为任务管理器使用。

Backlog 数据存储在项目本地的 backlog 文件夹中，例如 backlog/、.backlog/，或通过 backlog.config.yml 配置的项目相对路径。任务仍是可直接阅读的 Markdown 文件（例如 task-10 - Add core search functionality.md）。Git 是可选的：backlog init --no-git 创建纯文件系统项目，并禁用跨分支检查、远程操作和自动提交。

---

与 AI 智能体协作

这是针对 Claude Code、Codex、Gemini CLI、Kiro 及类似工具的推荐工作流 —— 遵循规范驱动的 AI 开发方法。
运行 backlog init 后，智能体应首先运行 backlog instructions overview，然后按以下循环工作：

步骤 1 —— 描述您的想法。 告诉智能体您想构建什么，并要求它将工作拆分为小任务，附上清晰的描述和验收标准。

🤖 询问您的 AI 智能体：

我想为 Web 视图添加一个搜索功能，用于搜索任务、文档和决策。请将其分解为小的 Backlog.md 任务。

Note

审查检查点 #1 —— 阅读任务描述和验收标准。

步骤 2 —— 一次一个任务。 每个 AI 会话只处理一个任务，一个任务对应一个 PR。良好的任务拆分意味着每个会话可以独立工作、互不冲突。确保每个任务足够小，能在一次对话中完成，避免超出上下文窗口上限。

步骤 3 —— 编码前先规划。 要求智能体调研代码库，并在任务中编写实施计划。就在实施前执行这一步，确保计划反映代码库的当前状态。

🤖 询问您的 AI 智能体：

只处理 BACK-10。研究代码库并在任务中编写实施计划。在编码前等待我的批准。

Note

审查检查点 #2 —— 阅读计划。方法是否合理？批准或要求智能体修正。

步骤 4 —— 实施和验证。 让智能体实施任务。

Note

审查检查点 #3 —— 审查代码、运行测试、检查代码规范，并验证结果是否符合您的预期。

如果结果不理想：清除计划/备注/最终总结，完善任务描述和验收标准，然后在新的会话中重新处理该任务。

---

不与 AI 智能体协作

直接在终端或浏览器中使用 Backlog.md 管理任务。

# 创建和完善任务
backlog task create "Render markdown as kanban"
backlog task edit BACK-1 -d "Detailed context" --ac "Clear acceptance criteria"

# 跟踪工作
backlog task list -s "To Do"
backlog task edit BACK-1 --comment "Can we split the UI work into a separate PR?" --comment-author @sara
backlog task edit BACK-1 --remove-comment 2  # Remove comment #2; --clear-comments removes all
backlog search "kanban"
backlog board

# 在浏览器中可视化工作
backlog browser

您可以随时在 AI 辅助和手动工作流之间切换 —— 两者都基于相同的 Markdown 任务文件。建议通过 Backlog.md 命令（CLI/MCP/Web）修改任务，而不是手动编辑任务文件，以保持字段类型和元数据的一致性。任务可记录项目根目录下的已修改文件，之后通过 backlog search --modified-file src/path.ts --plain 即可找到。使用任务评论进行讨论和审阅记录；评论正文支持 Markdown，但单独的 --- 行被保留为评论分隔符。使用执行记录跟踪执行进度，使用最终总结编写类似 PR 的完成说明。

了解更多： CLI 参考 | 高级配置

---

Web 界面

启动现代、响应式的 Web 界面，用于可视化任务管理（默认仅绑定本机回环地址 127.0.0.1；如需局域网访问，使用 --host 0.0.0.0，注意 API 未认证、请谨慎在不可信网络暴露）：

# 启动 Web 服务器（自动打开浏览器，仅本机可访问）
backlog browser

# 自定义端口
backlog browser --port 8080

# 不自动打开浏览器
backlog browser --no-open

# 开放局域网访问（危险：API 未认证）
backlog browser --host 0.0.0.0

# 使用指定浏览器打开（BROWSER 环境变量；devcontainer 场景常用）
BROWSER="/path/to/browser" backlog browser

功能特性：

• 支持拖放的交互式看板
• 带有丰富表单的任务创建和编辑
• 带有检查清单的交互式验收标准编辑器
• 所有视图的实时更新
• 支持桌面和移动设备的响应式设计
• 带确认对话框的任务归档
• 与 CLI 无缝集成 —— 所有更改与 Markdown 文件同步

甘特图视图

backlog browser 内置甘特图视图，支持五种时间粒度（日/周/月/季度/年），纯 React/CSS 实现，零外部依赖：

• 计划时间：plannedStart / plannedEnd（YYYY-MM-DD）绘制计划边框
• 实际时间：actualStart / actualEnd（YYYY-MM-DD HH:MM UTC）自动随状态变更填充，绘制状态色实心条
• 跟踪对比：同一行叠加计划边框与实际条，延期/提前一目了然
• 依赖箭头：SVG 智能连接任务依赖关系

时间字段支持 CLI 直接设置或清除：

# 计划字段（Date-only）
backlog task edit BACK-10 --planned-start 2026-06-01 --planned-end 2026-06-07 --due-date 2026-06-10

# 实际字段（Date-time UTC），状态变更时自动填充
backlog task edit BACK-10 --status "In Progress"  # actualStart 自动设为当前时间

# 清除任意时间字段
backlog task edit BACK-10 --clear-due-date --clear-planned-start --clear-planned-end --clear-actual-start --clear-actual-end

# 里程碑时间字段清除
backlog milestone edit "Release 1.0" --clear-due-date --clear-planned-start --clear-planned-end

要使 Web UI 作为自动启动的本地服务持续运行，请参阅 将 Backlog.md 作为服务运行。

---

🔧 MCP 集成（Model Context Protocol）

CLI 指令是默认的 AI 接入方式。如果您明确偏好 MCP 连接器，Backlog.md 仍支持 Claude Code、Codex、Gemini CLI 和 Kiro 等 AI 编码助手。
您可以运行 backlog init（即使您已经初始化了 Backlog.md）并选择 MCP 集成，或按照以下手动步骤操作。

客户端指南

Claude Code

claude mcp add backlog --scope user -- backlog mcp start

Codex

codex mcp add backlog -- backlog mcp start

Gemini CLI

gemini mcp add backlog -s user backlog mcp start

Kiro

kiro-cli mcp add --scope global --name backlog --command backlog --args mcp,start

处处统一使用 backlog 作为服务器名称。服务器会从客户端的 MCP roots 中查找当前项目，并在切换工作区或 worktree 时重新解析。找到项目前，它会提供 backlog://init-required。一个用户级服务器即可覆盖所有仓库。

手动配置

{
  "mcpServers": {
    "backlog": {
      "command": "backlog",
      "args": ["mcp", "start"],
      "env": {
        "BACKLOG_CWD": "/absolute/path/to/your/project"
      }
    }
  }
}

设置 BACKLOG_CWD 可将服务器固定到单个项目并停止工作区跟随。当你始终想定位同一个 backlog，或客户端无法上报 MCP roots 时使用它。
如果您的 IDE 支持自定义参数但不支持环境变量，您也可以使用 ["mcp", "start", "--cwd", "/absolute/path/to/your/project"]。

Important

手动添加 MCP 服务器时，建议在 CLAUDE.md/AGENTS.md 文件中补充简短说明，让智能体读取 backlog://workflow/overview。
使用 backlog init 时无需此步骤，因为它会自动添加这些说明。
基于 CLI 的 setup，请使用 backlog instructions overview 获取当前工作流指引。

连接后，智能体可以通过 backlog://workflow/overview 读取 Backlog.md 工作流说明，详细指南位于 backlog://workflow/task-creation、backlog://workflow/task-execution 和 backlog://workflow/task-finalization。
在您的 AI 工具（Claude Code、Codex、Kiro）中使用 /mcp 命令验证连接是否正常工作。

---

CLI 参考

完整命令参考 —— 任务管理、搜索、看板、文档、决策等：CLI-INSTRUCTIONS.md

快速示例：backlog、backlog instructions、backlog task create、backlog task list、backlog task edit、backlog milestone add、backlog milestone edit、backlog milestone remove、backlog search、backlog board、backlog browser。

完整帮助：backlog --help

---

配置

Backlog.md 的配置按以下层次叠加（优先级从高到低）：

1. CLI 参数
2. 项目配置文件：
   • 存在时使用 backlog.config.yml
   • 否则使用 backlog/config.yml 或 .backlog/config.yml
3. 内置默认值

交互式向导（backlog config）

不带参数运行 backlog config 以启动完整的交互式向导。这与在 backlog init 中选择开启高级设置时触发的体验相同，它会引导您完成所有配置项：

• 跨分支准确性：checkActiveBranches、remoteOperations 和 activeBranchDays。
• Git 工作流：autoCommit 和 bypassGitHooks。
• ID 格式化：启用 zeroPaddedIds 或设置其长度。
• 编辑器集成：选择一个带可用性检查的 defaultEditor。
• 完成定义默认值：交互式添加/删除/重新排序/清除项目级 definition_of_done 检查清单项。
• Web UI 默认值：选择 defaultPort 以及是否启用 autoOpenBrowser。

跳过向导（在 init 期间回答"否"）将应用 Backlog.md 内置的安全默认设置：

• checkActiveBranches=true、remoteOperations=true、activeBranchDays=30。
• autoCommit=false、bypassGitHooks=false。
• zeroPaddedIds 禁用。
• defaultEditor 未设置（回退到您的环境配置）。
• defaultPort=6420、autoOpenBrowser=true。

对于纯文件系统项目，运行 backlog init --no-git。Backlog.md 不会运行 git init，保存的配置会强制设置 checkActiveBranches=false、remoteOperations=false 和 autoCommit=false，以便 CLI、Web 和 MCP 本地文件工作流不依赖 Git 仓库。

每当您重新访问 backlog init 或重新运行 backlog config 时，向导都会用您当前的值预填充提示，以便您只调整已更改的内容。

autoCommit 自动提交

开启后（backlog config set autoCommit true 或配置文件 autoCommit: true），以下操作会每次写入自动产生一个 Git 提交：任务创建/编辑/批量更新、任务归档/完成、Draft 提升/降级/归档、决策与文档的创建和更新、里程碑归档/重命名、以及 backlog init 写入的 AI 指令文件。

注意事项：

• 提交只包含本次操作触碰的文件（新文件 + 被替换/移动的旧路径），不会整目录暂存，也不会卷入或清空您预先暂存（staged）的其他改动，未跟踪（untracked）文件保持原样。
• 必须初始化 Git 才能使用；backlog init --no-git 的纯文件系统项目强制禁用自动提交。
• 提交失败不丢数据：文件已写入磁盘，只是未提交，可用 git status 查看并手动补提交。里程碑归档/重命名失败时会自动回滚文件移动。
• bypassGitHooks：默认会触发仓库 pre-commit 钩子，可能因 lint/格式化失败而阻塞提交；需要跳过时设置 backlog config set bypassGitHooks true。
• 提交信息：任务按操作区分（Create task / Update task / Archive task）；决策与文档区分创建与更新（Add decision / Update decision、Add document / Update document）；里程碑与 Draft 使用 backlog: 前缀。
• 推荐：单人/自动化工作流开启自动提交可获得「一操作一提交」的干净历史；多人协作或需要精细控制历史时可保持关闭（默认），手动 git add/git commit——两种方式互不污染。

完成定义默认值

使用 backlog config（或在 backlog init 高级设置期间）、在 Web UI 中（设置 → 完成定义默认值），或直接编辑项目配置文件来设置项目范围的 DoD 项：

definition_of_done:
  - Tests pass
  - Documentation updated
  - No regressions introduced

当项目使用根目录配置自动发现时，请编辑 backlog.config.yml 而不是 backlog/config.yml。

这些检查项默认添加到每个新任务中。您可以在创建时使用 --dod 添加更多，或使用 --no-dod-defaults 为单个任务禁用默认值。

有关完整配置参考（所有选项、命令和详细说明），请参阅 ADVANCED-CONFIG.md。

---

🔧 故障排除

Apple Silicon (macOS)

在 M 系列 Mac 上，当 Node、Bun 或 Homebrew 以 Rosetta（x64 模拟）方式运行，却安装了 Intel 版而非 arm64 版二进制时，backlog 可能报 illegal hardware instruction 或 Binary package not installed for darwin-...。启动器会运行实际已安装的任一 darwin 变体（arm64 或 x64），但最可靠的修复方式是安装原生架构版本。

先检查各工具报告的架构：

uname -m                            # arm64 = Apple Silicon 硬件；x86_64 = Intel 或 Rosetta shell
node -p process.arch                # 你的 Node/Bun 运行时架构
sysctl -in sysctl.proc_translated   # 1 = 当前 shell 运行于 Rosetta 之下
which brew                          # /opt/homebrew = arm64 brew，/usr/local = Intel brew

若架构不一致，用原生架构重新安装：

# Homebrew：确保 `which brew` 输出 /opt/homebrew，然后（上游）
brew reinstall backlog-md

# npm
arch -arm64 npm i -g @kuwork/backlog.md

# Bun
arch -arm64 bun add -g @kuwork/backlog.md

如果刻意在 Rosetta 下运行 x64 Node 也可以：backlog 会回退到实际已安装的任一 backlog.md-darwin-* 包。

---

🌐 社区工具

• vscode-backlog-md - VS Code 扩展，包含事项面板、看板视图和编辑功能。(ysamlan/vscode-backlog-md)

---

许可证

Backlog.md 采用 MIT 许可证发布 —— 随意使用，只需注明出处。请参阅 LICENSE。