Backlog.md：基于Markdown与MCP的AI开发项目管理工具实践

1. 项目概述：当AI成为你的项目协作者

如果你和我一样，正在尝试将AI助手（比如Claude Code、Cursor、Gemini CLI）深度整合到日常开发工作流中，那你一定遇到过这个痛点：如何让AI有条不紊地处理一个复杂项目？你给AI一个宏大的指令，比如“给我的博客加个搜索功能”，它可能会生成一堆代码，但代码质量、实现路径、甚至是否覆盖了所有需求，都像开盲盒一样不可预测。项目进度、任务拆分、验收标准，这些原本由项目经理或资深开发者把控的环节，在AI协作中变得模糊不清。

这正是Backlog.md要解决的核心问题。它不是一个简单的待办事项列表，而是一个为“人机协作”量身定制的项目管理系统。它的核心理念是“Spec-Driven AI Development”（规范驱动的AI开发）。简单来说，就是把我们人类项目管理中“任务拆解、明确验收标准、分步执行”的那套成熟方法论，封装成一个AI能理解、能执行的框架。所有项目任务都以纯Markdown文件的形式，存放在你的Git仓库里。这意味着，你的项目板（Kanban）和任务历史，本身就是代码库的一部分，版本可控、可追溯，并且100%离线私有。

我第一次接触Backlog.md时，正被一个AI助手搞得焦头烂额，它总是忘记上下文，或者把不同模块的修改混在一起提交。用了Backlog.md之后，整个协作过程变得清晰、可控。我可以通过CLI快速创建任务、设定明确的验收标准（Acceptance Criteria），然后直接告诉AI：“请处理BACK-15号任务”。AI通过MCP协议连接到Backlog.md后，能读取任务详情、更新状态，甚至按照我预设的“完成定义”来检查自己的工作。这就像给AI配了一个严格的产品经理，确保每一次代码提交都目标明确、结果可验。

2. 核心设计理念与架构解析

2.1 为什么是“Markdown-Native”？

Backlog.md 选择Markdown作为任务存储的基石，这是一个看似简单却极其精妙的设计。市面上很多项目管理工具（如Jira, Trello）将数据存在自己的云端数据库或专有格式中，这带来了几个问题：数据锁死、迁移困难、无法与代码变更直接关联、离线不可用。

Backlog.md 反其道而行之。每一个任务，例如“BACK-10 - 实现核心搜索功能.md”，就是一个标准的Markdown文件。这个文件里不仅包含任务描述，还以特定的Front Matter（YAML格式的元数据）存储了状态（status: In Progress）、优先级、分配给谁、关联的Git分支等信息。正文部分则用于写详细的实施计划、笔记和最终的完成总结。

这样做的好处是立竿见影的：

1. 版本控制无缝集成：任务文件的创建、修改、删除，都会通过Git进行记录。你可以清晰地看到某个任务是如何随着需求变更而演进的，甚至可以用git blame查看是谁在什么时候修改了验收标准。
2. 工具无关性：你可以用任何你喜欢的文本编辑器（VSCode, Vim, Sublime）打开并编辑这些.md文件。即使Backlog.md这个工具某天消失了，你的所有项目数据依然完好无损，是一堆可读的文档。
3. 便于AI理解与操作：对于大语言模型（LLM）来说，解析和生成Markdown是它们的“母语”。相比解析复杂的JSON API或网页DOM，让AI读写一个结构清晰的Markdown文件要简单、可靠得多。这为深度AI集成打下了坚实基础。

2.2 “Spec-Driven AI Development”工作流详解

这是Backlog.md的灵魂所在，也是我认为它区别于其他工具的核心价值。它定义了一套让人类和AI高效协作的标准化流程。

传统AI协作模式（混乱模式）：用户：“AI，给我的网站加个用户登录系统。” AI：（生成大量代码，可能包含前端、后端、数据库设计，混在一起，难以Review，可能还有隐藏的Bug）。 用户：（需要花大量时间阅读代码、测试、提出修改意见，陷入冗长的对话循环）。

