Backlog.md

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

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

---

Backlog.md 将任何包含 Git 仓库的文件夹变成一个自包含的项目看板，由纯 Markdown 文件和零配置 CLI 驱动。 专为**规范驱动的 AI 开发（spec‑driven AI development）**而构建 —— 通过结构化的任务，让 AI Agent 交付可预测的结果。

功能特性

• 📝 Markdown 原生任务 —— 将每个 Issue 管理为一个纯 .md 文件

• 🤖 AI 就绪 —— 兼容 Claude Code、Gemini CLI、Codex、Kiro 以及任何其他支持 MCP 或 CLI 的 AI 助手

• 📊 即时终端看板 —— backlog board 可在你的 Shell 中实时呈现看板

• 🌐 现代 Web 界面 —— backlog browser 可启动简洁的 Web UI，用于可视化任务管理

• 🔍 强大的搜索 —— 通过 backlog search 对任务、文档和决策进行模糊搜索

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

• ✅ 默认“完成定义”（Definition of Done） —— 为每个新任务添加可复用的清单

• 📤 看板导出 —— 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 "My Awesome Project"

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

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

Backlog 数据存储在项目本地的文件夹中，例如 backlog/、.backlog/，或是通过 backlog.config.yml 配置的自定义项目路径。任务仍以人类可读的 Markdown 文件形式存在（例如 task-10 - Add core search functionality.md）。

---

与 AI Agent 协作

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

第一步 — 描述你的想法。 告诉 Agent 你想要构建的内容，并要求它将工作拆解为带有清晰描述和验收标准（Acceptance Criteria）的小任务。

🤖 询问你的 AI Agent：

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

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

第二步 — 每次完成一个任务。 在每个 Agent 会话中只处理一个任务，每个任务对应一个 PR。良好的任务拆解意味着每个会话都可以独立工作而不会产生冲突。确保每个任务足够小，可以在单次对话中完成，以避免超出上下文窗口（context window）。

第三步 — 编码前进行规划。 要求 Agent 研究代码库并在任务中编写实现计划。在实施前立即执行此操作，以确保计划反映代码库的当前状态。

🤖 询问你的 AI Agent：

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

[!NOTE] 检查点 #2 — 阅读计划。方案合理吗？批准它或要求 Agent 修改。

第四步 — 实施并验证。 让 Agent 执行任务。

[!NOTE] 检查点 #3 — 审查代码、运行测试、检查 Linting，并验证结果是否符合你的预期。

如果输出效果不理想：清除计划/笔记/最终总结，完善任务描述和验收标准，然后在新的会话中重新运行该任务。

---

在没有 AI Agent 的情况下使用

将 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 search "kanban"
backlog board

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

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

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

---

Web 界面