bmad-project-context

概述

一次对话，产出一份仓库的 Agent 指令：AGENTS.md 内一个经过验证的小区块。用户带来希望被遵循的规则——治理、安全、标准——仓库则提供其余部分，并加以验证。

始终以对话方式进行；每次写入都由用户批准。

参数： intent（setup | adopt | refresh | record | audit）；目标仓库或路径；额外的源路径或 URL。

解析规则

• 裸路径和 {skill-root}（例如 references/best-practices.md）从本 skill 的安装目录解析。
• {project-root} → 项目工作目录。
• Target → 被描述的仓库，默认为 {project-root}。如果它解析到多个工作树，或解析到用户无法提交的工作树，写入前先询问。

激活时

1. 解析自定义配置：uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow。

   • 未找到脚本：此处未设置 BMad。提议运行 bmad skill 的设置流程；如果你还没有 bmad，先安装它（npx skills add bmad-code-org/BMAD-METHOD --skill bmad），然后再次运行该命令。
   • 任何其他失败：直接读取 {skill-root}/customize.toml 并使用默认值。

   执行 {workflow.activation_steps_prepend}；将 {workflow.persistent_facts} 中的条目视为常驻上下文（file: = 要加载的路径/通配模式，其余按原文处理）。

2. 配置：如果 {project-root}/_bmad 存在，运行 uv run {project-root}/_bmad/scripts/resolve_config.py --project-root {project-root} 并读取 {output_folder}。独立运行时：跳过。

3. 在做任何其他事之前，先加载 references/best-practices.md 和 references/template.md。 下面的每个决策都依据它们做出。

4. 检测 intent 并问候用户：setup（目标中没有指令文件带有有意义的内容——仅有脚手架、空标题、一条注释、单独一行 import，都不算有意义；拿不准时用 adopt，因为采用一个近乎空的文件只需付出很小的台账代价，而对一个有意义的文件执行 setup 则会丢失指令）、adopt（某个指令文件有内容但没有受管区块，无论其状态如何、由谁编写——这是 refresh 的迁移形式；该文件即为基线，其中的每条指令都进入步骤 1 的台账）、refresh（存在受管区块）、record（用户报告 Agent 犯下的错误）、audit（重新验证并精简）。所提供的 intent 若与检测结果相矛盾——例如对已有内容的文件使用 setup——应明确指出并请用户确认，绝不默默照办。将 {workflow.external_sources} 并入源列表。执行 {workflow.activation_steps_append}。

Setup、Adoption 和 Refresh 步骤

步骤 5 之前不要写入！

1. 评估并报告

阅读 AGENTS.md、harness 或 Agent 专用的规则文件、docs 文件夹，以及任何承载经验教训的笔记。按照 best-practices.md，报告哪些内容已存在、其水平如何。

现有指令是要改进的基线，绝不是可以丢弃的原材料。建立一份台账：每个现有章节、每条独立有意义的指令各占一条，初始状态为 retain 或 rewrite，并记录没有它 Agent 会弄错什么。随着第 2–4 步中证据的出现，条目最终确定为 retain | rewrite | relocate | automate | delete，每条都附上原因、证据、移除后的风险、迁移目的位置以及审批标记。删除需要有 best-practices.md 中四条依据之一，而迁移目的位置本身必须会被加载，或位于可观察的触发条件之后——迁入一个无人读取的文件就是删除，同样需要依据。Setup 没有可映射的内容，也不开台账；refresh 会为其提议修改或删除的行开条目，包括该块自身的行。在指令文件之外发现的教训——README 中的警告、笔记文件——只是普通候选项，不是台账条目。

如果目标包含可分离的单元——列出成员的 workspace 清单，或自带构建清单的目录——请将其命名，并询问本次运行是只覆盖根目录、全部覆盖，还是覆盖其中哪些。没有这类证据就不要问。同级仓库不是子级；每个都是独立目标，依次提出。

2. 询问他们带来什么

无论仓库做什么都要遵循的规则：治理、安全与合规、编码规范、风格指南、冻结区域。也要询问外部文档——手册、wiki、架构文档、MCP 知识库。记下路径；暂时不要阅读。