Backlog.md 驱动的规范模式：这个模式强制将工作分解为“规划-批准-执行-验证”的循环，每个循环针对一个微小、独立的任务。

1. 规划阶段（人类主导）：你作为项目负责人，使用backlog task create创建一个新任务。关键不在于创建任务本身，而在于如何填写“验收标准”。你必须用清晰、无歧义的语言描述“完成这个任务后，系统应该表现出什么行为”。例如，任务“添加用户登录按钮”的验收标准可能是：“1. 在导航栏右侧出现‘登录’按钮。2. 点击按钮弹出模态框，包含邮箱和密码输入框。3. 输入错误凭证时，显示‘邮箱或密码错误’提示。”
2. 批准与执行阶段（AI主导）：你将任务ID（如BACK-10）交给AI，并指令：“请处理BACK-10任务。先研究代码库，在任务文件中撰写实施计划，等我批准后再编码。” AI会读取任务文件，理解上下文，然后在其“实施计划”部分写下它打算如何做。这是一个关键的审查点。你阅读这个计划，判断其技术路线是否合理，是否与现有架构冲突，然后批准或要求修改。
3. 验证阶段（人类主导）：AI根据批准的计划进行编码。完成后，它（或你）需要根据之前设定的“验收标准”逐条验证。同时，Backlog.md可以配置“完成定义”，例如“所有单元测试通过”、“代码风格检查无误”。只有全部通过，任务才能被标记为“Done”。

这套流程将AI从“黑盒代码生成器”变成了“可预测、可审查的执行单元”。它极大地降低了沟通成本，提高了产出质量，并且让项目进度一目了然。

2.3 双模交互：CLI终端与Web UI

Backlog.md 提供了两种互补的交互界面，适应不同场景。

CLI（命令行界面）是效率核心。对于开发者而言，终端是主战场。backlog board命令能在终端里渲染出一个彩色的、实时更新的看板，让你在不离开终端的情况下，快速掌握项目全貌。backlog search支持模糊搜索，能瞬间从所有任务、文档中定位信息。通过一系列backlog task *子命令，创建、编辑、筛选、归档任务都只需几秒钟。这种无缝集成到开发环境的能力，是Web应用无法比拟的。

Web UI 是可视化管理和协作界面。运行backlog browser会启动一个本地Web服务器，打开一个现代化的看板界面。你可以通过拖拽来改变任务状态，在富文本编辑器中完善任务描述，或者使用更直观的表单编辑任务属性。这个界面特别适合在规划会议、进度同步时使用，或者当你需要更沉浸式地处理复杂任务描述时。所有在Web UI上的操作，都会实时同步到本地的Markdown文件中，两者数据完全一致。

这种设计体现了工具设计的成熟思考：为专业场景（高效命令行操作）和扩展场景（可视化协作）分别提供最优解，并通过统一的数据层保持一致性。

3. 从零开始：安装与初始化实战

3.1 环境准备与安装

Backlog.md 基于 Node.js 环境，因此你需要先确保系统已安装 Node.js (>= 18) 或 Bun。我个人更推荐使用Bun，因为它在安装和启动速度上通常有更好的表现，而且Backlog.md对其有良好支持。

安装Backlog.md全局命令行工具：你有多种包管理器可以选择，选你习惯的即可。

# 使用 Bun (推荐) bun add -g backlog.md # 使用 npm npm i -g backlog.md # macOS 用户可使用 Homebrew brew install backlog-md # Nix 用户 nix run github:MrLesk/Backlog.md

安装完成后，在终端输入backlog --help，如果看到一长串命令说明，恭喜你，安装成功。

注意：如果你在安装后遇到“command not found”错误，通常是因为全局安装路径没有添加到系统的PATH环境变量中。对于Node.js/npm，可以检查npm config get prefix对应的bin目录是否在PATH中。对于Bun，它通常会自动处理。使用which backlog或where backlog命令可以查看工具的实际安装位置。

3.2 项目初始化与AI集成配置

Backlog.md 的核心是项目级别的管理。你需要在一个Git仓库的根目录下初始化它。

