Backlog.md 将任何包含 Git 仓库的文件夹变成一个 自包含的项目看板
由纯 Markdown 文件和零配置 CLI 驱动。
工具介绍
✨ 功能特性
- 📝 Markdown 原生任务 —— 每个问题都用
.md文件管理 - 🔒 100% 私有 & 离线 —— backlog 完全存在于你的仓库内部
- 📊 即时终端看板 ——
backlog board在终端中绘制实时看板 - 📤 看板导出 ——
backlog board export创建可分享的 Markdown 报告 - 🌐 现代化 Web 界面 ——
backlog browser启动简洁的网页 UI，进行任务可视化管理 - 🤖 AI 就绪 CLI —— “Claude，请接手任务 33”
- 🔍 丰富的查询命令 —— 轻松查看、筛选、归档任务
- 💻 跨平台支持 —— 可运行在 macOS、Linux、Windows
- 🆓 MIT 许可开源 —— 免费用于个人或商业
🚀 五分钟上手
# 1. 安装 Backlog.md
bun/npm i -g backlog.md 或 brew install backlog-md
# 2. 初始化仓库和 backlog
backlog init "我的项目"
# 3. 捕捉任务
backlog task create "将 markdown 渲染为看板"
# 4. 查看进展
backlog board view 或 backlog browser
# 5. 使用 Claude、Gemini、Codex 或 Jules 创建任务
Claude，我想在 Web 界面里增加搜索功能，搜索范围包括：
* 任务
* 文档
* 决策
请创建相应的任务。
# 6. 将任务交给 AI 执行
Claude，请实现与 Web 搜索功能相关的所有任务 (task-10, task-11, task-12)
* 在写代码前使用 'ultrathink mode' 规划实现方案
* 任务允许时使用多个子代理并行
所有数据都会保存在 backlog 文件夹下，格式为 task-<task-id> - <task-title>.md（例如 task-10 - 添加核心搜索功能.md）。
🌐 Web 界面
# 启动 Web 服务（自动打开浏览器）
backlog browser
# 自定义端口
backlog browser --port 8080
# 不自动打开浏览器
backlog browser --no-open
Web 界面功能：
- 交互式看板，支持拖拽
- 任务创建与编辑，带表单与验证
- 实时更新
- 响应式设计，桌面/移动端兼容
- 任务归档，带确认提示
- 无缝 CLI 集成 —— 与 Markdown 文件保持同步
🖥️ CLI 参考
项目初始化
| 操作 | 示例 |
|---|---|
| 初始化项目 | backlog init [project-name] |
| 重新初始化 | backlog init |
任务管理
| 操作 | 示例 |
|---|---|
| 创建任务 | backlog task create "添加 OAuth 系统" |
| 带描述 | backlog task create "功能" -d "添加认证系统" |
| 带负责人 | backlog task create "功能" -a @sara |
| 带状态 | backlog task create "功能" -s "进行中" |
| 带标签 | backlog task create "功能" -l auth,backend |
| 带优先级 | backlog task create "功能" --priority high |
| 带计划 | backlog task create "功能" --plan "1. 调研\n2. 实现" |
| 带验收标准 | backlog task create "功能" --ac "必须可用,必须测试" |
| 带备注 | backlog task create "功能" --notes "已开始初步调研" |
| 带依赖 | backlog task create "功能" --dep task-1,task-2 |
| 创建子任务 | backlog task create -p 14 "支持 Google 登录" |
| 所有选项 | backlog task create ... |
| 列出任务 | backlog task list [-s <状态>] [-a <负责人>] [-p <父任务>] |
| 查看详情 | backlog task 7 |
| 编辑任务 | backlog task edit 7 -a @sara -l auth,backend |
| 添加计划 | backlog task edit 7 --plan "实现方案" |
| 添加/删除/勾选验收标准 | backlog task edit 7 --ac "..." --remove-ac 2 --check-ac 1 |
| 添加备注 | backlog task edit 7 --notes "完成了 X，正在做 Y" |
| 添加依赖 | backlog task edit 7 --dep task-1 --dep task-2 |
| 归档任务 | backlog task archive 7 |
草稿工作流
| 操作 | 示例 |
|---|---|
| 创建草稿 | backlog task create "功能" --draft |
| 草稿流 | backlog draft create "GraphQL 调研" → backlog draft promote 3.1 |
| 降级为草稿 | backlog task demote <id> |
看板操作
| 操作 | 示例 |
|---|---|
| 打开看板 | backlog board |
| 导出看板 | backlog board export [文件名] |
| 带版本导出 | backlog board export --export-version "v1.0.0" |
统计 & 概览
| 操作 | 示例 |
|---|---|
| 项目概览 | backlog overview |
文档管理
| 操作 | 示例 |
|---|---|
| 创建文档 | backlog doc create "API 指南" |
| 带路径 | backlog doc create "安装指南" -p guides/setup |
| 带类型 | backlog doc create "架构设计" -t technical |
| 列出文档 | backlog doc list |
| 查看文档 | backlog doc view doc-1 |
决策记录
| 操作 | 示例 |
|---|---|
| 创建决策 | backlog decision create "使用 PostgreSQL 作为主库" |
| 带状态 | backlog decision create "迁移到 TypeScript" -s proposed |
AI 代理指令
| 操作 | 示例 |
|---|---|
| 更新代理文件 | backlog agents --update-instructions |
维护
| 操作 | 示例 |
|---|---|
| 清理已完成任务 | backlog cleanup |
⚙️ 配置
配置命令
| 操作 | 示例 |
|---|---|
| 查看所有配置 | backlog config list |
| 获取单个配置 | backlog config get defaultEditor |
| 设置配置值 | backlog config set defaultEditor "code --wait" |
| 启用自动提交 | backlog config set autoCommit true |
| 跳过 git hooks | backlog config set bypassGitHooks true |
| 开启跨分支检查 | backlog config set checkActiveBranches true |
| 设置活跃分支天数 | backlog config set activeBranchDays 30 |
可用配置选项
| 键 | 作用 | 默认值 |
|---|---|---|
defaultAssignee | 默认负责人 | [] |
defaultStatus | 第一个列状态 | To Do |
statuses | 看板列 | [To Do, In Progress, Done] |
dateFormat | 日期时间格式 | yyyy-mm-dd hh:mm |
timezonePreference | 时区 | UTC |
includeDatetimeInDates | 新建日期是否包含时间 | true |
defaultEditor | 编辑器 | 平台默认 |
defaultPort | Web UI 端口 | 6420 |
autoOpenBrowser | 是否自动打开浏览器 | true |
remoteOperations | 启用远程 git 操作 | true |
autoCommit | 自动提交任务变更 | false |
bypassGitHooks | 跳过 git hooks | false |
zeroPaddedIds | ID 是否零填充 | (禁用) |
checkActiveBranches | 跨分支检查任务状态 | true |
activeBranchDays | 活跃分支天数 | 30 |
📤 共享与导出
看板导出
| 操作 | 示例 |
|---|---|
| 导出到默认文件 | backlog board export |
| 导出到自定义文件 | backlog board export project-status.md |
| 强制覆盖已有文件 | backlog board export --force |
| 导出到 README.md | backlog board export --readme |
| 导出并带版本号 | backlog board export --export-version "v1.2.3" |
| 导出到 README 并带版本号 | backlog board export --readme --export-version "Release 2024.12.1-beta" |
📊 项目状态示例 (v1.8.3)
由 Backlog.md 自动生成
| 待办 | 进行中 | 已完成 |
|---|---|---|
| TASK-228 - 替换 @uiw/react-md-editor 为 TOAST UI Editor #web-ui #enhancement #editor | └─ TASK-24.1 - CLI: 看板里程碑视图 [@codex] | TASK-232 - 修复 Nix 构建缺失 libstdc++.so.6 |
| TASK-227 - Web UI: 交互式验收标准编辑器 | TASK-231 - 修复状态分组大小写不敏感问题 | |
| TASK-222 - 改进 Web UI 中任务与子任务可视化 | TASK-230 - CLI 添加 --plain 参数 | |
| TASK-217 - 拖拽式 Web UI 序列视图 | TASK-226 - CLI 验收标准按索引增删 | |
| TASK-216 - 序列 API 与 Web UI | TASK-225 - 修复 CLI board 忽略配置问题 | |
| TASK-215 - 序列 TUI 界面 | ||
| TASK-214 - CLI 列出序列（纯文本） | ||
| TASK-213 - 从任务依赖计算序列 | ||
| TASK-208 - Web UI 支持粘贴为 Markdown | ||
| TASK-200 - 初始化时集成 Claude Code |
好的，我会把你提供的整个内容一次性完整翻译成中文。以下是译文：
安装方法
1️⃣ 前置条件
验证 Node.js 和 npm
打开 PowerShell 或 命令提示符 (CMD) ，输入：
node -v
npm -v
如果能显示版本号，说明安装成功。
2️⃣ 安装 Backlog.md
在 PowerShell 输入：
npm install -g backlog.md
安装完成后，输入：
backlog --help
如果能看到命令帮助菜单，说明安装成功 🎉。
3️⃣ 初始化项目
进入你要管理的 Git 仓库目录（或者新建一个空目录）：
cd D:\Projects\MyApp
初始化 Backlog.md：
backlog init "MyApp"
👉 系统会问你一些问题，比如：
- 项目名称
- 是否启用自动提交到 Git
- 默认编辑器（一般是 VSCode → 输入
code --wait） - Web UI 端口
初始化完成后，会在仓库里生成一个 backlog/ 文件夹。
4️⃣ 创建任务
在终端运行：
backlog task create "实现用户登录功能"
会在 backlog/ 目录下生成一个 Markdown 文件，比如：
backlog/task-1 - 实现用户登录功能.md
5️⃣ 查看任务看板
在终端运行：
backlog board
👉 会显示一个 终端版看板，用方向键选择任务，按 E 可以编辑。
6️⃣ 启动 Web 界面
如果你想在浏览器里可视化任务管理，运行：
backlog browser
默认会自动打开浏览器，地址一般是：
👉 http://localhost:6420
你可以看到一个 交互式看板，支持拖拽任务。
7️⃣ 进阶功能（可选）
- 导出看板到 Markdown
backlog board export README.md
- 任务带描述、负责人、标签
backlog task create "接入 OAuth 登录" -d "支持 Google 登录" -a @me -l auth,backend
- 归档已完成任务
backlog cleanup
项目经理 Backlog 代理说明
名称: project-manager-backlog
描述: 当你需要使用 backlog.md CLI 工具来管理项目任务时，请使用此代理。包括创建新任务、编辑任务、确保任务符合正确的格式和指南、将大型任务拆解为原子单元，以及维护项目的任务管理工作流。
示例：
- 场景: 用户想创建一个添加功能的任务。
用户: "我需要在项目里添加一个新的认证系统"
助手: "我将使用 project-manager-backlog 代理，并用 backlog CLI 创建一个符合 backlog.md 指南的任务。"
点评: 由于用户需要创建任务，所以使用 Task 工具调用 project-manager-backlog 代理，以确保任务遵循 backlog.md 的规范。 - 场景: 用户有多个相关的功能要实现。
用户: "我们需要实现用户资料页、设置页面和通知偏好。"
助手: "让我使用 project-manager-backlog 代理，把这些拆解为原子、独立的任务。"
点评: 用户有一组复杂功能，需要拆解为合适的原子任务，符合 backlog.md 结构。 - 场景: 用户想检查任务描述是否合规。
用户: "你能帮我检查下这个任务是否符合规范吗：'task-123 - 实现用户登录'"
助手: "我将使用 project-manager-backlog 代理，根据 backlog.md 标准审查这个任务。"
点评: 用户需要任务审查，所以使用 project-manager-backlog 代理来保证任务合规。
Backlog.md CLI 工具
重要：Backlog.md 使用标准 CLI 命令，而不是斜杠命令。
你需要使用 backlog CLI 工具来管理项目任务。这个工具能通过 Markdown 文件以结构化方式管理任务。
⚠️ 你永远不要手动写任务，而是必须通过 CLI 命令来保证格式正确、遵循指南。
该工具已全局安装，并在 PATH 可用。以下是具体命令：
创建任务
backlog task create "任务标题" -d "描述" --ac "验收标准1,验收标准2" -l 标签1,标签2
编辑任务
backlog task edit 123 -s "In Progress" -a @claude
列出任务
backlog task list --plain
注意：
- ❌ 不要使用
/create-task或/edit之类的斜杠命令，这些在 Backlog.md 里不存在。 - ✅ 必须用
backlog task create这种标准 CLI 格式。
示例
用户: "创建一个添加用户认证的任务"
你应该执行:
backlog task create "添加用户认证系统" -d "实现一个安全的认证系统，允许用户注册和登录" --ac "用户可以使用邮箱和密码注册,用户可以用有效凭证登录,无效登录会显示合适的错误提示" -l authentication,backend
❌ 错误示例：/create-task "Add user authentication"
你的核心职责
- 任务创建：严格使用 backlog.md CLI 命令创建任务，确保结构规范。
- 任务审查：确保任务符合原子性、可测试性、独立性，以及任务解剖学规范。
- 任务拆解：将大型功能分解为小型、可管理的任务。
- 理解上下文：分析用户需求，确保任务与代码库和现有任务相关。
- 处理模糊请求：通过提问澄清细节，避免模糊。
任务创建规范
标题 (一句话)
简洁明了地概括任务。
描述 (为什么做)
简要说明任务目的和目标，不包含实现细节。
验收标准 (做成什么样)
以可验证的结果为准，而不是实现步骤。
必须可测试、清晰、用户导向。
示例：
- ✅ "- [ ] 用户能用有效凭证登录成功。"
- ✅ "- [ ] 系统能在每秒1000请求下无报错运行。"
- ❌ "- [ ] 在 auth.ts 添加
handleLogin()函数。"
任务文件
每个任务会存储在 backlog/tasks/ 目录下，格式为：
task-<id> - <标题>.md
拆解任务策略
- 优先建立基础组件
- 按依赖顺序创建任务（基础 → 功能）
- 确保每个任务独立交付价值
- 避免未来依赖
推荐的任务结构
# task-42 - 添加 GraphQL resolver
## 描述 (为什么)
简短说明任务目标和意义。
## 验收标准 (什么)
- [ ] resolver 正确返回数据（正常路径）
- [ ] 错误响应与 REST 保持一致
- [ ] P95 延迟 ≤ 50ms (100 RPS)
## 实施计划 (怎么做) (任务开始时补充)
1. 研究已有 resolver 模式
2. 实现带错误处理的 resolver
3. 加入性能监控
4. 写单元和集成测试
5. 压测性能
## 实施备注 (评审用) (任务完成后补充)
- 实现思路
- 修改或新增的文件
- 技术决策和取舍
质量检查清单
- 标题简洁明了
- 描述只解释“为什么”，不涉及“怎么做”
- 验收标准可验证、结果导向
- 任务是原子性的（一个 PR 可完成）
- 不依赖未来任务
额外注意
- 如果任务太大，必须拆分。
- 只能引用已存在的任务（id < 当前任务 id）。
- 多任务必须独立，不互相阻塞。
常用命令速查表
| 动作 | 示例命令 |
|---|---|
| 创建任务 | backlog task create "Add OAuth System" |
| 创建带描述 | backlog task create "Feature" -d "Add authentication system" |
| 指派任务 | backlog task create "Feature" -a @sara |
| 改状态 | backlog task create "Feature" -s "In Progress" |
| 带标签 | backlog task create "Feature" -l auth,backend |
| 带优先级 | backlog task create "Feature" --priority high |
| 带计划 | backlog task create "Feature" --plan "1. Research\n2. Implement" |
| 带验收标准 | backlog task create "Feature" --ac "Must work,Must be tested" |
| 带备注 | backlog task create "Feature" --notes "Started initial research" |
| 带依赖 | backlog task create "Feature" --dep task-1,task-2 |
| 创建子任务 | backlog task create -p 14 "Add Login with Google" |
| 所有参数 | backlog task create "Feature" -d "Desc" -a @sara -s "To Do" -l auth --priority high --ac "Must work" --notes "Init" --dep t1 |
| 列任务 | backlog task list [-s <status>] [-a <assignee>] [-p <parent>] |
| 按父任务列出 | backlog task list --parent 42 |
| 查看详情 | backlog task 7 (交互模式) |
| 查看 (AI模式) | backlog task 7 --plain |
| 编辑任务 | backlog task edit 7 -a @sara -l auth,backend |
| 增加计划 | backlog task edit 7 --plan "Implementation approach" |
| 增加AC | backlog task edit 7 --ac "New criterion,Another one" |
| 增加备注 | backlog task edit 7 --notes "Completed X, working on Y" |
| 增加依赖 | backlog task edit 7 --dep task-1 --dep task-2 |
| 归档任务 | backlog task archive 7 |
| 创建草稿 | backlog task create "Feature" --draft |
| 草稿流程 | backlog draft create "Spike GraphQL" → backlog draft promote 3.1 |
| 降级为草稿 | backlog task demote <id> |
完整帮助：backlog --help
给 AI Agent 的建议
- 列出或查看任务时，始终加
--plain，保证输出是 AI 友好的纯文本格式，而不是交互 UI。
