BMAD-METHOD 的 bmad-project-context：在 AGENTS.md 中构建小而验证的代理规则块

• AI 技能
• 人工智能
• 开发工具

BMAD-METHOD 是面向"敏捷 AI 驱动开发"的开源方法框架，bmad-project-context是其核心技能之一，负责为 AI 代理在仓库中正常工作"整备环境"。本文围绕该技能的设计与工作方式展开：它如何把组织政策、经验证的命令、偏离生态默认值的约定、真实发生的代理错误浓缩成一个存放在AGENTS.md中的精简规则块，如何通过 Setup、Adopt、Refresh、Record、Audit 五种意图持续维护这一块内容，以及它在加载机制、monorepo 布局、与bmad-architecture分工等方面的实现细节。读完本文，你将掌握该技能的内容准入标准、五种执行意图、块结构与标记边界约定，并能结合源码定位其判定依据。

定位：对话式整备工具，而非文档生成器

原文档（docs/ko-kr/explanation/project-context.md）开宗明义：bmad-project-context是对话式工具，不是生成器。它的产出物不是长篇文档，而是放进仓库根目录AGENTS.md的一段简洁且经过验证的规则块——记录组织要求什么、实际运行确认过的命令、与常见预期不同的规则、以及代理在这个仓库里反复犯下的错误。

这一设计的核心约束是：代理应遵守的规则由人来提供（治理、安全、编码标准），其余信息由技能负责查找并验证；每次写入都必须经过人工确认，不存在无人值守的执行模式。

从 skills/bmad-project-context/SKILL.md 的实现看，该技能接受一个显式意图参数intent（setup|adopt|refresh|record|audit）以及目标仓库路径或额外来源路径。其激活流程会先通过resolve_customization.py解析customize.toml中的[workflow]配置（见 skills/bmad-project-context/customize.toml，默认activation_steps_prepend、activation_steps_append为空数组，persistent_facts刻意留空——因为技能自身的产出AGENTS.md由宿主工具加载，而非通过该数组注入），随后在读取其他任何内容之前加载 references/best-practices.md 与 references/template.md，所有后续决策都以这两份文件为基准。

收录与排除：以"查找成本"为判定基准

技能的内容取舍标准不是"代理能否推导出这条事实"，而是在需要它的时刻找到它所付出的成本。代理阅读源码比阅读描述源码的文字更准确；低成本的结论写成文字会迅速过时，并且每次会话加载都要支付额外 token 成本。因此，仓库概览、目录树、技术栈清单一律不收录；真正值得记录的是"只读代码难以在关键时刻找到"的信息。

原文档明确列出六类值得收录的内容：

1. 组织政策——禁止修改的路径、生成的文件、分支规则、安全与合规要求；
2. 配置文件无法表达的运行条件——不照抄脚本，而是记录"该用哪个命令、注意什么"，例如pnpm test已存在于package.json，但"测试要跑 11 分钟"或"需要先启动某个服务"这类事实不会出现在配置里；
3. 偏离生态默认值的规则——没有特别说明时，代理会按通用惯例行事，所以只有"偏离"的部分值得一行；
4. 有实证的错误教训——来自既有记录、维护者记忆、Git 历史中反复修正的失误、以及本次会话中当场发现并纠正的错误；扫描中发现的"看起来危险"的事实不能直接写成规则，必须先提问；
5. 跨组件规则与必要版本——编辑单个文件时看不到、却需要系统多处共同遵守的规则，以及项目实际构建所用的工具版本；
6. 指向产出位置与首读文件的指针。

references/best-practices.md 将同样的判断组织为Admit（收录）与Exclude（排除）两张清单，排除项包括：仓库概览与目录树（副本比源码更快腐烂）、仅因"有趣"而收录的内容、代理本可自律的风格规则（应改由格式化器、lint、hook 或 CI 强制）、陈词滥调、明显调用方式已经正确的命令清单、粘贴的代码与变更日志、指向未来的理想状态、历史叙述。该文件还强调"优先写禁令而非建议，并在同一行给出被允许的替代方案"。

五种意图：Setup、Adopt、Refresh、Record、Audit

原文档用一张表概括技能支持的五种意图，SKILL.md 则在 "On Activation" 中给出了自动化检测逻辑（指令文件无实质内容判定为 setup；有内容但无托管块判定为 adopt，它是 refresh 的迁移形态；存在托管块判定为 refresh；用户报告代理犯错判定为 record；其余为 audit），并且当用户提供的意图与检测结果矛盾时会向用户确认，绝不静默服从：