# 进入你的项目目录 cd /path/to/your/git-project # 运行初始化命令 backlog init "我的AI增强博客项目"

这个init命令会启动一个交互式向导。除了让你输入项目名称，最关键的一步是选择AI集成方式。向导会提供三个选项：

1. MCP Connector (推荐)：这是最强大、最无缝的集成方式。MCP（Model Context Protocol）是Anthropic推出的一种协议，允许像Claude Code这样的AI助手安全地访问外部工具和数据源。选择此项，Backlog.md会自动检测你系统上已安装的AI开发工具（如Claude Code, Cursor, Codex, Gemini CLI, Kiro），并为你配置好MCP连接。它还会在你的项目根目录生成或更新CLAUDE.md、AGENTS.md等指导文件，告诉AI助手如何与Backlog.md交互。
2. CLI Commands：如果你使用的AI工具不支持MCP，或者你希望更显式地控制，可以选择这个。Backlog.md会生成详细的指令文件，教导AI通过执行backlog task list、backlog task edit等CLI命令来管理任务。AI需要在它的上下文中运行这些命令。
3. Skip：如果你暂时只想将Backlog.md用作一个本地的、纯人工的任务管理工具，可以选择跳过AI设置。

我强烈建议第一次使用时选择MCP Connector。它能省去大量手动配置的麻烦，实现开箱即用的AI协作体验。初始化完成后，你的项目目录下会生成一个backlog/文件夹（或.backlog/，可在配置中修改），里面包含了config.yml配置文件、tasks/（存放所有任务md文件）、docs/、decisions/等子目录。整个结构清晰，并且被.gitignore合理管理（通常只忽略缓存文件，任务文件会被跟踪）。

3.3 理解数据存储与配置层级

初始化后，了解Backlog.md如何管理配置和数据很重要，这能帮助你在后续进行高级定制。

数据存储：所有核心数据（任务、文档、决策记录）都以Markdown文件形式存放在backlog/目录下。这意味着：

• 你可以用git add backlog/tasks/BACK-1*.md来提交单个任务。
• 你可以用grep -r "搜索功能" backlog/来全局搜索所有相关内容。
• 项目备份和迁移，就是复制整个backlog/目录那么简单。

配置优先级（由高到低）：

1. 命令行参数：执行命令时直接传入的--flag，优先级最高。例如backlog browser --port 8080 --no-open。
2. 项目配置文件：
   • 如果项目根目录存在backlog.config.yml，则使用它。
   • 否则，使用backlog/config.yml或.backlog/config.yml。
3. 内置默认值：如果以上都未设置，则使用工具自带的默认配置。

你可以通过backlog config命令再次启动交互式配置向导，来修改任何设置，比如默认编辑器、Web UI端口、是否自动提交Git等。配置是即时生效的。

4. 核心功能实操：任务生命周期管理

4.1 创建与定义任务

任务创建是规范驱动的起点。一个定义良好的任务是成功的一半。

# 基本创建 backlog task create "为REST API添加用户身份验证中间件" # 创建时直接补充详细描述和验收标准（推荐） backlog task create "实现博客文章草稿自动保存功能" \ -d "用户在文章编辑器中输入时，每隔30秒自动将当前内容保存为草稿，防止浏览器意外关闭导致内容丢失。需考虑网络离线时的本地存储方案。" \ --ac "1. 在编辑页面，无操作30秒后，控制台输出‘草稿已保存’日志。2. 手动刷新页面后，编辑器能自动加载最后一次保存的草稿内容。3. 网络恢复后，能将本地草稿同步至服务器。4. 提供‘清除草稿’的按钮。" # 指定状态和优先级 backlog task create "修复首页图片加载缓慢的问题" -s "To Do" -p high

关键参数解析：

• -d(--description)：详细描述。这里要写清楚背景、上下文、非功能性需求（如性能要求）。这是AI理解任务全貌的基础。
• --ac(--acceptance-criteria)：验收标准。这是最重要的部分。务必使用清晰、可验证的陈述句，最好能像测试用例一样逐一列出。例如：“用户点击提交按钮后，页面显示‘提交成功’提示”就比“优化提交体验”要好得多。
• -s(--status)：初始状态，默认为“To Do”。Backlog.md 默认使用To Do->In Progress->In Review->Done的工作流，你可以在配置中自定义。
• -p(--priority)：优先级 (low,medium,high,critical)。