Greenfield：这就是全部内容。Brownfield：这是扫描触及不到的那一半。

3. 发现并验证

针对各章节所需的内容，用并行子 Agent 全面铺开——可执行配置和 CI，用于了解策略及其已声明的内容；受跟踪的源码，用于了解约定和边界；有针对性的历史记录，用于了解其理由至今仍成立的约束。

阅读 package.json、Makefile、pyproject.toml、贡献指南、pull request 模板和 CI 配置，是为了知道该块不得重复什么。它们的注意事项来自第 4 步中的人类。对每条指名文件的断言都要做路径检查。对于该块将就某条命令的作用所做的每条断言，阅读运行它的目标或脚本并验证该断言。

第 1 步中确认的每个子级都作为独立范围，对照其自身的清单进行扫描。

4. 访谈缺口

只问扫描触及不到的内容：Agent 在这里总是弄错什么、什么属于禁区、某个领域术语是什么意思、某个约束为何存在。

• 绝不要问扫描能回答的问题。让用户确认一条已做路径检查的断言，或确认配置文件已声明的内容，都是缺陷。
• 问回忆性问题，而不是审查清单。绝不要把扫描造成的选项难题丢给用户。
• 本次会话中犯过并已发现的一个错误是观察到的证据——可以提出来。
• 在本次会话中读到的任何内容——日志、文档、其自身的运行记录——里发现的一条可重复命令，如果其正确形式并非显而易见的猜测，就是候选行：可以提出来。例如 uv run pytest，而看起来正确的 pytest 实际会在项目环境之外运行。
• 每批最多八条；越少越好。一批没有产生新内容就意味着可以写了。
• 当仓库与用户说法矛盾时，展示证据并询问。绝不要按用户所说写下该断言，也绝不要默默丢弃它。

5. 先展示块，再写入

对照 template.md 撰写。对于每一个候选条目，先问：钩子、lint 规则或 CI 检查是否能比文字说明更好地落实它？如果可以，就提出该检查，而这一行则成为对方拒绝时的后备方案。标记为 automate 的账本条目会保留其指令，直到相应检查就位为止（检查上线后，后续运行会依据第 2 条理由删除该行）。

先展示完整块，再写入，并同时展示它的每一个子块——一次批准覆盖整套内容。连同它一起呈现已定稿的账本：只给出替换文本是不完整的提案，因为它展示了用户得到什么，却隐藏了用户失去什么。每一条现有指令都要出现，并附上其决定和理由。保留以及保持完整规则的改写可以合并分组。如果改写弱化、收窄或删除了某条规则的一部分，就把丢失的部分当作删除处理并单独列出。保留规则本身；示例可以解释规则，但不能取代规则。每一次迁移、自动化与删除都逐项列出。不基于前三条理由中任何一条的删除，需逐项批准——批准整个块并不等于批准它——而被拒绝的删除、迁移或自动化则恢复为保留。批准后，在标记之间进行拼接——拼接本身不触碰标记之外的任何内容。标记之外的文本只能通过已定稿的账本条目或用户已见过的拟议修正来改变，绝不能作为拼接的副作用而改变。为每一行来源信息填入今天的日期和已验证的 SHA。

如果其他地方的某条指令与块内容相矛盾，且这种矛盾会改变行为——例如 CLAUDE.md 中的过时行、已废弃的命令——就向该文件提出修正。两条同时生效且相互矛盾的指令是一种缺陷。

绝不提交。

6. 收尾

• 纳入了什么，遗漏了什么以及原因，并且——在采用或刷新之后——每一条现有指令最终落在了哪里。
• 用用户的说法，依据 best-practices.md 说明原因——为什么它很小，为什么仓库中已经说明的内容不再纳入，为什么某个坑点在成因消失之前一直保留。
• 它如何加载，以及其他 harness 文件可以指向它。
• 当用户提交这些指令变更时适用的任何分支、工单、提交或拉取请求规则。
• 维护：在发生重大变更后重新运行，Agent 一旦做错就立刻 record，优先选择检查而不是新增一行。
• 在用户各项目间重复出现的规则，或属于个人而非团队的规则，应放入他们的全局 Agent 配置。

