BMAD-METHOD 项目上下文管理实战用 bmad-project-context 打造精准的 AGENTS.md 指令块【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD导读本篇文章聚焦 BMAD-METHOD 仓库中的bmad-project-context技能SKILL.md讲解如何为任意代码仓库生成、采纳、刷新、审计并维护一份小而准的 AI Agent 指令块即AGENTS.md中被!-- bmad:context --标记包围的区块。读完本文你将掌握该技能的五个操作意图setup / adopt / refresh / record / audit、六步对话式工作流、账本ledger机制以及什么该写入、什么必须排除的证据化判定规则并能直接复用它为你的仓库建立可持续的 Agent 运行上下文。一、技能定位产出经过验证的小指令块bmad-project-context的职责一句话概括通过一场对话产出一个仓库的 Agent 指令——AGENTS.md内一块小而经过验证的区块。用户带来他们希望被遵守的规则治理、安全、标准仓库提供其余部分且每一句都由技能验证过。整个过程始终是对话式的每一次写入都必须经用户批准No writes until step 5!技能从不擅自提交Never commit.。技能接收的参数Argsintentsetup|adopt|refresh|record|audit五选一target repo or path目标仓库或路径extra source paths or URLs额外来源路径或 URL。从源码结构看该技能是一个对话即工作流的 Skill 定义不依赖自有脚本核心逻辑全部写在 SKILL.md 的提示词流程中判定规则沉淀在 references/best-practices.md输出模板则来自 references/template.md。技能模块元数据见 module-manifest.toml版本6.13.0-next。二、五个意图先检测再确认技能在激活时会先做意图检测而不是盲目信任用户声明的 intent——如果用户声明与检测结果冲突例如对一份有实际内容的文件声称setup技能会亮出矛盾并请用户确认绝不静默服从。五个意图的判定标准意图触发条件setup目标中没有任何含实质内容的指令文件——只有脚手架、空标题、一行注释或孤立 import 行都不算有意义拿不准时按 adopt 处理采纳一份近乎空白的文件只花一小笔账本开销而 setup 一个有内容文件会丢失指令adopt指令文件有内容但没有受管理区块——无论文件状态如何、谁写的这是 refresh 的迁移形态该文件成为基线其中每条指令都进入第 1 步的账本refresh已存在受管理区块record用户报告 Agent 犯下的错误audit重新验证并修剪record是唯一只接收观察到的一次真实 Agent 失误的意图——它是 pitfall陷阱记录唯一合法的来源。三、六步核心工作流1. 评估并汇报Assess and report读取AGENTS.md、harness 或 Agent 专属规则文件、docs 目录以及任何承载经验的笔记。已有指令是待改进的基线绝不是可丢弃的原材料。此步要开立一份账本ledger对每个既有小节、每条独立有意义的指令各开一个条目初始状态为retain或rewrite每个条目携带若缺失Agent 会出什么错的说明随着第 2–4 步的证据到来条目结算为retain | rewrite | relocate | automate | delete之一并附上理由、证据、删除风险、迁移目的地与批准标记删除必须满足 best-practices.md 中四个理由之一迁移目的地本身必须可被加载或位于可观察的触发器之后——移到无人读取的文件等于删除需要同等理由。若目标包含可分离单元工作区清单列出的成员、或带独立构建清单的子目录技能会点名这些单元并询问本次运行是否只覆盖根目录、全部或其中哪些若无此证据则不提问。兄弟仓库不是子单元各自是独立目标会依次提供。2. 询问用户带来什么Ask what they bring询问与仓库做什么无关、都必须遵守的规则治理、安全与合规、编码标准、风格指南、冻结区域。同时索取外部文档——手册、wiki、架构文档、MCP 知识库。只记下路径此刻不读取。对新项目Greenfield这段对话就是全部内容对既有代码库Brownfield它是任何扫描都够不到的那一半。3. 发现并验证Discover and verify用并行子代理针对各小节所需进行扇出调查可执行配置与 CI用于政策类内容也用于核验其自身已声明的语句受版本控制的源码用于约定与边界定向历史用于理由必须仍然成立的约束。package.json、Makefile、pyproject.toml、贡献指南、PR 模板、CI 配置都会被读取——目的是知道指令块绝不能重复什么。对每条命名文件的说法做路径核验对指令块将声称某命令做什么的每条语句都要读取运行它的目标或脚本并核验。4. 访谈空白区Interview the gaps只问扫描够不到的问题Agent 在这里反复出错的是什么、什么被禁止、某个领域术语的含义、某条约束为何存在。规则明确绝不问扫描能回答的问题——让用户确认一条已路径核验的说法或配置文件已声明的事实属于缺陷问回忆型问题不给清单——绝不把扫描制造的选择题丢给用户本次会话犯过并已发现的错误是观察到的证据可以主动提出本次会话中读到的任何可复现命令日志、文档、其自身运行若其正确形式并非显而易见的猜测是候选行——例如uv run pytest才是对的而表面上看pytest也没错但实际运行在项目环境之外每批最多八个问题越少越好一批问题毫无新收获就意味着该写了当仓库与用户矛盾时展示证据并提问——既不按原样写入用户说法也不静默丢弃。5. 展示区块然后写入Show the block, then write it按 template.md 组装。对每个候选先问hook、lint 规则或 CI 检查是否比散文更能强制它——若是先提议检查该行在用户拒绝时才作为后备账本中标记automate的条目在其检查落地前保留指令检查上线后后续运行按理由 2 删除该行。写入前必须展示完整区块子区块一并展示——一次批准覆盖整组。已结算的账本必须一同呈现仅给替换文本是不完整的提案因为它只展示用户所得、隐藏用户所失。每条既有指令都带其决策与理由保留且未弱化完整规则的retain/rewrite可以分组若重写弱化、收窄或删除了规则的一部分被删部分按删除单独列出。删除若不属于前三项理由陈旧错误 / 机械强制 / 有害矛盾必须逐行单独审批——批准整个区块绝不等于批准删除被拒的删除、迁移或自动化回退为retain。批准后在!-- bmad:context --与!-- /bmad:context --标记之间拼接写入——拼接本身绝不触碰标记之外的任何内容。标记外的文本只能通过已结算的账本条目或用户已看到的修复提案改变。每条 provenance溯源行填入今天的日期与核验过的 commit SHA。若别处指令与区块矛盾且会改变行为过期的CLAUDE.md行、退役的命令则向该文件提出修复——两条同时生效的矛盾指令是缺陷。永不提交。6. 收尾Close汇报写了什么、没写什么及原因adopt/refresh 后每条既有指令的去向用用户的语言解释为什么——为什么区块这么小、为什么仓库已声明的内容被排除在外、为什么 pitfall 在其根因消失前一直保留说明它如何被加载以及其它 harness 文件如何指向它说明用户提交这些指令变更时适用的分支、ticket、commit、PR 规则维护建议重大变更后重跑、Agent 一出错就record、优先用检查而非新增一行跨项目重复的规则、或个人而非团队层面的规则应放进用户的全局 Agent 配置。四、区块模板六个板块与书写纪律template.md 规定区块内按此顺序排列任何没有内容能通过准入规则的板块一律省略绝不写空板块Orientation方向——三到四句话这是什么、技术栈、规划与深入文档在哪Policy政策——组织要求什么Where things are物在何处——入口点以及指向子文件与链接文件的指针Running and verifying运行与验证——正确的运行命令与所需工具版本外加package.json、pyproject.toml、Makefile或 CI 配置尚未说明的内容Conventions that differ from defaults与默认不同的约定Known pitfalls已知陷阱。书写纪律平级标题下用简洁的祈使句除 Orientation 外无散文、无引言、无总结裸事实只能作为指令的理由从句出现——写从搜索中排除vendor/它占跟踪文件的 60%而不是vendor/占跟踪文件的 60%禁令必须指名替代方案整个区块最多两处强调标记。模板自带一个 worked exampleacme-billing 支付服务示例完整展示了从!-- bmad:context --注释含核验日期与 SHA到六个板块再到闭合标记的成品形态可作为实际产出物的直接参照。模板同时提醒provenance 行必须填真实日期和核验所对的 commit SHArefresh 时从该 SHA 做差异对比。五、判定规则什么该写、什么该排除best-practices.md 是整个技能的价值核心它回答仓库的 Agent 指令里到底该放什么。核心测试不是Agent 能否推导出来而是**推导不出来时代价多大**找到它需要多少探索、Agent 有多大可能按时搜对地方而非猜测、它在使用时是否可得还是只在犯错后出现、检索失败的成本是浪费一次搜索还是损坏数据、它是必须成立的规则还是代码已展示的细节。每行都要回答同一个问题删掉它会不会改变 Agent 行为不会就删。能阻止每次会话重复同一昂贵探索的一行哪怕可推导也值得留下而把 Agent 一手的、更准确的读取结果复制一份则不值得——副本会腐烂且每次会话都要付费。准入清单Admit代码无法表达的政策——分支规则、冻结与受保护路径、生成文件、机密、安全与合规必须由人声明或从强制配置读出绝不推断配置文件无法说明的运行事项——根测试脚本在此工作区什么都不做、集成测试需先起服务、全套件要十一分钟所以迭代时跑单文件、Makefile才是真正入口而package.json形同虚设、CI 跑测试脚本不覆盖的 typecheck。显然的猜测就能得到正确调用的命令已由package.json/Makefile/pyproject.toml/CI 声明不值得占行修正、注意事项和正确的命令才值得与生态默认不同的约定——Agent 默认遵循惯例只有偏差值得占行命令调用也算当显而易见的命令在此处是错的裸仓库前缀、必需的包装器精确的正确调用就值得一行且无需先观察到失误有观察证据的陷阱——已记录的经验、维护者的回忆、历史中反复修复的同一错误、或本次会话犯下并已抓住的错误。仓库能产出数百个看起来像陷阱的事实但只有观察到的行为能预测真实失误令人惊讶的扫描发现是要问的问题不是要写的行仓库中不可见的运行时行为——回放的 webhook、撒谎的健康检查端点、环境怪癖——一旦人工确认跨组件规则——在一个文件里改错会在别处破坏东西的规则谁拥有什么、数据如何流动、流水线按什么顺序运行。例如写入必须走 dispatcher直接改 store 会跳过事务importer 是两遍——先逐行校验再提交绝不要在解析循环里写库必需的工具与运行时版本——从声明它们的项目文件读取绝不从本次会话环境读取会话环境回答更快也错得更快入口点与指针——指向工作落点。排除清单Exclude排除内容原因仓库概述、目录树、技术栈清单现场重新推导更准确存储副本会腐烂任何只因有趣而收录的内容兴趣不是需求Agent 本可自我执行的风格规则属于 formatter、linter、hook 或 CI——应提议检查陈词滥调本来就是默认显而易见调用本就正确的命令清单转写从package.json/Makefile/CI 读取即可脚本一改名副本就漂移粘贴的代码、变更日志内容、快速变化的事实立即过时理想状态写是什么意图属于 spec历史与编辑叙述Git 存着历史区块只陈述当下真相退役规则Retire政策或陷阱只在其所守护之物消失、或用户将其退役时才能删除。最近没出事绝不是证据——一条正常工作的规则会抹掉它自己的证据。任何其它既有指令只能依据评判既有文件的四个理由之一删除。规模纪律Size**每一行都在每次会话中付费且随加载集增大指令遵循会退化。**预算超了就砍最弱的行或把它们移到触发器之后——绝不提高预算。十条证据就是十行。采纳的文件也必须适配预算但缩减方式不同先把最弱的指令移出去子文件、链接文档、或强制它的 hook/检查删除仍需四个理由。文件仍然过大且无理由再删时展示给用户由其决定——用户选择的超预算文件好过用户没有参与的被掏空的文件。保持小约束的是技能自己写什么而不是维护者已写的。检索原则Retrieval**必须主动选择去取的索引会被跳过已经在上下文中的索引不会。**一切承重内容留在区块内。指向外部的指针必须命名 Agent 可观察的触发器路径、文件类型、具名任务绝不能是它需要判断的东西当任务复杂时或需要追踪自身状态的东西在首次编辑之前。仅当触发器不是路径时才用链接文件。维护Maintain复查注意事项是否仍然成立变快的慢套件、被修复的 bug 的变通方案对照核验 SHA 之后的删除与重命名逐行 diff在区块内记录 provenance让下次运行知道自己在对什么做 diff失误发生时当场记录而不是评审时一次出现是笔记复发才占一行任何机械可防的问题路由到 hook/lint/CI——落地的检查会删除对应行。评判既有文件Judging an existing file人类写下的每条指令都被假定为有意为之有人为它付过钱通常是看着 Agent 失败。文件是被改进的基线不是原材料。删除必须满足四个理由之一陈旧或错误——所指之物已消失或指令从未为真并点名证据机械强制——hook、linter、formatter 或 CI 检查已能让该指令指出的违规失败。只覆盖相同文件或主题的工具不算强制了这条指令有害或矛盾——把 Agent 指向错误的东西或与另一条生效指令矛盾且无法调和用户批准本次删除——必须逐行单独询问绝不因批准替换区块而暗示。理由 1–3 由本次运行自证并随区块批准理由 4 是其余一切情况都要走的先问路径。除此之外什么都不删。简洁不是理由、最近没出事不是理由、Agent 能推导不是理由、仓库里某个地方找得到单独永远不是理由——那正是掏空好文件的推理方式。被排除清单拒绝的内容目录树、技术栈清单、粘贴代码没有自己的理由按理由 4 提议删除。汇报顺序固定先讲什么不可验证或过时再讲对照各小节缺什么然后讲什么已经很好最后是账本——每条迁移、自动化、删除都逐条列明。已记录的经验是维护者的证词默认保留只有用所指之物已消失或错误的证据才能挑战。六、扩展流程refresh、adopt、greenfield 与迁移Refresh步骤相同但第 1 步是 diff。读取 provenance 行重新核验每条路径与每条注意事项并对照记录的 SHA 运行git log --diff-filterDR --name-only逐行检查——证据消失的行要更新或删除。每条拟删除都是第 5 步展示的账本条目绝非静默编辑。绝不重问先前运行已解决的问题访谈收缩为团队工作方式发生了什么变化。区块只在新证据上增长。Adoption对技能从未触碰过的指令做 refresh。没有先前的结算完整访谈适用文件本身是维护者的证词因此账本是本次运行的主要产出——用户应能读着它看到自己每条指令的去向。提案须说明从哪些文件中移出指令后各文件还剩下什么常见形态CLAUDE.md瘦身为AGENTS.md一行导入前提是已验证每个在用 harness 都支持该导入。同一条指令绝不出现在两个被加载的文件中付两次费重复的——无论逐字还是改写——只保留一次区块保留幸存者两个条目同时结算。Greenfield从 spec 或规划文档播种或仅靠访谈。尚不存在的命令写成显式 TODO 并点名既定技术栈绝不把猜测的调用当事实陈述待代码出现后的首次 refresh 再核验。真正有争议的设计决策真实权衡、多个可行形态交给bmad-architecture。Migration若目标中存在已退役技能bmad-generate-project-context/bmad-document-project遗留的project-context.md通常在{output_folder}下第 1 步读取它并提供吸收其内容的选项。未经同意不删除也不静默弃置。七、record 与 audit错误即入口审计只减不增Record当场捕获一次观察到的 Agent 失误——这是 pitfall 唯一合法的来源。取走任务、失误、纠正及其证据检查区块是否已有覆盖该行的一行单次出现记为笔记反复出现或代价高昂的失误才立即占一行——命令类错误写成Running and verifying下的精确调用其它写成 pitfall写完后展示 diff。若机械可防则提议 hook、lint 或 CI 检查。Audit重新核验每条注意事项、路径核验每个文件、跟进每个指针并问每一行删掉它是否会改变 Agent 行为对照运行它的目标或脚本核验每条命令声明检查与其它指令文件的矛盾。失败的行被修复、移到可观察触发器之后、或变成账本条目——删除仍需 best-practices.md 的四个理由按第 5 步展示并结算后才能移除。政策或陷阱只在其所守护之物消失或用户将其退役时离开最近没失败不是理由。审计结束时区块更小或相等绝不更大。八、子文件Children何时拆分、何时留在根区块当工作持续落在一个组件、嵌套仓库或抽取的规则文件上且每个条件都成立时才为它建立同构的子文件规则是子树专属的、内容可观寥寥几条规则撑不起一个文件、拆分显著减小父区块、加载机制对每个在用 harness 都核验过检查绝不假设且用户批准拆分。即使加载已核验若规则必须在会话进入该目录前生效、或违反它会影响到子树外的工作仍把它留在根区块。否则以路径限定行留在父区块在src/importer/中……比一个没人加载的文件便宜。**仅在触发器不是路径时才用链接文件。**被选中的子文件若最终没有父区块未说过的新内容就不建文件说明原因后继续。每个子文件都要在父区块的Where things are中用一行列出其路径——发现过程绝不依赖 harness 自己找到它。九、定制面workflow 配置与源码佐证技能激活时会解析定制配置执行uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow失败时直接读 customize.toml 用默认值若{project-root}/_bmad存在再运行resolve_config.py读取中央配置。customize.toml 定义了 [workflow] 表该文件被更新时整体覆盖团队覆盖放{project-root}/_bmad/custom/bmad-project-context.toml个人覆盖放...user.toml合并规则为标量后层覆盖、数组追加activation_steps_prepend/activation_steps_append激活前后注入的步骤默认空数组persistent_facts默认故意为空——技能自身的产出AGENTS.md由 harness 加载不经过此数组用户自行追加自己的常驻事实file:为路径/glob其它按原文处理on_complete完成钩子默认空字符串external_sources每次 setup/refresh 默认提供的仓库外来源未验证前不可信支持file:{project-root}/...、file:/abs/path、skill:name、tool:nameMCP 知识库及纯文本常驻事实追加式。源码层面resolve_customization.py 实现了三层 TOML 合并与项目根解析find_project_root以_bmad/优先于.git向上寻找子模块携带.git却未必是 BMad 项目candidate_project_roots按工作目录 → 脚本安装路径 → 技能目录的信任顺序候选若所选根没有该技能定制而其它根有会向 stderr 打印提示而非静默采用。--key支持点路径抽取如workflow输出 JSON 到 stdout。resolve_config.py 则对四层中央 TOML 配置做同样风格的合并与键抽取。这些脚本同时解释了 SKILL.md 中失败时直接读 customize.toml 用默认值这一降级路径的由来resolve_customization.py在配置解析失败时返回非零退出码并打印错误。十、与官方文档、仓库实践的对齐本技能在 BMAD-METHOD 文档体系中对应 Set and Maintain Project Context操作指南与 The Theory of Project Context原理论证。后者的核心论据恰好解释了本技能为何如此克制实测表明仓库级任务中代码访问优于文档访问为 Agent 写的大多数文档反而让它们更糟——测量显示仓库指令文件存在 vs 缺失对成功率无提升且推理成本 20%但对模型训练数据中不存在的框架 API一份压缩的文档索引放入AGENTS.md能把通过率提到100%无文档 53% → 压缩索引 100%40KB 压到 8KB 性能无损Agent 常跳过需要主动选择的检索709 页 wiki 测试中 Agent 跳过索引直接猜路径因此已在上下文中的区块才能承重指针必须命名可观察触发器结论即本技能的产出哲学实现上下文约束、命令、约定、陷阱属于代码仓库必须极小、可核验、每次会话加载规划上下文理由、被拒方案、归属、领域语义属于项目/计划是另一项能力——用同一文件服务两者正是被本技能取代的两个旧技能bmad-generate-project-context、bmad-document-project失败的原因。仓库自身就是本技能的活样本AGENTS.md 展示了规则先行的仓库指令形态Conventional Commits、推送前运行uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.py等它同时印证了 best-practices 中命令正确调用值得一行的原则——正是这类明显猜测会出错未加--frozen、未在确切 checkout 上运行的命令才有资格进入指令块。十一、实战快速上手在目标仓库根目录运行bmad-project-context用平实语言说出意图——set up AGENTS.md、adopt 我们已有的 AGENTS.md、refresh the context、audit our context、agent 总在用错的测试运行器——技能会自动路由到对应意图若不在目标仓库内指明路径该路径解析到多个工作树时先询问树内不可提交时也先询问按第 2–4 步提供治理/安全/风格规则与外部文档等待技能完成扫描验证与空白访谈审阅完整区块与已结算账本逐项批准删除、迁移、自动化需逐项确认批准后内容写入AGENTS.md的!-- bmad:context --标记之间对读取其它文件如CLAUDE.md的工具技能会提议并核验一行AGENTS.md导入标记外内容一律不动技能从不 commit提交这份变更——区块随代码入库团队共享、跨机器一致、与它所约束的代码同版本演进之后保持健康循环重大变更后refresh、Agent 一出错当场record、定期audit只减不增能把规则交给 hook/lint/CI 的尽早移交。bmad-project-context的最终交付物永远是证据允许几行就写几行——保持小、保持核验、保持每行都能改变 Agent 行为。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BMAD-METHOD 项目上下文管理实战：用 bmad-project-context 打造精准的 AGENTS.md 指令块
BMAD-METHOD 项目上下文管理实战用 bmad-project-context 打造精准的 AGENTS.md 指令块【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD导读本篇文章聚焦 BMAD-METHOD 仓库中的bmad-project-context技能SKILL.md讲解如何为任意代码仓库生成、采纳、刷新、审计并维护一份小而准的 AI Agent 指令块即AGENTS.md中被!-- bmad:context --标记包围的区块。读完本文你将掌握该技能的五个操作意图setup / adopt / refresh / record / audit、六步对话式工作流、账本ledger机制以及什么该写入、什么必须排除的证据化判定规则并能直接复用它为你的仓库建立可持续的 Agent 运行上下文。一、技能定位产出经过验证的小指令块bmad-project-context的职责一句话概括通过一场对话产出一个仓库的 Agent 指令——AGENTS.md内一块小而经过验证的区块。用户带来他们希望被遵守的规则治理、安全、标准仓库提供其余部分且每一句都由技能验证过。整个过程始终是对话式的每一次写入都必须经用户批准No writes until step 5!技能从不擅自提交Never commit.。技能接收的参数Argsintentsetup|adopt|refresh|record|audit五选一target repo or path目标仓库或路径extra source paths or URLs额外来源路径或 URL。从源码结构看该技能是一个对话即工作流的 Skill 定义不依赖自有脚本核心逻辑全部写在 SKILL.md 的提示词流程中判定规则沉淀在 references/best-practices.md输出模板则来自 references/template.md。技能模块元数据见 module-manifest.toml版本6.13.0-next。二、五个意图先检测再确认技能在激活时会先做意图检测而不是盲目信任用户声明的 intent——如果用户声明与检测结果冲突例如对一份有实际内容的文件声称setup技能会亮出矛盾并请用户确认绝不静默服从。五个意图的判定标准意图触发条件setup目标中没有任何含实质内容的指令文件——只有脚手架、空标题、一行注释或孤立 import 行都不算有意义拿不准时按 adopt 处理采纳一份近乎空白的文件只花一小笔账本开销而 setup 一个有内容文件会丢失指令adopt指令文件有内容但没有受管理区块——无论文件状态如何、谁写的这是 refresh 的迁移形态该文件成为基线其中每条指令都进入第 1 步的账本refresh已存在受管理区块record用户报告 Agent 犯下的错误audit重新验证并修剪record是唯一只接收观察到的一次真实 Agent 失误的意图——它是 pitfall陷阱记录唯一合法的来源。三、六步核心工作流1. 评估并汇报Assess and report读取AGENTS.md、harness 或 Agent 专属规则文件、docs 目录以及任何承载经验的笔记。已有指令是待改进的基线绝不是可丢弃的原材料。此步要开立一份账本ledger对每个既有小节、每条独立有意义的指令各开一个条目初始状态为retain或rewrite每个条目携带若缺失Agent 会出什么错的说明随着第 2–4 步的证据到来条目结算为retain | rewrite | relocate | automate | delete之一并附上理由、证据、删除风险、迁移目的地与批准标记删除必须满足 best-practices.md 中四个理由之一迁移目的地本身必须可被加载或位于可观察的触发器之后——移到无人读取的文件等于删除需要同等理由。若目标包含可分离单元工作区清单列出的成员、或带独立构建清单的子目录技能会点名这些单元并询问本次运行是否只覆盖根目录、全部或其中哪些若无此证据则不提问。兄弟仓库不是子单元各自是独立目标会依次提供。2. 询问用户带来什么Ask what they bring询问与仓库做什么无关、都必须遵守的规则治理、安全与合规、编码标准、风格指南、冻结区域。同时索取外部文档——手册、wiki、架构文档、MCP 知识库。只记下路径此刻不读取。对新项目Greenfield这段对话就是全部内容对既有代码库Brownfield它是任何扫描都够不到的那一半。3. 发现并验证Discover and verify用并行子代理针对各小节所需进行扇出调查可执行配置与 CI用于政策类内容也用于核验其自身已声明的语句受版本控制的源码用于约定与边界定向历史用于理由必须仍然成立的约束。package.json、Makefile、pyproject.toml、贡献指南、PR 模板、CI 配置都会被读取——目的是知道指令块绝不能重复什么。对每条命名文件的说法做路径核验对指令块将声称某命令做什么的每条语句都要读取运行它的目标或脚本并核验。4. 访谈空白区Interview the gaps只问扫描够不到的问题Agent 在这里反复出错的是什么、什么被禁止、某个领域术语的含义、某条约束为何存在。规则明确绝不问扫描能回答的问题——让用户确认一条已路径核验的说法或配置文件已声明的事实属于缺陷问回忆型问题不给清单——绝不把扫描制造的选择题丢给用户本次会话犯过并已发现的错误是观察到的证据可以主动提出本次会话中读到的任何可复现命令日志、文档、其自身运行若其正确形式并非显而易见的猜测是候选行——例如uv run pytest才是对的而表面上看pytest也没错但实际运行在项目环境之外每批最多八个问题越少越好一批问题毫无新收获就意味着该写了当仓库与用户矛盾时展示证据并提问——既不按原样写入用户说法也不静默丢弃。5. 展示区块然后写入Show the block, then write it按 template.md 组装。对每个候选先问hook、lint 规则或 CI 检查是否比散文更能强制它——若是先提议检查该行在用户拒绝时才作为后备账本中标记automate的条目在其检查落地前保留指令检查上线后后续运行按理由 2 删除该行。写入前必须展示完整区块子区块一并展示——一次批准覆盖整组。已结算的账本必须一同呈现仅给替换文本是不完整的提案因为它只展示用户所得、隐藏用户所失。每条既有指令都带其决策与理由保留且未弱化完整规则的retain/rewrite可以分组若重写弱化、收窄或删除了规则的一部分被删部分按删除单独列出。删除若不属于前三项理由陈旧错误 / 机械强制 / 有害矛盾必须逐行单独审批——批准整个区块绝不等于批准删除被拒的删除、迁移或自动化回退为retain。批准后在!-- bmad:context --与!-- /bmad:context --标记之间拼接写入——拼接本身绝不触碰标记之外的任何内容。标记外的文本只能通过已结算的账本条目或用户已看到的修复提案改变。每条 provenance溯源行填入今天的日期与核验过的 commit SHA。若别处指令与区块矛盾且会改变行为过期的CLAUDE.md行、退役的命令则向该文件提出修复——两条同时生效的矛盾指令是缺陷。永不提交。6. 收尾Close汇报写了什么、没写什么及原因adopt/refresh 后每条既有指令的去向用用户的语言解释为什么——为什么区块这么小、为什么仓库已声明的内容被排除在外、为什么 pitfall 在其根因消失前一直保留说明它如何被加载以及其它 harness 文件如何指向它说明用户提交这些指令变更时适用的分支、ticket、commit、PR 规则维护建议重大变更后重跑、Agent 一出错就record、优先用检查而非新增一行跨项目重复的规则、或个人而非团队层面的规则应放进用户的全局 Agent 配置。四、区块模板六个板块与书写纪律template.md 规定区块内按此顺序排列任何没有内容能通过准入规则的板块一律省略绝不写空板块Orientation方向——三到四句话这是什么、技术栈、规划与深入文档在哪Policy政策——组织要求什么Where things are物在何处——入口点以及指向子文件与链接文件的指针Running and verifying运行与验证——正确的运行命令与所需工具版本外加package.json、pyproject.toml、Makefile或 CI 配置尚未说明的内容Conventions that differ from defaults与默认不同的约定Known pitfalls已知陷阱。书写纪律平级标题下用简洁的祈使句除 Orientation 外无散文、无引言、无总结裸事实只能作为指令的理由从句出现——写从搜索中排除vendor/它占跟踪文件的 60%而不是vendor/占跟踪文件的 60%禁令必须指名替代方案整个区块最多两处强调标记。模板自带一个 worked exampleacme-billing 支付服务示例完整展示了从!-- bmad:context --注释含核验日期与 SHA到六个板块再到闭合标记的成品形态可作为实际产出物的直接参照。模板同时提醒provenance 行必须填真实日期和核验所对的 commit SHArefresh 时从该 SHA 做差异对比。五、判定规则什么该写、什么该排除best-practices.md 是整个技能的价值核心它回答仓库的 Agent 指令里到底该放什么。核心测试不是Agent 能否推导出来而是**推导不出来时代价多大**找到它需要多少探索、Agent 有多大可能按时搜对地方而非猜测、它在使用时是否可得还是只在犯错后出现、检索失败的成本是浪费一次搜索还是损坏数据、它是必须成立的规则还是代码已展示的细节。每行都要回答同一个问题删掉它会不会改变 Agent 行为不会就删。能阻止每次会话重复同一昂贵探索的一行哪怕可推导也值得留下而把 Agent 一手的、更准确的读取结果复制一份则不值得——副本会腐烂且每次会话都要付费。准入清单Admit代码无法表达的政策——分支规则、冻结与受保护路径、生成文件、机密、安全与合规必须由人声明或从强制配置读出绝不推断配置文件无法说明的运行事项——根测试脚本在此工作区什么都不做、集成测试需先起服务、全套件要十一分钟所以迭代时跑单文件、Makefile才是真正入口而package.json形同虚设、CI 跑测试脚本不覆盖的 typecheck。显然的猜测就能得到正确调用的命令已由package.json/Makefile/pyproject.toml/CI 声明不值得占行修正、注意事项和正确的命令才值得与生态默认不同的约定——Agent 默认遵循惯例只有偏差值得占行命令调用也算当显而易见的命令在此处是错的裸仓库前缀、必需的包装器精确的正确调用就值得一行且无需先观察到失误有观察证据的陷阱——已记录的经验、维护者的回忆、历史中反复修复的同一错误、或本次会话犯下并已抓住的错误。仓库能产出数百个看起来像陷阱的事实但只有观察到的行为能预测真实失误令人惊讶的扫描发现是要问的问题不是要写的行仓库中不可见的运行时行为——回放的 webhook、撒谎的健康检查端点、环境怪癖——一旦人工确认跨组件规则——在一个文件里改错会在别处破坏东西的规则谁拥有什么、数据如何流动、流水线按什么顺序运行。例如写入必须走 dispatcher直接改 store 会跳过事务importer 是两遍——先逐行校验再提交绝不要在解析循环里写库必需的工具与运行时版本——从声明它们的项目文件读取绝不从本次会话环境读取会话环境回答更快也错得更快入口点与指针——指向工作落点。排除清单Exclude排除内容原因仓库概述、目录树、技术栈清单现场重新推导更准确存储副本会腐烂任何只因有趣而收录的内容兴趣不是需求Agent 本可自我执行的风格规则属于 formatter、linter、hook 或 CI——应提议检查陈词滥调本来就是默认显而易见调用本就正确的命令清单转写从package.json/Makefile/CI 读取即可脚本一改名副本就漂移粘贴的代码、变更日志内容、快速变化的事实立即过时理想状态写是什么意图属于 spec历史与编辑叙述Git 存着历史区块只陈述当下真相退役规则Retire政策或陷阱只在其所守护之物消失、或用户将其退役时才能删除。最近没出事绝不是证据——一条正常工作的规则会抹掉它自己的证据。任何其它既有指令只能依据评判既有文件的四个理由之一删除。规模纪律Size**每一行都在每次会话中付费且随加载集增大指令遵循会退化。**预算超了就砍最弱的行或把它们移到触发器之后——绝不提高预算。十条证据就是十行。采纳的文件也必须适配预算但缩减方式不同先把最弱的指令移出去子文件、链接文档、或强制它的 hook/检查删除仍需四个理由。文件仍然过大且无理由再删时展示给用户由其决定——用户选择的超预算文件好过用户没有参与的被掏空的文件。保持小约束的是技能自己写什么而不是维护者已写的。检索原则Retrieval**必须主动选择去取的索引会被跳过已经在上下文中的索引不会。**一切承重内容留在区块内。指向外部的指针必须命名 Agent 可观察的触发器路径、文件类型、具名任务绝不能是它需要判断的东西当任务复杂时或需要追踪自身状态的东西在首次编辑之前。仅当触发器不是路径时才用链接文件。维护Maintain复查注意事项是否仍然成立变快的慢套件、被修复的 bug 的变通方案对照核验 SHA 之后的删除与重命名逐行 diff在区块内记录 provenance让下次运行知道自己在对什么做 diff失误发生时当场记录而不是评审时一次出现是笔记复发才占一行任何机械可防的问题路由到 hook/lint/CI——落地的检查会删除对应行。评判既有文件Judging an existing file人类写下的每条指令都被假定为有意为之有人为它付过钱通常是看着 Agent 失败。文件是被改进的基线不是原材料。删除必须满足四个理由之一陈旧或错误——所指之物已消失或指令从未为真并点名证据机械强制——hook、linter、formatter 或 CI 检查已能让该指令指出的违规失败。只覆盖相同文件或主题的工具不算强制了这条指令有害或矛盾——把 Agent 指向错误的东西或与另一条生效指令矛盾且无法调和用户批准本次删除——必须逐行单独询问绝不因批准替换区块而暗示。理由 1–3 由本次运行自证并随区块批准理由 4 是其余一切情况都要走的先问路径。除此之外什么都不删。简洁不是理由、最近没出事不是理由、Agent 能推导不是理由、仓库里某个地方找得到单独永远不是理由——那正是掏空好文件的推理方式。被排除清单拒绝的内容目录树、技术栈清单、粘贴代码没有自己的理由按理由 4 提议删除。汇报顺序固定先讲什么不可验证或过时再讲对照各小节缺什么然后讲什么已经很好最后是账本——每条迁移、自动化、删除都逐条列明。已记录的经验是维护者的证词默认保留只有用所指之物已消失或错误的证据才能挑战。六、扩展流程refresh、adopt、greenfield 与迁移Refresh步骤相同但第 1 步是 diff。读取 provenance 行重新核验每条路径与每条注意事项并对照记录的 SHA 运行git log --diff-filterDR --name-only逐行检查——证据消失的行要更新或删除。每条拟删除都是第 5 步展示的账本条目绝非静默编辑。绝不重问先前运行已解决的问题访谈收缩为团队工作方式发生了什么变化。区块只在新证据上增长。Adoption对技能从未触碰过的指令做 refresh。没有先前的结算完整访谈适用文件本身是维护者的证词因此账本是本次运行的主要产出——用户应能读着它看到自己每条指令的去向。提案须说明从哪些文件中移出指令后各文件还剩下什么常见形态CLAUDE.md瘦身为AGENTS.md一行导入前提是已验证每个在用 harness 都支持该导入。同一条指令绝不出现在两个被加载的文件中付两次费重复的——无论逐字还是改写——只保留一次区块保留幸存者两个条目同时结算。Greenfield从 spec 或规划文档播种或仅靠访谈。尚不存在的命令写成显式 TODO 并点名既定技术栈绝不把猜测的调用当事实陈述待代码出现后的首次 refresh 再核验。真正有争议的设计决策真实权衡、多个可行形态交给bmad-architecture。Migration若目标中存在已退役技能bmad-generate-project-context/bmad-document-project遗留的project-context.md通常在{output_folder}下第 1 步读取它并提供吸收其内容的选项。未经同意不删除也不静默弃置。七、record 与 audit错误即入口审计只减不增Record当场捕获一次观察到的 Agent 失误——这是 pitfall 唯一合法的来源。取走任务、失误、纠正及其证据检查区块是否已有覆盖该行的一行单次出现记为笔记反复出现或代价高昂的失误才立即占一行——命令类错误写成Running and verifying下的精确调用其它写成 pitfall写完后展示 diff。若机械可防则提议 hook、lint 或 CI 检查。Audit重新核验每条注意事项、路径核验每个文件、跟进每个指针并问每一行删掉它是否会改变 Agent 行为对照运行它的目标或脚本核验每条命令声明检查与其它指令文件的矛盾。失败的行被修复、移到可观察触发器之后、或变成账本条目——删除仍需 best-practices.md 的四个理由按第 5 步展示并结算后才能移除。政策或陷阱只在其所守护之物消失或用户将其退役时离开最近没失败不是理由。审计结束时区块更小或相等绝不更大。八、子文件Children何时拆分、何时留在根区块当工作持续落在一个组件、嵌套仓库或抽取的规则文件上且每个条件都成立时才为它建立同构的子文件规则是子树专属的、内容可观寥寥几条规则撑不起一个文件、拆分显著减小父区块、加载机制对每个在用 harness 都核验过检查绝不假设且用户批准拆分。即使加载已核验若规则必须在会话进入该目录前生效、或违反它会影响到子树外的工作仍把它留在根区块。否则以路径限定行留在父区块在src/importer/中……比一个没人加载的文件便宜。**仅在触发器不是路径时才用链接文件。**被选中的子文件若最终没有父区块未说过的新内容就不建文件说明原因后继续。每个子文件都要在父区块的Where things are中用一行列出其路径——发现过程绝不依赖 harness 自己找到它。九、定制面workflow 配置与源码佐证技能激活时会解析定制配置执行uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow失败时直接读 customize.toml 用默认值若{project-root}/_bmad存在再运行resolve_config.py读取中央配置。customize.toml 定义了 [workflow] 表该文件被更新时整体覆盖团队覆盖放{project-root}/_bmad/custom/bmad-project-context.toml个人覆盖放...user.toml合并规则为标量后层覆盖、数组追加activation_steps_prepend/activation_steps_append激活前后注入的步骤默认空数组persistent_facts默认故意为空——技能自身的产出AGENTS.md由 harness 加载不经过此数组用户自行追加自己的常驻事实file:为路径/glob其它按原文处理on_complete完成钩子默认空字符串external_sources每次 setup/refresh 默认提供的仓库外来源未验证前不可信支持file:{project-root}/...、file:/abs/path、skill:name、tool:nameMCP 知识库及纯文本常驻事实追加式。源码层面resolve_customization.py 实现了三层 TOML 合并与项目根解析find_project_root以_bmad/优先于.git向上寻找子模块携带.git却未必是 BMad 项目candidate_project_roots按工作目录 → 脚本安装路径 → 技能目录的信任顺序候选若所选根没有该技能定制而其它根有会向 stderr 打印提示而非静默采用。--key支持点路径抽取如workflow输出 JSON 到 stdout。resolve_config.py 则对四层中央 TOML 配置做同样风格的合并与键抽取。这些脚本同时解释了 SKILL.md 中失败时直接读 customize.toml 用默认值这一降级路径的由来resolve_customization.py在配置解析失败时返回非零退出码并打印错误。十、与官方文档、仓库实践的对齐本技能在 BMAD-METHOD 文档体系中对应 Set and Maintain Project Context操作指南与 The Theory of Project Context原理论证。后者的核心论据恰好解释了本技能为何如此克制实测表明仓库级任务中代码访问优于文档访问为 Agent 写的大多数文档反而让它们更糟——测量显示仓库指令文件存在 vs 缺失对成功率无提升且推理成本 20%但对模型训练数据中不存在的框架 API一份压缩的文档索引放入AGENTS.md能把通过率提到100%无文档 53% → 压缩索引 100%40KB 压到 8KB 性能无损Agent 常跳过需要主动选择的检索709 页 wiki 测试中 Agent 跳过索引直接猜路径因此已在上下文中的区块才能承重指针必须命名可观察触发器结论即本技能的产出哲学实现上下文约束、命令、约定、陷阱属于代码仓库必须极小、可核验、每次会话加载规划上下文理由、被拒方案、归属、领域语义属于项目/计划是另一项能力——用同一文件服务两者正是被本技能取代的两个旧技能bmad-generate-project-context、bmad-document-project失败的原因。仓库自身就是本技能的活样本AGENTS.md 展示了规则先行的仓库指令形态Conventional Commits、推送前运行uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.py等它同时印证了 best-practices 中命令正确调用值得一行的原则——正是这类明显猜测会出错未加--frozen、未在确切 checkout 上运行的命令才有资格进入指令块。十一、实战快速上手在目标仓库根目录运行bmad-project-context用平实语言说出意图——set up AGENTS.md、adopt 我们已有的 AGENTS.md、refresh the context、audit our context、agent 总在用错的测试运行器——技能会自动路由到对应意图若不在目标仓库内指明路径该路径解析到多个工作树时先询问树内不可提交时也先询问按第 2–4 步提供治理/安全/风格规则与外部文档等待技能完成扫描验证与空白访谈审阅完整区块与已结算账本逐项批准删除、迁移、自动化需逐项确认批准后内容写入AGENTS.md的!-- bmad:context --标记之间对读取其它文件如CLAUDE.md的工具技能会提议并核验一行AGENTS.md导入标记外内容一律不动技能从不 commit提交这份变更——区块随代码入库团队共享、跨机器一致、与它所约束的代码同版本演进之后保持健康循环重大变更后refresh、Agent 一出错当场record、定期audit只减不增能把规则交给 hook/lint/CI 的尽早移交。bmad-project-context的最终交付物永远是证据允许几行就写几行——保持小、保持核验、保持每行都能改变 Agent 行为。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考