Backlog.md

原生支持 Markdown 的任务管理器与看板可视化工具，适用于任何 Git 仓库

npm i -g backlog.md 或 bun add -g backlog.md 或 brew install backlog-md 或 nix run github:MrLesk/Backlog.md

Backlog.md 可以将任意包含 Git 仓库的文件夹转换为一个自包含的项目看板， 完全基于纯 Markdown 文件和零配置的命令行工具。专为规范驱动的 AI 开发而设计——通过结构化任务，让 AI 助手交付可预测的结果。

特性

• 📝 原生 Markdown 任务 -- 将每个问题都以普通的 .md 文件形式进行管理

• 🤖 AI 就绪 -- 兼容 Claude Code、Gemini CLI、Codex、Kiro 以及其他任何符合 MCP 或 CLI 标准的 AI 助手

• 📊 即时终端看板 -- backlog board 命令可在你的终端中实时绘制出看板视图

• 🌐 现代化 Web 界面 -- backlog browser 命令会启动一个简洁美观的 Web UI，用于可视化任务管理

• 🔍 强大的搜索功能 -- 使用 backlog search 命令可在任务、文档和决策中进行模糊搜索

• 📋 丰富的查询命令 -- 轻松查看、列出、筛选或归档任务

• ✅ 完成标准默认设置 -- 为每个新任务添加可复用的检查清单

• 📤 看板导出 -- backlog board export 命令可以生成可分享的 Markdown 报告

• 🔒 100% 私密且离线 -- Backlog 的所有数据完全存储在你的仓库内，你可以完全在本地管理一切

• 💻 跨平台 -- 支持 macOS、Linux 和 Windows

• 🆓 MIT 许可且开源 -- 个人及商业用途均可免费使用

入门指南

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

# 在任意 Git 仓库中初始化
backlog init "我的超棒项目"

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

• MCP 连接器（推荐）— 自动配置 Claude Code、Codex、Gemini CLI、Kiro 或 Cursor，并为你的助手添加工作流说明。
• CLI 命令 — 创建指令文件（CLAUDE.md、AGENTS.md 等），以便助手通过 CLI 使用 Backlog。
• 跳过 — 不进行 AI 设置；仅将 Backlog.md 作为纯粹的任务管理工具使用。

Backlog 的数据会存储在项目本地的 backlog/、.backlog/ 文件夹中，或者通过 backlog.config.yml 配置的自定义相对路径。任务始终是人类可读的 Markdown 文件（例如 task-10 - 添加核心搜索功能.md）。

与 AI 助手协作

这是针对 Claude Code、Codex、Gemini CLI、Kiro 等工具推荐的工作流程——遵循规范驱动的 AI 开发方法。运行 backlog init 并选择 MCP 或 CLI 集成后，按照以下循环操作：

步骤 1 — 描述你的想法。 向助手说明你想构建什么，并请它将工作拆分为多个小任务，每个任务都应有清晰的描述和验收标准。

🤖 请求你的 AI 助手：

我想在网页视图中添加一个搜索功能，能够搜索任务、文档和决策。请将其分解为若干个 Backlog.md 任务。

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

步骤 2 — 每次处理一个任务。 每次与助手对话只处理一个任务，每个任务对应一个 Pull Request。良好的任务拆分意味着每次对话都可以独立完成，不会产生冲突。确保每个任务足够小，能够在一次对话中完成。这样可以避免上下文窗口不足的问题。

步骤 3 — 编写计划再编码。 请助手研究并编写任务的实现计划。务必在实施之前执行此步骤，以确保计划反映当前代码库的状态。

🤖 请求你的 AI 助手：

请只处理 BACK-10 任务。研究代码库并在任务中写下实现计划。等待我的批准后再开始编码。

[!NOTE] 审查检查点 #2 — 阅读计划。这个方案是否合理？批准它，或者要求助手修改。

步骤 4 — 实现并验证。 让助手完成任务的实现。

[!NOTE] 审查检查点 #3 — 审查代码，运行测试，检查代码风格，并确认结果符合预期。

如果输出不够理想：清除计划、笔记和最终总结，重新细化任务描述和验收标准，然后在新的对话中再次执行该任务。

不使用 AI 助手时的操作

将 Backlog.md 作为独立的任务管理工具，通过终端或浏览器进行操作。

# 创建和优化任务
backlog task create "将 Markdown 渲染为看板"
backlog task edit BACK-1 -d "详细背景信息" --ac "明确的验收标准"

# 跟踪工作
backlog task list -s "待办"
backlog search "看板"
backlog board

# 在浏览器中进行可视化操作
backlog browser

你可以随时在 AI 辅助和手动工作流之间切换——两者都基于相同的 Markdown 任务文件。建议通过 Backlog.md 提供的命令行工具（CLI/MCP/Web）来修改任务，而不是直接编辑任务文件，这样可以保持字段类型和元数据的一致性。

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

Web 界面

启动一个现代化、响应式的 Web 界面，用于可视化任务管理：

# 启动 Web 服务器（自动打开浏览器）
backlog browser

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

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

功能：