创建成功后，CLI会输出类似Created task BACK-5的信息。此时，一个名为task-5 - 实现博客文章草稿自动保存功能.md的文件就已经在backlog/tasks/目录下生成了。你可以用backlog task edit BACK-5命令或直接用文本编辑器打开它进行查看和编辑。

4.2 使用“完成定义”确保质量

“完成定义”是一份项目级别的质量检查清单。在backlog config向导中，你可以设置全局的DoD项。例如：

definition_of_done: - 代码通过ESLint检查 - 新增或修改的功能均有单元测试覆盖 - 相关文档（README或API文档）已更新 - 代码经过至少一位同事的Review - 在主要浏览器（Chrome, Firefox）上测试通过

此后，每创建一个新任务，这个清单会自动附加到任务的“验收标准”区域。这相当于为每一个任务都内置了质量门禁。在AI协作中，你可以指令AI：“请完成BACK-8任务，并确保满足所有‘完成定义’中的要求。” AI在提交代码前，就会自主检查这些项。

你也可以在创建单个任务时，用--dod添加额外的DoD项，或用--no-dod-defaults禁用全局默认项。

4.3 任务查询、筛选与可视化

随着任务增多，如何快速找到所需信息至关重要。

# 列出所有任务（基础视图） backlog task list # 列出特定状态的任务 backlog task list -s "In Progress" backlog task list -s "Done" -s "In Review" # 多个状态 # 按优先级筛选 backlog task list -p high # 组合筛选：高优先级且正在进行中的任务 backlog task list -s "In Progress" -p high # 使用强大的搜索功能（模糊搜索，支持标题、描述、内容） backlog search "身份验证" backlog search "bug" --status "To Do" # 在待办任务中搜索bug # 最直观的：在终端查看看板 backlog board

backlog board命令会输出一个彩色的、基于字符的看板视图，各列就是任务状态，任务以卡片形式呈现，包含ID、标题和优先级图标。这是快速同步项目状态的神器。

进阶查询：Backlog.md 的查询引擎支持更复杂的逻辑。例如，想找出所有由“AI”创建但尚未开始的任务：backlog task list --creator AI --status "To Do"。查询条件非常灵活，可以满足日常管理的大部分需求。

4.4 任务推进、更新与归档

任务的生命周期管理通过简单的命令完成。

# 开始处理一个任务（将其状态改为 In Progress） backlog task start BACK-12 # 更新任务进度或信息 backlog task edit BACK-12 -d "补充了关于错误处理的详细描述" backlog task edit BACK-12 --ac "增加AC：当服务器返回5xx错误时，前端显示友好错误页面。" # 将任务标记为需要审查 backlog task review BACK-12 # 将任务标记为完成 backlog task finish BACK-12 # 如果任务不再需要，可以归档（并非删除，而是移到归档区） backlog task archive BACK-7

一个重要的实操技巧：在AI协作流程中，backlog task start BACK-XX是一个很好的仪式感命令。它明确告诉系统和你的AI协作者：“现在我开始专注处理这个任务了”。当任务完成后，使用backlog task finish会检查其“验收标准”是否都已标记完成（在Web UI或编辑任务文件时可以勾选），这是一个最终的质量确认步骤。

5. 深度集成：与AI助手协同工作流

5.1 配置MCP连接（以Claude Code为例）

如果你在初始化时选择了MCP Connector，那么配置几乎是自动完成的。但了解其原理有助于排错。

对于Claude Code，Backlog.md的初始化向导通常会帮你执行类似下面的命令：

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

这条命令做了两件事：

1. 在Claude Code的MCP配置中，添加了一个名为“backlog”的服务器。
2. 这个服务器的启动命令是backlog mcp start。

