代理指令文件

代理指令文件是 Backlog.md 为 AI 编码助手准备的标准化指南文档。这些文件告诉 AI 如何与 Backlog.md 协作，包括工作流规范、命令用法和任务管理标准。通过统一的指令文件，不同 AI 工具对项目的理解保持一致，避免因工具切换导致的工作流偏差。

什么是指令文件

AI 编码助手在启动时会读取项目中的特定 Markdown 文件作为上下文。Backlog.md 利用这一机制，生成包含项目管理规范的指令文件。这些文件涵盖：

• Backlog.md 的核心能力介绍
• 任务文件结构说明
• CLI 命令完整参考
• 验收标准与定义完成（DoD）规范
• 典型工作流程示例
• 常见错误与正确做法对比

AI 阅读这些文件后，能够在对话中准确使用 Backlog.md 的功能，无需用户反复解释项目规范。

生成指令文件

Backlog.md 提供两种方式生成或更新代理指令文件。

初始化项目时自动生成

运行 backlog init 初始化新项目时，向导会询问是否需要安装 AI 代理指令：

backlog init my-project
# 交互式向导中出现选项：
# "Install AI agent instructions?"

选择安装后，Backlog.md 会根据你的选择生成对应的指令文件。

手动更新已有项目的指令

对于已存在的项目，随时可以通过以下命令更新或重新生成指令文件：

backlog agents --update-instructions

该命令会扫描当前项目，根据现有配置重新生成所有指令文件，确保内容与项目当前状态同步。当你修改了任务状态流程、标签体系或其他项目规范后，建议运行此命令更新 AI 指令。

生成的文件清单

根据你使用的 AI 工具，Backlog.md 会生成以下一个或多个文件：

注意：Cursor 不再生成单独的 .cursorrules 等 Backlog 拥有的规则文件，统一使用 AGENTS.md。重复执行生成命令会保留 AGENTS.md 中已有的用户内容，只更新 Backlog 管理的标记区块。

指令文件里不含项目状态机的副本（v1.53.9 起）：状态机以 config.yml 为唯一真源，由 backlog instructions overview 按当前配置现场渲染。旧版本写进 AGENTS.md / CLAUDE.md / GEMINI.md 的 state-machine 区块会在下次 backlog init 或 backlog agents --update-instructions 时被移除。

CLAUDE.md

专为 Claude Code 和 Claude Desktop 设计。Claude 系列工具会自动读取项目根目录下的 CLAUDE.md 作为系统提示的一部分。该文件包含完整的 Backlog.md 操作指南，是功能最全面的指令文件。

AGENTS.md

通用代理指令文件，适用于 Cursor 以及不识别特定品牌文件的 AI 工具。文件内容与 CLAUDE.md 基本一致，但采用更通用的表述方式。Cursor 会读取项目根目录的 AGENTS.md 作为通用代理指令；部分 IDE 插件或自定义 AI 客户端也会优先读取 AGENTS.md。

GEMINI.md

针对 Google Gemini CLI 优化的指令文件。Gemini CLI 会识别项目根目录下的 GEMINI.md 并纳入上下文。

.github/copilot-instructions.md

专为 GitHub Copilot 设计。由于 Copilot 不支持 MCP 协议，该文件内容更侧重 CLI 命令参考，帮助 Copilot 理解如何在代码生成过程中配合 Backlog.md 的 shell 命令。文件位于 .github/ 目录下，因此仅在 GitHub 仓库中生效。

指令文件包含的内容

所有生成的指令文件都遵循统一的内容框架，主要包括以下模块。

工作流指南

说明 AI 与 Backlog.md 协作的推荐流程：

• 首轮先加载项目实况：新会话在给出任何答案或计划之前，先运行 backlog config list、backlog search <关键词>、backlog task list、backlog task view <id>、backlog overview 等命令，读取真实的 statuses、defaultStatus、defaultAssignee 与活跃任务
• 不得假设默认状态集合 [To Do, In Progress, Done]；设置或校验任务状态时必须落在配置的 statuses 之内
• defaultStatus 必须是 statuses 的成员，若不是应提示用户修正或另选默认值
• 如何通过 CLI 或 MCP 读取任务
• 如何在实施前撰写实现计划
• 如何按验收标准逐步完成任务
• 如何添加最终总结并标记任务完成

这条"先加载实况"的规则写在随 CLI 分发的 overview 指南中（而非项目自己的 AGENTS.md），因此对任何使用 Backlog.md 的项目都生效。

backlog instructions overview 的加载节奏约定为每个会话一次：指令要求代理在会话开始、给出任何回答或采取行动之前运行一次该命令；同一会话内已读过的无需重复执行。

引用与行号定位

指南约定任务的 References 支持行号引用，每条引用是三种形态之一：外部 URL、项目相对文件路径、或带行区间的路径（path:LINE 单行、path:START-END 连续区间）。创建/编辑任务与 MCP 的 references / addReferences / removeReferences 参数均遵循同一约定，removeReferences 按完整存储字符串（含行号后缀）匹配。文档链接同样区分三类目标：外部 URL、Backlog 短链接（/task/:id、/doc/:id 等，可带行号后缀）与项目相对路径。

日期与多行输入约定

指南还明确了两类高频输入错误：

• 日期与时间字段：CLI 与 MCP 接受本地时间输入，存储为 UTC，展示时再转回本地时间。不要读取任务文件里可见的 UTC 值再作为输入传回去，否则会产生时区偏移
• 多行文本字段：在引号内使用字面量 \n 表示换行；不要在引号内按真实回车——shell 会把它拆成多行，实际只保存第一行

任务创建规范

明确高质量任务的标准：

• 标题应简洁概括任务目的
• 描述聚焦 "为什么" 而非 "怎么做"
• 验收标准必须结果导向、可验证
• 每个任务对应一个独立的 Pull Request

验收标准格式

详细说明验收标准的格式要求：

• 使用编号复选框形式 - [ ] #1 标准内容
• 通过 CLI 的 --ac 参数添加
• 通过 --check-ac 和 --uncheck-ac 管理完成状态
• 支持单次命令操作多个标准项

命令参考

提供完整的 CLI 命令速查表，覆盖：

• 任务创建、编辑、查看、归档
• 验收标准与 DoD 管理
• 搜索与过滤
• 文档和决策管理
• 看板与概览

backlog instructions 分册

除了写入项目的指令文件，CLI 还内置一套可即时打印的工作流分册，与 MCP 资源一一对应：

backlog instructions            # 打印分册索引
backlog instructions --list     # 列出可用分册
backlog instructions overview   # 打印指定分册

overview 分册携带项目状态机，打印时按当前 config.yml 现场组装，不是静态文本（doc-19 FR-8）。

MCP 与 CLI 指令方式对比

Backlog.md 支持两种 AI 集成方式，各有适用场景：

推荐策略：

• 如果使用的 AI 工具支持 MCP，优先选择 MCP 方式
• 对于 GitHub Copilot 等不支持 MCP 的工具，使用 CLI 指令方式作为补充
• Cursor 同时支持 MCP 与 AGENTS.md 指令文件，可任选其一或两者并存
• 两种方式可以并存：MCP 负责日常任务管理，CLI 指令文件确保 Copilot、Cursor 等也能理解项目规范