AI 技能人工智能开发工具【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址https://gitcode.com/gh_mirrors/bm/BMAD-METHOD点击查看免费下载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 的实现看该技能接受一个显式意图参数intentsetup|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 成本。因此仓库概览、目录树、技术栈清单一律不收录真正值得记录的是只读代码难以在关键时刻找到的信息。原文档明确列出六类值得收录的内容组织政策——禁止修改的路径、生成的文件、分支规则、安全与合规要求配置文件无法表达的运行条件——不照抄脚本而是记录该用哪个命令、注意什么例如pnpm test已存在于package.json但测试要跑 11 分钟或需要先启动某个服务这类事实不会出现在配置里偏离生态默认值的规则——没有特别说明时代理会按通用惯例行事所以只有偏离的部分值得一行有实证的错误教训——来自既有记录、维护者记忆、Git 历史中反复修正的失误、以及本次会话中当场发现并纠正的错误扫描中发现的看起来危险的事实不能直接写成规则必须先提问跨组件规则与必要版本——编辑单个文件时看不到、却需要系统多处共同遵守的规则以及项目实际构建所用的工具版本指向产出位置与首读文件的指针。references/best-practices.md 将同样的判断组织为Admit收录与Exclude排除两张清单排除项包括仓库概览与目录树副本比源码更快腐烂、仅因有趣而收录的内容、代理本可自律的风格规则应改由格式化器、lint、hook 或 CI 强制、陈词滥调、明显调用方式已经正确的命令清单、粘贴的代码与变更日志、指向未来的理想状态、历史叙述。该文件还强调优先写禁令而非建议并在同一行给出被允许的替代方案。五种意图Setup、Adopt、Refresh、Record、Audit原文档用一张表概括技能支持的五种意图SKILL.md 则在 On Activation 中给出了自动化检测逻辑指令文件无实质内容判定为 setup有内容但无托管块判定为 adopt它是 refresh 的迁移形态存在托管块判定为 refresh用户报告代理犯错判定为 record其余为 audit并且当用户提供的意图与检测结果矛盾时会向用户确认绝不静默服从意图执行的工作Setup用于没有需要保留的既有指令的仓库。先询问用户要提供的规则再查找并验证其余内容展示完整块之后经用户批准写入。Adopt接受用户已写好的指令。写文件前展示每条既有指令将如何被处理未经用户批准不删除任何内容。Refresh对既有块执行同一流程重新运行命令对照记录的提交 SHA 之后的删除/重命名更新已迁移的内容。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 规定了块的内部结构没有内容的章节一律省略禁止写空节Orientation——三到四句话这是什么、技术栈、规划文档与深度文档在哪里Policy——组织要求什么Where things are——入口点以及指向子文件与链接文件的指针Running and verifying——正确的运行命令与必需工具版本以及package.json、pyproject.toml、Makefile、CI 配置没有说明的内容Conventions that differ from defaults——偏离默认值的约定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 技能人工智能开发工具【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址https://gitcode.com/gh_mirrors/bm/BMAD-METHOD点击查看免费下载相关推荐BMAD-METHOD 项目上下文管理实战用 bmad-project-context 打造精准的 AGENTS.md 指令块BMAD METHOD 项目上下文管理实战用 bmad project context 打造精准的 AGENTS.md 指令块 导读 本篇文章聚焦 BMADAI 技能人工智能开发工具在既有代码库中建立并维护项目上下文BMAD-METHOD 的 bmad-project-context 实战指南在既有代码库中建立并维护项目上下文BMAD METHOD 的 bmad project context 实战指南 导读 bmad project contexAI 技能人工智能开发工具BMAD-METHOD 安装指南使用 npx bmad-method install 在项目中安装与验证 BMadBMAD METHOD 安装指南使用 npx bmad method install 在项目中安装与验证 BMad BMAD METHODBreakthroAI 技能人工智能开发工具创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考