BMAD-METHODbmad-project-context 技能的设计理论——如何为 AI Agent 编写最小而验证过的项目上下文【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHODBMAD-METHOD 的bmad-project-context技能建立在一个反直觉的发现之上大多数为 AI Agent 撰写的文档反而会拉低 Agent 的表现。本文解析该技能背后的完整设计理论——它以检索成本为唯一准入标准决定哪些事实值得写入仓库的AGENTS.md以负面清单明确拒绝哪些信息进入并建立了有效规则必须受保护的反向删除原则。读完本文你将掌握一套可落地的判断框架什么该写、什么不写、什么规则绝不能轻易删除以及这套理论在仓库源码中是如何被逐条实现的。反直觉的起点为 Agent 写文档大多是在帮倒忙bmad-project-context的出发点是一次令人不安的观察为 AI Agent 专门撰写的文档大部分不仅没有帮助反而降低了 Agent 的性能。这个技能的全部设计都围绕两个问题展开它收集什么、为什么收集以及更重要的——它刻意不收集什么。技能的功能定位与运行方式参见 项目上下文说明 与使用指南本文讨论的是其理论基础对应仓库中的 docs/ko-kr/explanation/project-context-theory.md。英文版本可对照阅读 docs/existing-codebases/theory-of-project-context.md。基准信息检索成本是唯一准入标准判定一条信息是否值得写下来的基准不是Agent 能不能自己推导出它而是不写下来时Agent 每次亲自找到它的代价有多大。具体衡量三个维度探索成本Agent 需要花费多少搜索动作才能找到这条事实命中概率它能否及时找对地方而不是靠猜时机问题这条事实在 Agent 犯错之前就能被看到还是犯错之后才暴露。官方文档引用了两个研究领域的结论它们指向同一答案在仓库级任务上直接访问代码优于访问文档。如果对比代码推理与文档背诵两种条件让模型直接看代码时的性能提升幅度远大于让它阅读描述系统的文档——描述系统的文档打不过它所描述的原始源码。让模型从代码反向生成需求是不可靠的。模型无法稳定地产出尚未实现的内容当前实现的行为可以从源码恢复但意图、决策依据、以及被刻意否决的替代方案无法从代码中恢复。由此得出核心推论凡是 Agent 能够以低成本从原始材料中可靠读取的内容就当场读取、不落盘。存储副本只会迅速过期并且每次会话调用都要支付 token 成本。但如果同一个事实每个会话都要费力重新寻找一次那么即便它可以从仓库推断出来也值得记录下来。这条基准在技能的规则文件 skills/bmad-project-context/references/best-practices.md 中被固化为准入测试The test判断标准不是Agent 能否推导出这条信息而是没有它时代价是什么。为什么大多数 AGENTS.md 不起作用据官方文档描述仓库级 Agent 指令文件AGENTS.md 一类产物是 2026 年研究最多的产物之一但有文件对比无文件的对照结果并不理想任务成功率没有提升推理成本却增加了 20%在真实仓库上的重复实验复现了相同结论失败原因被归因于实现能力不足而非仓库知识缺失一项大规模研究中发现随机生成的规则与专家精心挑选的规则效果相当。表面上看这似乎宣告了仓库指令文件毫无价值。但关键在于检查这些文件里写了什么绝大多数文件在重复仓库中已经存在的内容——目录结构、技术栈列表、架构摘要。换句话说这些研究实际测量的不是书面上下文这个整体而是**可以从仓库推断出来的内容被写成文字这一子集**的效果。为什么常驻文件中的短索引产生了相反的结果另一项对照实验给出了正面的反例。该实验针对模型训练数据中不存在的框架 API比较了四种配置配置通过率无文档53%仅提供可复用技能无额外指令53%同样技能 显式指令要求调用它79%在AGENTS.md中提供压缩的文档索引100%这个实验与前一个无效果的研究使用了相同的文件格式但内容完全不同它没有复述仓库本身而是写入了模型本来不知道的知识。索引把 40KB 的文档压缩到 8KB性能没有损失。实验的另一半同样重要没有任何额外指令时可复用技能在56% 的案例中从未被调用过加入调用它的显式指令后调用率超过 95%但通过率仍停留在 79%且措辞稍有变动结果就大幅波动在基于 709 页 Wiki 的实验中Agent 跳过了索引仅凭问题猜页面路径。由此得出的原则只有一条需要 Agent 自己决定是否去取的索引会被跳过而已经在上下文中的索引不会被跳过。必须遵循的信息必须放进常驻加载的文件AGENTS.md。指向其他文件的指针必须标明 Agent可以直接观察到的触发条件——路径、文件类型、具体任务都是合格条件需要 Agent 自行判断当任务复杂时或需要自我监控在你第一次编辑之前的条件都不合格。这条可观察触发器原则同样落在 skills/bmad-project-context/references/best-practices.md 的 Retrieval 一节中一个 Agent 必须主动选择去获取的索引会被跳过一个已经在上下文里的索引不会。所有承载重量的内容都留在块内。值得写入的信息先过剪枝测试该技能对块内每一行都施加剪枝测试pruning test删掉这一行Agent 的行为会改变吗如果人类手写的行没有通过这个测试也不会立即删除——先按下文反向判断一节的标准确认是否有保留依据。通过剪枝测试后以下六类信息值得写入仅凭配置文件无法知道的项目运行条件。显而易见的命令直接在package.json、Makefile、CI 配置里查看只有当多个命令都看似合理时才记录该用哪一个以及配置文件中没有的例外。典型场景根测试脚本在此工作区里什么都不做集成测试前必须先启动某个服务完整测试套件太慢、只能按单文件迭代CI 执行了测试脚本没有覆盖的检查。代码无法表达的政策。禁止修改的路径、生成文件、分支规则、安全与合规要求。这类信息只接受有权限的人告知的内容不做推断。与生态默认值不同的规则。只记录差异。没有特别说明时 Agent 会遵循通用做法因此按默认做法也不会出错的事实用不上一行。来自真实观察到的失败的危险信号。扫描仓库可以找到数百个看起来危险的事实但仅凭事实本身的性质无法区分出真正导致失误的那几个——这个信号只来自实际行为。扫描中碰到的意外发现应当变成问题去问而不是直接写成规则。跨组件规则与必需版本。Agent 只看当前正在编辑的文件无法得知、但系统多处必须共同遵守的规则以及项目实际构建所使用的工具版本。不做为了完整而完整的清单。负面约束优于正面指导。测量结果表明禁令比建议更有效因此每条禁令必须在同一行内给出被允许的替代方案。这六类准入规则与 skills/bmad-project-context/references/best-practices.md 中 Admit 一节逐条对应例如一条阻止每次会话重复同一高成本再发现的行哪怕可以推断也该保留一份 Agent 直接读原始材料更准确的副本不该保留——它会腐烂且每次会话都要付费。刻意不收集的信息负面清单是设计的核心留白什么比写入什么更能定义这套设计。官方文档列出了八类刻意不收集的信息及理由不收集的信息理由代码已经说清的内容Agent 读源码比读源码摘要更准。再写一份解释就会出现原件准确、副本过期的问题仓库结构与文件地图结构每个提交都在变存储的地图腐烂得最快Agent 几秒内就能重新摸清最新结构概览与导览文档代表性生成产物也是被测量出拉低性能的元凶块的作用应当是改变 Agent 行为而不是给读者导览生态默认值LLM 已经知道典型 Node、Python、Go 项目如何工作复述默认值等于花钱教 Agent 它本来就有的知识只因有趣而写入的内容有趣不是需要的证据。这个技能存在的意义之一就是阻止这类信息堆积需要 Agent 自我执行的风格规则这类规则应由格式化器、Linter、Hook、CI 检查承担技能改为建议引入检查检查落地后对应行删除历史与编辑过程叙述禁止写我们删掉 X 是因为……。历史由 Git 管理块内只陈述当前事实指向未来状态的内容系统将来应该是什么样属于规格说明Agent 把未来目标当成当前事实会去实现并不存在的行为结论一句话如果证据只支撑十行产物就是十行。小输出是有意设计不是能力不足。skills/bmad-project-context/references/best-practices.md 中 Size 一节进一步补充每一行在每个会话中都要付费且指令遵循能力随加载集合增大而退化超预算的应对是砍掉最弱的一行或把它移到触发器之后永远不提高预算。删除规则时反向判断有效规则必须受保护这是整套理论中最容易被误用、也最容易被忽视的部分。剪枝原则在删除规则时必须反过来应用——误用它会让文件中价值最高的内容悄无声息地消失。政策与危险信号只允许在三种情况下删除它所守护的对象已经消失该约束已经被工具自动强制执行人类明确废弃了它。最近没有发生同类失败永远不是删除理由——因为一条起作用的规则会自己消灭失败的痕迹。在这个块里那些防止已经不再发生的失误的规则恰恰最珍贵。这层保护同样覆盖所有人类撰写的指令只有当它过期或错误、已被 Hook 或检查强制、有害或与其他指令冲突、或用户逐条批准删除时才可移除可以从仓库推断或在别处找得到单独都不构成删除理由。skills/bmad-project-context/references/best-practices.md 的 Judging an existing file 一节将此细化为四个合法删除依据并特别强调内容可以在仓库某处被发现这一条单独使用从来都不是依据——这正是把优秀文件掏空的推理方式。两种范围、两种产物实现上下文与规划上下文单一产物无法同时服务编码工作与规划工作因为两者所需的信息几乎不重叠维度实现上下文Implementation规划上下文Planning内容约束、命令、规则、危险信号决策依据、被否决的替代方案、责任归属、领域语义、组织标准归属代码仓库项目或倡议验证方式可与代码对照、可直接执行验证只能追溯到来源文档过期速度每次提交都可能过期通常以月为单位过期使用方式每个会话都加载因此必须极小不常驻加载需要时集中查阅现状由bmad-project-context管理独立能力计划后续单独提供试图用一个文件同时服务两种范围正是这个技能所替代的两个旧技能犯下的错误见下文。上下文必须持续证明自己的价值旧模型把文档当作资产覆盖范围越大价值越高。bmad-project-context把上下文视为一种必须持续证明保留价值才能存在的负担Refresh重新确认每一条注意事项用git log --diff-filterDR --name-only对比记录 SHA 之后被删除或改名的条目与块内每一行对照——证据消失的行要更新或删除Audit对每行施加剪枝测试但人类手写内容同时受上述删除依据约束硬性结果任何一次运行之后块的大小小于或等于运行前出处管理某条声明的出处消失时要么按新事实修正声明要么删除它不允许仅仅因为另一份文档也提到了同样的内容就把出处悄悄换掉。第一版很容易生成真正的价值在于让它持续保持准确——这就是 Refresh 与 Audit 作为独立意图而非说明书里的备注存在的原因。与两个被替代技能的区别旧技能它的做法评价bmad-document-project扫描现有仓库生成包含概览、源码树、分领域深度说明的文档树典型的文档即资产模型但证据反对它产物大、未经验证、从生成那一刻起就在腐烂属于拉低 Agent 表现的上下文类型。它唯一合理的直觉——动手前先理解仓库——被保留为探索阶段且探索结果现在用于验证而非写成散文bmad-generate-project-context把不易察觉的项目事实装进一个小规则文件直觉是对的如今这个想法成为整体结构的中心。但它缺少文件之外的一切没有验证流程、没有维护周期、也没有区分推断与已确认事实的办法一句话总结旧技能写更多文档新技能管理更少的事实并且对它们做检查。更少的、经过验证的信息优于更多的信息。这两个旧技能以及早期的模块前缀变体如bmad-bmm-document-project、bmad-bmm-generate-project-context已列入仓库的清理清单 removals.txt安装/更新时会被自动移除。源码佐证理论如何逐条落到实现以下实现细节均可在仓库中直接核对与上述理论一一对应意图与流程skills/bmad-project-context/SKILL.md技能接受setup | adopt | refresh | record | audit五种意图全程对话式、每次写入都需用户批准。其中Adopt 的 ledger台账机制落实了反向判断原则每条既有指令都要开一个台账条目以retain保留或rewrite改写开局最终落定为retain | rewrite | relocate | automate | delete之一每条都要给出理由、证据、删除风险与审批标记删除必须命中四个合法依据之一且移到一个没人读的文件里等于删除同样需要依据Refresh对应持续证明价值读取块内 provenance 行用记录 SHA 之后的git log --diff-filterDR --name-only逐行对比删除与改名块只在新证据出现时生长Audit对应剪枝测试 四依据一条政策或危险信号只在其守护的对象消失、或被用户废弃时移除最近没有出问题不是依据且审计结束后块更小或等大Record对应只接受观察到的失败捕获当时正在发生的一个 Agent 失误一次记录为备注重复出现或代价高昂的失误才配得上一行若失误可被机械手段预防则优先提议 Hook/Lint/CI 检查而非新行。产出物的形态skills/bmad-project-context/references/template.md块被约束为六个固定小节——Orientation三四句、Policy、Where things are、Running and verifying、Conventions that differ from defaults、Known pitfalls空小节直接省略至多两个强调标记事实只能作为指令的正当化从句出现如搜索时排除vendor/它占了被跟踪文件的 60%而不是孤立的vendor/占 60%。模板附带的完整示例展示了最终产物长什么样一个夹在!-- bmad:context --与!-- /bmad:context --标记之间、包含 Verified 2026-08-08 against a1b2c3d 溯源行的紧凑块——标记之外的用户内容按字节原样保留刷新拼接splice绝不触碰标记以外的任何字节且技能永不提交变更留在工作树中由用户自行提交。配置面skills/bmad-project-context/customize.tomlpersistent_facts数组被刻意留空注释解释得很直白——这个技能自己的产物AGENTS.md 块由 harness 加载不经过这个数组团队可自行追加常驻事实external_sources数组支持登记仓库外的手册、Wiki、MCP 知识库且明确标注在对照仓库或用户确认之前视为不可信——这正是政策只接受权威来源告知原则的工程化。小结一套可迁移的判断框架抛开 BMAD-METHOD 的具体实现这篇理论文档给出的是一套通用的 Agent 上下文治理框架准入看成本写不写取决于不写时每次找它的代价而不是能不能推断出来内容看增量只写模型与配置文件都不知道的知识复述仓库与复述默认值都是负价值加载看确定性必须遵守的规则放进必然被加载的文件指向外部的指针必须挂可观察触发器因为让 Agent 自觉去取不可靠删除看依据有效规则会抹掉自己的失败证据最近没出事与别处找得到都不是删除理由规模看证据证据支撑十行就是十行超预算就砍最弱的一行绝不提高预算。bmad-project-context的价值不在于它写得多而在于它把少变成了一套有证据、有流程、可审计的工程纪律。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考