SKILL.md 进一步规定了核心执行流程：第 5 步之前不写任何内容。流程依次为：(1) 评估现状并汇报，为每条既有指令开一张"台账"（ledger），条目初始状态为retain或rewrite，随证据逐步落定为retain | rewrite | relocate | automate | delete；(2) 询问用户带来的规则（治理、安全合规、编码标准、冻结区域，以及组织手册、wiki、MCP 知识库等外部文档，只记录路径暂不读取）；(3) 用并行子代理对配置与 CI、被追踪源码、定向 Git 历史做发现与验证，逐条核对文件路径与命令声明；(4) 只访谈扫描无法覆盖的部分——代理常错之处、禁区、领域术语含义、约束存在的原因，批次不超过 8 个问题；(5)先展示完整块再写入，同时展示已落定的台账（替换文本单独呈现不构成完整提案，因为那会隐藏用户失去的内容），批准后在两个标记之间拼接，块外内容绝不作为拼接的副作用被改动，且技能从不主动提交。

加载方式与标记边界

AGENTS.md位于仓库根目录，是主流编码工具都会读取的文件。技能只管理<!-- bmad:context -->与<!-- /bmad:context -->之间的区域；用户在标记之外写的内容按字节原样保留，Refresh 也不会触碰。

模板文件 references/template.md 规定了块的内部结构（没有内容的章节一律省略，禁止写空节）：

1. Orientation——三到四句话：这是什么、技术栈、规划文档与深度文档在哪里；
2. Policy——组织要求什么；
3. Where things are——入口点，以及指向子文件与链接文件的指针；
4. Running and verifying——正确的运行命令与必需工具版本，以及package.json、pyproject.toml、Makefile、CI 配置没有说明的内容；
5. Conventions that differ from defaults——偏离默认值的约定；
6. Known pitfalls——已知陷阱。

模板还提供了完整的实操示例块，包含<!-- Verified 2026-08-08 against a1b2c3d. Managed by bmad-project-context; ... -->这类溯源行——Refresh 正是基于记录的真实日期与校验过的提交 SHA 进行差异比对。整个块采用朴素标题下的祈使句短行，除 Orientation 外无散文、无引言、无总结；一条裸事实只允许以指令的"理由从句"形式出现（如"从搜索中排除vendor/，它占被追踪文件的 60%"，而非"vendor/占被追踪文件的 60%"）；禁令必须指明替代方案；全块最多使用两处强调标记。

对于 monorepo 的组件与嵌套仓库，用相同规则创建单独文件，并在上层文件中以指针连接。如果某目录有大量专属规则，可下沉到该目录的AGENTS.md——但前提是先确认所用工具确实会读取该位置的文件；若不读取，就把规则留在根文件，并注明每条规则适用的目录。SKILL.md 对"拆分"设置了更严格的门槛：规则必须为该子树独有且内容充实、拆分能实质减小父块、每个宿主工具的加载机制都被验证过（"检查过，而非假设"）、且获得用户批准；即使加载已验证，若某规则必须在会话进入该目录前生效、或违反它会影响子树之外的工作，仍应保留在根块。加载机制检查的原因在于：多个宿主工具在会话开始时一次性构建指令链（从根到工作目录），嵌套文件对之后才进入该子树的会话是不可见的。唯一例外是"触发条件不是路径"时才使用链接文件。

放仓库还是放主目录

技能产出的块必须提交进仓库：这样团队可以共享、每台机器使用相同规则、并随受约束的代码一起做版本管理。只有两类内容应放进主目录的代理全局配置——在所有项目中反复出现的相同规则，以及属于个人偏好而非团队规则的内容。

这与 references/best-practices.md 中 "Repo or home directory" 一节的结论一致。仓库自身的 AGENTS.md 就是一个鲜活的实例：它只有少量祈使行——提交必须用 Conventional Commits、推送前必须在将要推送的确切检出上运行质量校验命令、每个克隆运行一次pre-commit install、技能校验规则与文档规范各自指向对应文件，并解释了为什么"写作提示"要简短（技能、工作流、任务、代理定义都是每次运行被完整读取的提示文本，长度与歧义在每次运行中都要付费）。这正是"小而验证"原则在 BMAD-METHOD 自身仓库中的落地。

与 bmad-architecture 的分工

