为代码仓库建立/刷新 AI 代理指令（AGENTS.md…

当需要为某个仓库设置、采纳、刷新或审计 AI 代理指令（AGENTS.md 中的托管块），或记录代理犯过的错误时使用。

适用场景

解决思路

1. 解析定制配置：运行 `uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow`；若脚本不存在，说明此处未配置 BMad，提议运行 `bmad` 技能的 setup（必要时先 `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. 检测意图并问候用户：setup（目标中无有意义的指令文件——仅有脚手架、空标题、注释、单行 import 不算有意义；不确定时用 adopt，因为采纳近乎空文件只多一条小账目，而 setup 一个有意义文件会丢失指令）、adopt（指令文件有内容但无托管块，无论状态与作者，是 refresh 的迁移形式，该文件为基线，其中每条指令进入第 1 步账目）、refresh（已存在托管块）、record（用户报告代理犯错）、audit（重新验证并修剪）。若用户给出的意图与检测结果矛盾（如对已有内容的文件用 setup），要指出并确认，绝不静默服从。把 `{workflow.external_sources}` 并入来源列表。执行 `{workflow.activation_steps_append}`。
5. 第 1 步 评估并报告：读取 `AGENTS.md`、各 harness/代理专用规则文件、docs 目录及任何含经验教训的笔记，按 `best-practices.md` 报告现状与差距。现有指令是要改进的基线，绝不当作可丢弃的原料。建立账目（ledger）：每个现有小节和每条独立有意义的指令一条，初始为 `retain` 或 `rewrite`，记录没有它代理会做错什么。条目在第 2–4 步随证据落定为 `retain | rewrite | relocate | automate | delete`，各带原因、证据、删除风险、迁移目的地、批准标记。删除需符合 `best-practices.md` 中四条依据之一；迁移目的地必须本身会被加载或位于可观察触发器之后——移入无人读取的文件等同删除，需其依据。setup 无可映射内容、不开账目；refresh 为拟改动或删除的行（含块自身）开条目。指令文件之外发现的教训（README 警告、笔记文件）是普通候选，不是账目条目。
6. 若目标含可分离单元（列出成员的 workspace manifest，或带自身构建清单的目录），命名它们并询问本次是仅根、全部还是哪些。无此证据则不要问。兄弟仓库不是子级，各自是独立目标，逐个提供。
7. 第 2 步 询问用户带来的规则：与仓库行为无关的规则——治理、安全合规、编码标准、风格指南、冻结区域。也索取外部文档（手册、wiki、架构文档、MCP 知识库），记下路径但暂不读取。绿地项目这就是全部内容；棕地项目这是扫描触及不到的另一半。
8. 第 3 步 发现并验证：用并行子代理针对各小节所需展开——可执行配置与 CI 用于策略及其已声明内容，受跟踪源码用于约定与边界，定向历史用于原因仍须成立的约束。读取 `package.json`、`Makefile`、`pyproject.toml`、贡献指南、PR 模板、CI 配置，以了解该块不得重复什么；其注意事项来自第 4 步的人工。对每条指名文件的声明做路径校验。对块将做出的每条关于命令行为的声明，读取运行它的目标或脚本# 验证该声明。第 1 步确认的每个子级按自身范围、对照自身清单扫描。
9. 第 4 步 就缺口访谈：只问扫描触及不到的——代理在此反复做错什么、什么不可触碰、某领域术语含义、某约束为何存在。绝不问扫描能回答的问题；让用户确认已路径校验的声明或配置文件已写明的内容是缺陷。问回忆性问题，不给审查清单；绝不把扫描造成的选择题抛给用户。本次会话中犯下并被发现的错误是观察到的证据，可主动提供。本次阅读中发现的、正确形式并非显然猜测的可重复命令是候选行，例如 `uv run pytest`（直接 `pytest` 看似正确但在项目环境外运行）。每批最多八个，越少越好；一批无新信息即应写入。当仓库与用户矛盾时，出示证据并询问；绝不照写声明，也绝不静默丢弃。
10. 第 5 步 先展示块再写入：对照 `template.md` 撰写。对每个候选先问 hook、lint 规则或 CI 检查是否比文字更好；若是则提议该检查，被拒时该行作为兜底。标为 `automate` 的账目条目在其检查就位前保留指令（后续运行在检查上线后依依据 2 删除该行）。写入前展示完整块及每个子块——一次批准覆盖整套。同时呈现已落定的账目：仅给替换文本是不完整提案，只显示所得而隐藏所失。每条现有指令都带决定与原因出现；保留完整规则的 retain 和 rewrite 可合并；若 rewrite 削弱、收窄或丢弃规则的一部分，把丢失部分当作删除单独列出。保留规则本身；示例可解释但不能替代规则。每个迁移、自动化、删除都逐项列出。不基于前三条依据的删除需逐行批准——批准块不等于批准它；被拒的删除、迁移或自动化回退为 retain。批准后在标记之间拼接——拼接本身不触碰标记之外。标记外文本只能通过已落定账目条目或用户已见的修复提议改动，绝不作为拼接副作用。每条来源行填入今日日期与已验证 SHA。
11. 若别处指令与块矛盾且会改变行为（过时的 `CLAUDE.md` 行、已废弃命令），向该文件提议修复。两条同时生效的矛盾指令是缺陷。绝不提交。
12. 第 6 步 收尾：说明写入了什么、遗漏了什么及原因，以及（adopt 或 refresh 后）每条现有指令的去向。用用户的语言、依据 `best-practices.md` 解释为什么——为什么小、为什么仓库已声明的内容不进块、为什么坑点在其成因消失前保留。说明它如何加载，以及其他 harness 文件可指向它。说明用户提交这些指令改动时适用的分支、工单、提交或 PR 规则。维护：重大变更后重跑，代理一犯错就 `record`，优先用检查而非新行。跨项目重复的规则、或个人而非团队的规则，应放入其全局代理配置。
13. Refresh：步骤相同，第 1 步作为 diff。读取来源行，重新验证每条路径与注意事项，并对每行运行自记录 SHA 起的 `git log --diff-filter=DR --name-only`——更新或删除证据已消失的行。每个拟删除都是第 5 步展示的账目条目，绝不静默编辑；块外手写指令按 adopt 处理——任何触及它们的提议进入账目。绝不重问上次运行已落定的事；访谈缩小到团队工作方式的变化。块只在新证据上增长。
14. Adoption：对从未被本技能触碰过的指令做 refresh。上次运行未落定任何事，故完整访谈适用——文件本身是维护者证词，账目是本次运行的主要产出：用户应能读懂并看到其每条指令的去向。提案说明指令被移出的每个文件还剩什么——通常是 `CLAUDE.md` 缩减为 `@AGENTS.md`，前提是该 import 对所用每个 harness 已验证，如同任何加载机制。没有指令同时存在于两个被加载文件（会被付两次费）；重复（逐字或改写）只保留一次——块保留幸存者——并同时落定两个条目。
15. Greenfield：由规格或规划文档播种，或仅靠访谈。尚不存在的命令写成明确 TODO 并指名已定技术栈，绝不把猜测的调用写成事实，待代码存在后首次 refresh 时验证。真正有争议的设计决策（真实权衡、多种可行形态）交给 `bmad-architecture`。
16. Migration：若目标有来自已退役技能的 `project-context.md`（通常在 `{output_folder}` 下），第 1 步读取并提议吸收其内容。未经同意不删除，也不静默孤立它。
17. Record：在代理犯错当下捕获一个观察到的错误——这是坑点唯一可接受的来源。记录任务、错误、纠正及其证据。检查块中是否已有覆盖它的行。单次发生仅记录；反复或代价高的错误立即成行——命令错误时在 **Running and verifying** 下写精确调用，否则写成坑点。写入并展示 diff。若可机械预防，改为提议 hook、lint 规则或 CI 检查。
18. Audit：重新检查每条注意事项，对每个文件做路径校验，跟随每个指针，并对每行自问删除它是否会改变代理行为。对照运行它的目标或脚本验证每条命令声明。检查与其他指令文件的矛盾。失败的行被修复、移到可观察触发器之后，或成为账目条目：删除需符合 `best-practices.md` 中四条依据之一，按第 5 步呈现并落定后才删除。**策略或坑点仅在其守护之物消失或用户退役时才移除；最近没失败不构成依据。** Audit 结束时规模变小或持平。
19. Children：当工作持续落在某组件、嵌套仓库或抽出的规则文件，且所有条件成立时，它按同样形态获得自己的文件：其规则为该子树专属、内容充实（几条规则不算文件）、拆分实质减小父块、加载机制对所用每个 harness 已验证（须检查，绝不假设）、用户批准拆分。即便加载已验证，当规则必须在会话进入该目录前生效、或违反它会影响子级外工作时，仍保留在根。否则规则以路径限定行留在父块（如「in `src/importer/`: ...」），成本低于无人加载的文件。加载检查的原因见 `best-practices.md`。仅当触发器不是路径时才用链接文件。选定的子级若最终没有父块未说的内容，就不建文件，说明并继续。在父块 **Where things are** 中列出每个子级一行及其路径；发现绝不依赖 harness 找到它。

适用边界 · 注意事项

• 需要先安装并配置 BMad 技能体系（`_bmad` 脚本、`bmad` 技能）才能运行，纯独立环境需走降级路径。
• 不适用于没有可提交权限的仓库工作树，或目标解析到多个工作树时——必须先询问再写入。
• 不负责提交（never commit），也不处理真正有争议的架构设计决策（应交给 `bmad-architecture`）。