运行 {workflow.on_complete}。

刷新

步骤相同，第 1 步以 diff 形式进行。读取来源信息行，重新验证每一条路径和每一项注意事项，并针对每一行运行自所记录 SHA 以来的 git log --diff-filter=DR --name-only——更新或删除其依据已不复存在的行。每一项拟议删除都是第 5 步中展示的账本条目，绝不是静默编辑；块之外的手写指令按采用时的方式处理——任何触及它们的提案都要进入账本。绝不要重新询问前一次运行已定稿的内容；访谈收缩为团队工作方式中发生变化的部分。块只在有新的依据时才增长。

采用

针对本技能从未触碰过的指令进行刷新。此前没有任何运行定稿过内容，因此适用完整访谈——而文件本身就是维护者的证词，所以账本是本次运行的主要产出：用户应当能够阅读它，并看到他们的每一条指令去了哪里。

提案要说明每一条被移出指令的文件还剩下什么——通常是 CLAUDE.md 被精简为 @AGENTS.md，前提是该导入已针对所有正在使用的 harness 验证通过，就像任何加载机制一样。任何指令都不应存在于两个已加载文件中，否则就要付出双倍代价；重复内容，无论是逐字相同还是改述，都只保留一次——块保留存活下来的那一条——这也就同时定稿了两个条目。

Greenfield

从完整阅读的计划任务（initiative-.md 或较旧的 SPEC*.md）、规划文档或单独访谈开始。尚不存在的命令应明确写成 TODO，并注明已确定的技术栈，绝不能把猜测的调用方式说成事实；代码存在后，在首次刷新时验证。真正存在争议的设计决策——有实际权衡且存在多种可行方案——交由 bmad-architecture 处理。

Migration

如果目标项目有来自已停用技能的 project-context.md，通常位于 {output_folder} 下，应在步骤 1 中阅读并提出吸收其中内容。未经同意不得删除，也不得悄悄将其弃置。

Record

记录一次实际发生的 Agent 错误——陷阱的唯一允许来源。

记录任务、错误、纠正措施及其证据。检查本节是否已有覆盖该错误的条目。发生一次则记下；反复发生或代价高昂的错误现在就应补充一条——如果是命令错误，应在 Running and verifying 下写出准确调用方式，否则写成陷阱。写好后展示差异。如果能通过机械方式预防，应改为提议添加钩子、Lint 规则或 CI 检查。运行 {workflow.on_complete}。

Audit

重新检查每条注意事项，检查每个文件的路径，跟进每个引用，并逐条确认删除后是否会改变 Agent 的行为。对照目标项目或运行它的脚本，验证每项命令说明。检查是否与其他指令文件矛盾。

不合格的条目应修正、移至可观察触发条件之后，或记入台账：只有符合 best-practices.md 中四项依据之一，且像步骤 5 那样经过提出并确认后，才能删除条目。只有其所保护的对象已不存在或用户决定将其退役时，才能删除策略或陷阱；近期没有再出问题并非依据。 审计后的内容应更少或持平。运行 {workflow.on_complete}。

Children

当工作持续落在某个组件、嵌套仓库或拆分出的规则文件中，且满足所有条件时，应按相同结构将其放入单独文件：规则仅适用于该子树；规则内容足够多（一小组规则不值得单独成文）；拆分能实质性缩减父级区块；已针对所有正在使用的执行环境验证加载机制——必须实际检查，不能想当然；并且用户批准拆分。即使已验证加载，只要规则必须在会话进入该目录前生效，或违反规则可能影响子级范围以外的工作，就应保留在根目录。否则，规则应留在父级区块中，并附上路径限定（例如“在 src/importer/ 中：……”）；这比创建无人加载的文件代价更低。关于加载检查的原因，请参阅 best-practices.md。

仅当触发条件不是路径时，才使用链接文件。

如果选定的子级最终没有任何父级未涵盖的内容，就不要为它创建文件。说明原因后继续。

在父级的 Where things are 中列出每个子级，每项一行并注明其路径。发现子级不能依赖执行环境来完成。