• 带拖拽功能的交互式看板
• 丰富的表单用于创建和编辑任务
• 带检查清单的交互式验收标准编辑器
• 所有视图实时更新
• 适配桌面和移动设备的响应式设计
• 带确认对话框的任务归档功能
• 与命令行无缝集成——所有更改都会同步到 Markdown 文件中

🔧 MCP 集成（模型上下文协议）

将 Backlog.md 与 Claude Code、Codex、Gemini CLI 和 Kiro 等 AI 编码助手连接的最简单方式是通过 MCP 协议。你可以运行 backlog init（即使你已经初始化过 Backlog.md）来自动设置 MCP 集成，或者按照下面的手动步骤操作。

客户端指南

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

codex mcp add backlog backlog mcp start

gemini mcp add backlog -s user backlog mcp start

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

在所有地方都使用共享的 backlog 服务器名称——MCP 服务器会自动检测当前目录是否已初始化，并在需要时回退到 backlog://init-required。

手动配置

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

如果您的 IDE 无法为 MCP 服务器设置进程工作目录，请按照上述方式设置 BACKLOG_CWD。如果您的 IDE 支持自定义参数但不支持环境变量，您也可以使用 ["mcp", "start", "--cwd", "/absolute/path/to/your/project"]。

[!重要] 手动添加 MCP 服务器时，应在 CLAUDE.md/AGENTS.md 文件中添加一些额外的说明，以告知代理关于 Backlog.md 的信息。 使用 backlog init 时不需要此步骤，因为它会自动添加这些说明。 Backlog.md 中关于代理的说明可在 /src/guidelines/mcp/agent-nudge.md 找到。

连接成功后，代理可以通过资源 backlog://docs/task-workflow 阅读 Backlog.md 工作流说明。 请在您的 AI 工具（Claude Code、Codex、Kiro）中使用 /mcp 命令来验证连接是否正常工作。

CLI 参考

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

快速示例：backlog task create、backlog task list、backlog task edit、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 以及是否应自动打开浏览器。

如果您跳过向导（在初始化过程中回答“否”），则会应用 Backlog.md 自带的安全默认值：

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

无论何时您再次访问 backlog init 或重新运行 backlog config，向导都会预先填充您当前的值，以便您只需调整已更改的部分。

完成标准默认值

您可以通过 backlog config（或在 backlog init 的高级设置中）、Web UI（设置 → 完成标准默认值）或直接编辑项目配置文件来设置项目范围内的 DoD 项目：

definition_of_done:
  - 测试通过
  - 文档已更新
  - 未引入回归

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

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

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

许可证

Backlog.md 采用 MIT 许可证 发布——您可以自由使用，但需注明出处。详情请参阅 LICENSE。

Backlog.md 快速上手指南

Backlog.md 是一个基于 Markdown 的任务管理器和看板可视化工具，专为 Git 仓库设计。它将任务存储为纯文本 .md 文件，支持零配置 CLI、终端看板、Web 界面以及与 Claude Code、Gemini 等 AI 编程助手的深度集成。

环境准备

• 操作系统：macOS, Linux, Windows
• 前置依赖：
  • 已安装 Git 并初始化了仓库。
  • 已安装以下任一包管理器：Node.js (npm), Bun, 或 Homebrew。
• AI 集成（可选）：如需与 AI 助手联动，需安装支持的客户端（如 Claude Code, Codex, Gemini CLI, Kiro 等）。

安装步骤

选择以下任意一种方式全局安装 Backlog.md：

# 使用 npm
npm i -g backlog.md

# 使用 Bun
bun add -g backlog.md

# 使用 Homebrew (macOS/Linux)
brew install backlog-md

# 使用 Nix
nix run github:MrLesk/Backlog.md

基本使用

1. 初始化项目

进入你的 Git 仓库目录，运行初始化命令。向导将询问你如何连接 AI 工具（推荐选择 MCP 连接器以自动配置 AI 工作流，或选择 Skip 仅作为普通任务管理器使用）。

backlog init "My Awesome Project"

初始化后，任务数据将存储在项目本地的 backlog/ 或 .backlog/ 文件夹中，所有任务均为人类可读的 Markdown 文件。

2. 创建与管理任务

你可以使用 CLI 命令快速创建和查看任务：

# 创建新任务
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 search "kanban"

3. 可视化看板

Backlog.md 提供两种看板视图：

终端看板（即时预览）：

backlog board

Web 界面（功能更丰富，支持拖拽）：

# 启动 Web 服务并自动打开浏览器
backlog browser

# 指定端口
backlog browser --port 8080

4. 与 AI 助手协作（推荐工作流）

如果你选择了 MCP 或 CLI 集成模式，可以遵循“规格驱动开发”流程：

1. 分解任务：让 AI 将大需求拆分为小的 Backlog.md 任务。

   示例提示词："I want to add a search feature... Please decompose this into small Backlog.md tasks."

2. 逐个执行：每次会话只处理一个任务，避免上下文溢出。
3. 先计划后编码：要求 AI 在任务文件中写入实施计划，经你批准后再编码。

   示例提示词："Work on BACK-10 only. Research the codebase and write an implementation plan in the task. Wait for my approval before coding."

4. 实现与验证：让 AI 执行代码并验证结果。

注意：建议通过 Backlog.md 的命令（CLI/MCP/Web）修改任务，以确保元数据和字段类型的一致性。