设计决策由bmad-architecture做出。当bmad-project-context发现某个设计决策存在真实的取舍、多个可行形态、意见分歧时，它不会悄悄替用户下结论，而是引导用户到bmad-architecture处理。SKILL.md 的 Greenfield 章节同样规定：真正有争议的设计决策交给bmad-architecture，尚不存在的命令要写成显式 TODO（指明已确定的栈），绝不能把猜测的调用当作事实陈述，待代码出现后的首次 Refresh 再验证。

取代旧技能与演进依据

原文档以:::note[폐기됨: bmad-document-project 및 bmad-generate-project-context]说明两个旧技能均已废弃并指向本技能：bmad-generate-project-context曾生成单个project-context.md，若存在旧文件，Setup 流程会提议吸收其内容，不会任其搁置；bmad-document-project曾扫描既有仓库生成文档，但研究结果表明该路径无效，深度解释系统与设计依据的工作性质不同，将作为独立功能另行提供。SKILL.md 的 Migration 章节补充了迁移细节：检测到旧技能生成的project-context.md（通常位于{output_folder}）时在第 1 步读取并提议吸收，未经同意不删除、也不静默孤立该文件。

背后的理论依据完整记录在姊妹文档 docs/ko-kr/explanation/project-context-theory.md 中，要点包括：对比研究表明代理直接读代码比读文档效果显著更好，而意图、理由与主动放弃的替代方案无法从源码恢复；大多数AGENTS.md无效的原因正是重复了仓库中已有、可推导的内容（研究数据显示文件存在与否不影响任务成功率，推理成本反而增加约 20%）；而一份 40KB 压缩为 8KB 的文档索引放入AGENTS.md后通过率达到 100%（无文档 53%），说明"不放仓库重述、只放模型不知道的知识"才是关键；"需要代理自行判断是否取用"的索引会被跳过，因此关键信息必须放在始终加载的文件里，指向其他文件的指针必须附上代理可直接观察的触发条件（路径、文件类型、具名任务），而非需要代理自我判断的条件。

维护纪律：块必须持续证明自身价值

技能的维护模型把上下文视为"必须持续证明值得保留的负担"，而不是资产——范围越大价值越高的旧假设被明确抛弃。每条线都经受"修剪测试"：删除这一行会改变代理行为吗？不会就删。但对人写的行，该测试只打开候选资格，删除仍须满足 references/best-practices.md 中规定的四条删除理由之一：(1) 过时或错误；(2) 已被机制强制（hook、linter、格式化器或 CI 检查已能拦截该违规）；(3) 有害或自相矛盾；(4) 用户以逐条方式批准。"最近没出过事"不构成删除理由——有效的规则会自行抹去失败痕迹；"仓库某处能查得到"也绝不单独构成删除理由。政策与陷阱只有在所防护的对象消失或用户主动废弃时才可移除。Refresh 重验每条注意项与溯源行、对照记录的 SHA 之后的重命名与删除逐行更新、永不重问上一轮已定案的内容；Audit 后块保持小于或等于原规模；能机械预防的问题优先路由到 hook、lint 或 CI 检查，检查落地后其对应行即被删除。Record 只接受真实观察到的代理错误作为陷阱来源——一次发生记为笔记，反复或高代价的错误才升级为一行。首次创建块很容易，真正的价值在于持续保持其准确，这正是 Refresh 与 Audit 被设计为独立意图而非文档附录的原因。

快速上手路径

按 docs/ko-kr/how-to/project-context.md 的说明，直接以自然语言描述意图即可触发技能（如"帮我设置 AGENTS.md"、"接纳我现有的 AGENTS.md"、"刷新上下文"、"审计上下文"、"代理老是用错的测试运行器"），技能会自动选择合适意图；若在仓库外运行，需指定目标仓库路径，当路径解析到多个工作树时，技能会在写入前向你确认。四步走完即完成一轮：运行技能 → 告知你已知的规则（对新建项目这是全部内容，对既有代码库则是扫描够不到的另一半）→ 技能验证其余信息（核对每条路径，阅读package.json、Makefile、CI 配置，但不照抄脚本，只记录该用哪个命令、纠错与注意项）→ 展示并批准完整块后写入标记之间，随后技能说明取舍原因、加载方式及维护建议（重大变更后重跑、犯错当场 Record、能用检查就优先检查而非加行、跨项目重复或个人偏好放入全局代理配置）。技能不提交，变更留在工作树供你审查。

• AI 技能
• 人工智能
• 开发工具