你可以通过Claude Code界面中的/mcp命令来验证连接是否成功。连接后，AI助手就能访问backlog://协议下的资源，最重要的是backlog://docs/task-workflow，这个资源文件包含了Backlog.md希望AI遵循的工作流指南。

手动配置场景：如果你的IDE不支持自动配置，或者你想指定特定项目路径，可以手动编辑IDE的MCP配置。例如，在对应的配置文件中添加：

{ "mcpServers": { "backlog": { "command": "backlog", "args": ["mcp", "start"], "env": { "BACKLOG_CWD": "/绝对路径/到/你的项目" } } } }

环境变量BACKLOG_CWD用于告诉Backlog.md MCP服务器在哪个项目目录下运行，这对于那些无法自动设置进程工作目录的IDE非常必要。

5.2 规范化的AI协作四步法

连接成功后，你就可以与AI展开规范的协作了。以下是经过我多次实践验证的高效流程：

第一步：需求拆解与任务创建（人类主导）不要直接让AI实现一个大功能。而是由你，或者你和AI一起，将大目标拆解成原子任务。

• 你： “我想为我的Markdown博客添加一个基于标签的文章筛选功能。”
• 你（对AI）： “请将这个需求拆解成3-5个独立的、可交付的Backlog.md任务，每个任务都需要清晰的标题、描述和可验证的验收标准。”
• AI： 生成任务BACK-13“在文章Frontmatter中添加标签字段”，BACK-14“在文章列表页面添加标签云组件”，BACK-15“实现根据标签筛选文章列表的功能”等。
• 你： 审查AI创建的任务，调整描述和验收标准，确保它们真正独立且粒度合适。

第二步：单任务规划与批准（人机交互）聚焦一个任务，例如BACK-15。

• 你（对AI）： “请处理任务BACK-15。首先，详细研究代码库中文章列表组件和状态管理的现有实现，然后在任务文件中撰写一份详细的实施计划。计划需包含：1. 需要修改的文件。2. 状态管理逻辑的变化。3. 预期的UI组件结构。请等我批准计划后再开始编写代码。”
• AI： 阅读BACK-15的Markdown文件和相关代码，在任务的“实施计划”部分写下它的方案。
• 你：【关键审查点】仔细阅读AI写的计划。它是否理解了现有架构？方案是否合理？有没有更优解？如果没问题，在任务下评论或直接告诉AI：“计划已批准，请开始实施。”

第三步：任务执行与迭代（AI主导）

• AI： 根据批准的计划开始编码。它可能会在任务文件中更新进度笔记。
• 你： 可以定期运行backlog board查看进度，或者让AI在完成关键步骤后通知你。

第四步：验收与闭环（人类主导）

• AI： 完成编码后，它会（或你指令它）根据任务的“验收标准”和“完成定义”进行自检，并在任务中总结所做更改。
• 你：【最终审查点】运行测试、检查代码风格、Review代码变更。对照验收标准逐一验证功能。如果全部通过，使用backlog task finish BACK-15关闭任务。如果未通过，将任务状态改回“In Progress”或“To Do”，并在描述中清晰指出问题所在，让AI继续迭代。

这个流程将AI的创造力约束在了一个个有明确边界和标准的“盒子”里，极大地提升了结果的可预测性和项目管理的可控性。

6. Web界面与高级管理功能

6.1 启动与使用Web看板

虽然CLI效率极高，但有些时候视觉化的拖拽管理更直观。

# 默认启动，并自动打开浏览器 backlog browser # 指定端口运行，且不自动打开浏览器（例如在远程服务器上） backlog browser --port 8080 --no-open

启动后，浏览器会访问http://localhost:6420（或你指定的端口）。你会看到一个现代化的看板界面。

Web UI的核心优势：

1. 拖拽管理：在“待办”、“进行中”、“审核中”、“已完成”各列之间拖动任务卡片，是更新状态最自然的方式。
2. 富文本编辑：编辑任务描述和验收标准时，支持Markdown实时预览、添加列表、代码块等，比纯命令行编辑更友好。
3. 批量操作：可以方便地多选任务进行状态批量更新或归档。
4. 可视化筛选：侧边栏通常有基于标签、优先级、分配人的筛选器，适合快速聚焦某一类任务。
5. 适合演示：在站会或项目同步时，投屏Web看板比看终端更易于团队成员理解。

一个重要提示：Web UI和CLI操作的是同一套Markdown文件。你在网页上拖拽一个任务，对应的.md文件中的status元数据会立刻改变。反之亦然。这种双向实时同步是Backlog.md设计一致性的体现。

6.2 搜索、文档与决策记录

Backlog.md 不仅仅管理任务，它还是一个轻量级的项目知识库。

搜索 (backlog search)：这是一个全局搜索工具，威力强大。它不仅仅搜索任务标题，还会深入任务描述、验收标准、评论，以及backlog/docs/和backlog/decisions/目录下的所有文档。

# 简单关键词搜索 backlog search "数据库迁移" # 结合类型的搜索：在决策记录中搜索关于“架构”的讨论 backlog search "架构" --type decision

当你记不清某个功能细节是在哪个任务里讨论的，或者想回顾当初为什么选择某个技术方案时，这个搜索功能能救命。

文档 (backlog doc) 与 决策记录 (backlog decision):

• 文档：用于存放项目相对静态的说明，比如API设计规范、部署流程、团队约定。backlog doc create "API版本管理策略"会创建一个文档，并可以用backlog doc edit来更新。
• 决策记录：这是记录重要技术或产品决策的神器。每次面临选择（例如“为什么我们选用PostgreSQL而不是MySQL？”），都应该创建一个决策记录。

  backlog decision create "选择React状态管理库" \ -s "在Zustand和Redux Toolkit之间选择" \ -o "Zustand, Redux Toolkit" \ -c "项目复杂度中等，团队更倾向于简洁的API和更少的概念。Zustand学习曲线平缓，包体积小，能满足当前需求。" \ -d "选择Zustand作为核心状态管理库。"

  参数-s(状况)、-o(选项)、-c(权衡)、-d(决定) 构成了一个完整的决策记录框架，迫使你进行结构化思考，这对未来复盘和新成员入职 invaluable。

6.3 导出、备份与团队协作

导出看板：你可以将当前的看板状态导出为一份结构化的Markdown报告，用于周报或向非技术利益相关者同步。

backlog board export --output ./project-status-report.md

导出的报告会包含按状态分组的任务列表、摘要等信息，格式清晰。

Git集成与备份：Backlog.md 鼓励你将backlog/目录纳入Git版本控制（但通常忽略backlog/.cache等临时目录）。这意味着：

• 历史追溯：你可以看到任务描述是如何随时间演变的。
• 分支实验：你可以在Git分支上创建一套实验性的任务，合并分支时，这些任务变更也会一并合并。
• 灾难恢复：你的整个项目管理系统随着代码库一起被备份。

在团队协作中，每个成员都在本地克隆仓库后运行backlog init（如果尚未初始化），即可获得完全一致的任务视图。通过Git的拉取和推送操作，即可同步任务状态的更新。这种基于Git的协作模式，天然适合开发者团队，避免了中心化SaaS工具的权限和网络依赖问题。

7. 常见问题、故障排查与使用技巧

7.1 安装与初始化问题

问题：安装后backlog命令未找到。

• 排查：首先确认安装是否成功npm list -g backlog.md或bun pm ls -g。如果已安装，可能是全局bin目录不在PATH中。
• 解决：
  • npm：将$(npm config get prefix)/bin添加到你的shell配置文件（如~/.zshrc或~/.bashrc）的PATH中。
  • Bun：Bun通常将包安装在~/.bun/bin，确保该路径在PATH中。可运行bun setup进行自动配置。
  • 通用方法：在终端执行which backlog或where backlog找到可执行文件路径，手动将其所在目录加入PATH。

问题：backlog init时提示“Not a git repository”。

• 原因：Backlog.md 必须在Git仓库根目录内初始化，因为它依赖Git来提供项目上下文和实现部分功能（如分支关联）。
• 解决：cd到你的Git项目根目录再执行初始化。如果还没有Git，先运行git init。

问题：MCP连接失败，AI助手无法看到Backlog任务。

• 排查步骤：
  1. 确保在正确的项目目录下运行AI助手（Claude Code, Cursor等）。
  2. 在AI助手的聊天框内输入/mcp，查看“backlog”服务器是否在列表中且状态为“Connected”。
  3. 如果未连接，检查AI助手的MCP配置文件路径是否正确，命令是否为backlog mcp start。
  4. 尝试在终端手动运行backlog mcp start，看是否有错误输出。常见错误是BACKLOG_CWD环境变量未设置或指向错误路径。
• 解决：对于Claude Code，可以尝试重新运行连接命令：claude mcp add backlog --scope user -- backlog mcp start。或者，在项目根目录的CLAUDE.md文件中，确保包含了Backlog.md的工作流指引。

7.2 任务管理与工作流问题

问题：backlog board终端显示乱码或颜色异常。

• 原因：你的终端可能不支持真彩色或特定的Unicode字符。
• 解决：尝试设置环境变量FORCE_COLOR=1强制使用颜色，或使用NO_COLOR=1禁用颜色。也可以考虑使用更现代的终端，如Windows Terminal, iTerm2, WezTerm等。

问题：如何自定义任务状态的工作流？

• 方法：Backlog.md 默认使用一套经典状态流。你可以在项目配置文件backlog/config.yml中自定义。但请注意，深度自定义可能需要修改源代码或等待未来版本支持更灵活的配置。目前，建议先适应其默认状态（To Do, In Progress, In Review, Done），这已覆盖绝大多数开发场景。

问题：任务文件被手动修改后，CLI命令或Web UI显示不一致。

• 原因：虽然可以直接编辑.md文件，但如果修改了Front Matter的格式（比如YAML语法错误）或使用了Backlog.md不支持的字段，可能会导致解析失败。
• 解决：优先使用backlog task edit命令或Web UI来修改任务。如果必须手动编辑，请确保Y格式正确，并运行backlog task sync或重启backlog browser来刷新缓存。养成修改前备份的好习惯。

7.3 性能与使用技巧

技巧1：利用模糊搜索提高效率backlog search支持模糊匹配。你不需要输入完整词汇，例如backlog search “auth midleware”很可能找到关于“authentication middleware”的任务。这在你只记得任务大概内容时非常有用。

技巧2：为常用查询创建别名如果你经常需要查看某个特定视图，比如所有高优先级的待办任务，可以在你的shell配置文件（如.zshrc）中设置别名。

alias backlog-high-todo='backlog task list -s "To Do" -p high'

技巧3：将Backlog.md集成到你的提交钩子中在backlog/config.yml中，可以设置autoCommit: true。这样，当你通过Backlog.md CLI更改任务状态时，它会自动执行git add和git commit，并生成一条包含任务ID的提交信息（如“Update BACK-12 status”）。这能保持任务状态与Git历史同步。但请注意，如果你有复杂的Git钩子（如pre-commit检查），可能需要设置bypassGitHooks: true或根据情况调整。

技巧4：在CI/CD中利用导出功能你可以编写一个简单的脚本，在每日构建或部署前，运行backlog board export，将看板状态导出为Markdown，然后作为附件发送到团队频道或邮件列表，实现自动化项目状态同步。

技巧5：清晰定义“完成定义”花时间在项目初期，通过backlog config认真定义好项目的“完成定义”。这不仅是给AI的 checklist，也是整个团队的质量共识。一个明确的DoD能减少很多关于“这算不算做完”的争论。

Backlog.md 本质上是一个理念的载体：将软件工程的最佳实践（明确的需求、拆解的任务、清晰的验收标准、版本控制）应用于人机协作的新范式。它没有试图取代Jira或Linear，而是为AI时代的小型团队或个人开发者，提供了一种极其轻量、透明且强大的项目管理选择。我最欣赏它的一点是，所有数据都掌握在自己手中，格式开放，没有任何供应商锁定的风险。当你开始用它来规范你和AI的协作，你会发现，项目不再是一团乱麻，而是一条由清晰任务节点构成的、可向前推进的路径。