BMAD-METHOD 仓库开发协作规范指南提交约定、质量门禁、Skill 验证与发布流程全解析【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD本文以 BMAD-METHOD 仓库根目录的 AGENTS.md 为骨架系统拆解这套开源框架Breakthrough Method for Agile AI-Driven Development为所有贡献者、Agent 与维护者制定的协作规则从 Conventional Commits 提交约定、tools/quality.py质量门禁、Skill 验证体系、提示词与测试编写原则到基于dev/main双分支的发布运行手册。读完本文你将能在本地完整复现 CI 检查、通过全部 Skill 校验规则并理解一个以「Skill Agent 工作流」为核心的开源仓库如何通过确定性工具约束 AI 时代的多角色协作。AGENTS.md 在仓库中的定位AGENTS.md是面向代码仓库贡献者的顶层协作入口文件全文仅 31 行却浓缩了 BMAD-METHOD 的工程治理核心它没有罗列仓库功能而是直接给出四组「硬约束」——提交规则、质量门禁、提示词编写原则、测试原则外加一条发布流程指引。它同时是文档体系的锚点AGENTS.md 引用了 tools/skill-validator.md、tools/validate_skills.py、docs/_STYLE_GUIDE.md 三份规范文件分别覆盖 Skill 校验、确定性检查与文档风格三者共同构成仓库的「规则三角」。提交与质量门禁推送前必须复现 CI 检查Conventional Commits 提交约定AGENTS.md 的第一条规则是所有提交必须使用 Conventional Commits 规范即形如fix: ...、feat: ...、chore(release): v6.13.0的提交信息。这条约定在发布流程中会被严格执行——发布脚本stamp_release.py跑完后要求以chore(release): v版本与chore: bump placeholder version to 版本提交说明提交信息格式不只是风格要求还被发布流水线依赖。推送前必跑的完整质量门禁AGENTS.md 规定推送前必须在将要推送的确切 checkout 上运行uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.py这条命令由三部分组成uv sync --frozen按 pyproject.toml 与uv.lock锁定版本安装 Python 依赖--frozen确保不修改锁文件(cd docs-site npm ci)按 docs-site/package-lock.json 精确安装文档站点依赖npm ci会删除并重装node_modules保证与 CI 环境一致uv run --frozen tools/quality.py执行六步检查流水线。quality.py 的源码明确定义了流水线顺序STEPS列表步骤执行位置命令作用1仓库根uv run --frozen pre-commit run --all-files --show-diff-on-failure全仓 Python 侧 lint、格式、文档、校验与测试2docs-sitenpm run lintESLint--max-warnings03docs-sitenpm run format:checkPrettier 格式检查4docs-sitenpm run build构建文档站点构建前内部执行链接校验5docs-sitenpm run validate-sidebar校验侧边栏顺序6docs-sitenpm test站点测试套件任何一步非零退出脚本立即在stderr打印quality: failed at: 步骤并以状态码 1 终止quality.py。文档注释明确说明该脚本与.github/workflows/quality.yaml对齐即本地跑一遍等于完整复现 CI。与 CI 工作流的对应关系.github/workflows/quality.yaml 将同一套检查拆成两个 jobpython jobactions/checkoutv4astral-sh/setup-uvv6uv sync --frozen然后运行uv run --frozen pre-commit run --all-files --show-diff-on-failure即质量门禁第 1 步docs-site jobnode-version-file: docs-site/.nvmrc指定 Node 版本npm ci后依次执行npm run lint、format:check、build、validate-sidebar、npm test即第 26 步。CI 在pushmain/dev 分支与pull_request上触发并支持workflow_dispatch手动触发。本地提交钩子pre-commit.pre-commit-config.yaml 定义了提交时的本地钩子集合AGENTS.md 要求每个 clone 执行一次uv run pre-commit install。钩子分为两组第三方钩子ruff-check带--fix、ruff-format、rumdlMarkdown lint、yamllint、yamlfix、check-json、pretty-format-json均固定版本号并通过uv run pre-commit autoupdate升级三个 local 钩子language: systemalways_run: truevalidate-file-refsuv run tools/validate_file_refs.py --strict校验文档中的文件引用有效性validate-skillsuv run tools/validate_skills.py --strict确定性 Skill 校验见下节pytestuv run --frozen pytest运行全仓 Python 测试。注意exclude: ^(docs-site/|.*/tests/fixtures/)——文档站点与测试夹具目录不参与 pre-commit 检查前者由独立的 npm 脚本负责。Skill 验证体系20 条规则的「确定性 推断」双通道BMAD-METHOD 的核心资产是skills/目录下 30 余个 Agent Skillbmad、bmad-brainstorming、bmad-prd、bmad-spec等因此 AGENTS.md 用两条规则把它们纳入治理规则文件在 tools/skill-validator.md确定性检查通过 tools/validate_skills.py 执行。两遍式验证流程skill-validator.md 规定 Skill 验证分两遍第一遍确定性运行uv run --python 3.11 tools/validate_skills.py --json path/to/skill-dir程序化检查 10 条规则SKILL-01SKILL-07、PATH-02、SEQ-02、TPL-01第二遍推断式人工/LLM 阅读 skill 目录内所有文件对剩余 10 条需要判断的规则PATH-01、PATH-03、PATH-04、PATH-05、STEP-04、STEP-05、SEQ-01、REF-01、REF-02、REF-03逐条审查。两遍均无 finding 才判定通过确定性检查中零 finding 的规则可跳过推断复查。输出采用规定的 Report Template摘要表按 CRITICAL/HIGH/MEDIUM/LOW 统计逐条列出 File/Line/Detail/Fix。确定性校验器的用法与实现validate_skills.py 支持三种调用方式uv run --python 3.11 tools/validate_skills.py # 校验 skills/ 下全部 skill人类可读输出 uv run --python 3.11 tools/validate_skills.py path/to/skill-dir # 校验单个 skill 目录 uv run --python 3.11 tools/validate_skills.py --strict # 存在 HIGH 级别 finding 时退出码 1 uv run --python 3.11 tools/validate_skills.py --json # JSON 输出便于机器消费从实现看校验器通过discover_skill_dirs递归扫描含SKILL.md的目录只检查.md/.yaml/.yml扩展名文件并在规则检测前用strip_code_blocks剥离代码块避免误报。几条代表性规则的实际实现SKILL-04name 格式正则^(?:bmad|bmad-[a-z0-9](?:-[a-z0-9])*)$即根 skill 必须叫bmad子 skill 必须以bmad-开头且仅含小写字母、数字、单连字符validate_skills.pySKILL-05name 与目录名一致frontmatter 的name必须与SKILL.md所在目录名完全一致因为目录名是安装器、manifest 与跨 skill 引用的规范标识SKILL-06description 质量description 必须同时说明「做什么」与「何时用」超过 1024 字符或缺少Use when/Use if触发短语即告警deprecated开头的 skill 豁免SEQ-02禁止时间估算通过 4 个正则takes X min、~N min、estimated time、ETA扫描因为 AI 执行速度差异过大时间估算无意义TPL-01模板禁含渲染期表达式文件名含template的 Markdown 不得包含{{ config.* }}/{{ workflow.* }}否则会把渲染机器的本地值烧进每个生成产物validate_skills.py。--strict模式下只要存在 CRITICAL 或 HIGH finding 就以退出码 1 失败仅有 MEDIUM/LOW 则通过validate_skills.py。在 CI 的 GitHub Actions 环境中它还会输出::warning file...,line...::注解并把摘要写入GITHUB_STEP_SUMMARY。推断式规则的关键约束skill-validator.md中需要人工判断的规则里最有代表性的是路径与引用规范PATH-01skill 内部引用必须相对引用文件自身目录./指同级/子级、../指父级严禁出现steps/steps/...这类二次嵌套错误PATH-03/PATH-05跨 skill 边界的引用禁止写死路径必须使用{project-root}/...或配置键派生路径如{planning_artifacts}/...需要调用别的 skill 时用叙述语言「Invoke theskill-nameskill」而非文件级动词REF-01所有 token 必须能解析到定义源——{workflow.key}必须存在于本 skill 的customize.toml的[workflow]表{{ config.a.b.c }}等渲染期表达式只允许出现在调用render_skill.py的渲染型 skill 中STEP-04/STEP-05/SEQ-01展示菜单的步骤必须显式 HALT 等待用户、不得提前加载后续步骤文件、不得出现「跳过步骤」类指令条件路由除外。提示词编写原则每次运行都支付的长度成本AGENTS.md 的「Writing prompts」段落是该仓库方法论的精髓值得完整继承Skills, workflows, tasks, and agent definitions are prompt text that an agent reads in full on every run. Length and ambiguity are paid on every run; a corner case is paid only when it occurs.翻译成工程决策就是提示词的长度与歧义是「每次运行都付费」的经常性成本而边界情况只在发生时付费一次。因此规则是——不要为罕见的边界场景添加指令模型通常会从上下文自行处理万一处理不好审查的人类可以在当时纠正。这条原则与 Skill 校验器中的 SEQ-02禁止时间估算一脉相承既然 AI 执行速度不可预测就不写「约 N 分钟」既然提示词全量重读就不为低概率场景堆砌指令。它同样解释了 docs/_STYLE_GUIDE.md 中「Plain English、gist 先行、删除不改变读者决策的告诫」等文风要求——文档与提示词共享同一条成本逻辑。测试原则只为确定性代码写自动化测试AGENTS.md 的 Testing 段落只有一句话却划出了清晰的边界自动化测试只断言确定性代码产生的结果不为 LLM 输出或静态源文本写测试。仓库实践印证了这条原则确定性工具脚本均有配套测试如 tools/tests/test_validate_skills.py、tools/tests/test_stamp_release.pyskill 内置脚本同样遵循如skills/bmad/scripts/tests/、skills/bmad-brainstorming/scripts/tests/test_brain.py、skills/bmad-retrospective/scripts/tests/等——它们测试的是pick_methods.py、brain.py、sprint_status.py这类纯逻辑而不是 prompt 文本本身文档站点测试docs-site/test/验证的是 rehype 插件、站点 URL、重定向与 locale 覆盖这类可断言的工程行为。发布流程dev 开发、main 发布、无 PR 回合并AGENTS.md 的 Releases 段落指向 tools/release.md其核心模型是dev接收开发 PRmain是仅发布的默认分支通过把mainfast-forward 到dev上的 stamped 提交来发布然后打 tag。没有发布分支、发布 PR、merge commit 或 back-mergemain始终是dev的祖先。五步发布运行手册tools/release.md 给出了完整脚本Prepare在干净 checkout 上确认HEAD origin/dev且origin/main是dev的祖先显式选择发布版本如bmad_release_version6.13.0与下一个占位版本6.13.1-nextStamp and push dev运行uv run --python 3.11 tools/stamp_release.py $bmad_release_version审查 diff只应有 29 个 manifest 的版本变化提交chore(release): v版本跑质量门禁后推送devFast-forward main and tag验证HEAD origin/dev bmad_release_commit后git push origin dev:main对同一提交打带注释 tagv版本并推送Stamp the next placeholder在dev上再次运行 stamper 写入-next占位版本并提交推送开发即可恢复无需任何合并回Rebuild and verify在插件仓库运行发布脚本通过npx skills add bmad-code-org/BMAD-METHOD验证并注意raw.githubusercontent.com有约五分钟缓存。stamp_release.py 的版本校验细节stamp_release.py 在写入前会做完整的 manifest 模式校验理解它有助于避免发布事故严格 schema每个skills/*/module-manifest.toml必须恰好包含module、version、update_source、knowledge四个键module只能是method或toolboxupdate_source固定为github:bmad-code-org/BMAD-METHOD/skillsstamp_release.py版本语法接受标准 SemVer可选 prerelease但拒绝包含-dev的版本——因为skills/bmad/scripts/setup.py无法对-dev版本排序已安装副本永远不会判定自己过期也拒绝带 build metadata...的版本——因为排序时会忽略 build 部分1.2.0x与1.2.0比较相等发布对已安装副本不可见stamp_release.py写入策略分两阶段执行——先计算全部新内容任一文件失败则整体不写再写入并从磁盘重读验证version ...行按文本重写保证同一 module 的所有 manifest 字节级一致setup.py的模块发现依赖原始字节比较。文档规范贡献文档必须遵循的样式指引AGENTS.md 同时把文档贡献者指向 docs/_STYLE_GUIDE.md。该指南基于 Google Developer Documentation Style Guide 与 Diataxis 结构包含几条硬规则不写水平分隔线、不用####标题、不设「Related/Next:」小节、表格单元格不超过 12 句、每篇文档 812 个##、Starlight admonition 语法:::tip/:::note/:::caution/:::danger并按 Tutorial / How-To / Explanation / Reference 四类给出标准结构与提交前校验命令npm run fix-links -- --write、npm run validate-links、npm run build。文档站点脚本清单见 docs-site/package.json。速查表与本地操作清单推送前必做与 CI 完全一致uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.pySkill 校验快捷命令uv run --python 3.11 tools/validate_skills.py --strict # 全量HIGH 即失败 uv run --python 3.11 tools/validate_skills.py --json skills/bmad # 单个 skillJSON 输出核心文件索引文件作用AGENTS.md仓库协作规则总入口tools/quality.py六步质量门禁流水线.github/workflows/quality.yaml与质量门禁对齐的 CI 工作流.pre-commit-config.yaml提交钩子ruff/rumdl/yamllint 三个 local 校验tools/skill-validator.md20 条 Skill 校验规则10 确定性 10 推断tools/validate_skills.py确定性 Skill 校验器tools/release.md发布运行手册tools/stamp_release.py版本 stamp 与 manifest schema 校验docs/_STYLE_GUIDE.md文档风格指南BMAD-METHOD 的治理思路可以概括为一句话凡是能用确定性工具约束的格式、版本、路径、引用、schema全部下沉为可执行脚本并在 CI 强制执行凡是需要判断力的提示词质量、Skill 语义、文档可读性则交给明确的规则文本与人工复查。对于任何以 AI 工作流为核心资产的开源项目这套「规则文本 确定性校验 双分支发布」的组合都是可直接借鉴的工程范式。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BMAD-METHOD 仓库开发协作规范指南：提交约定、质量门禁、Skill 验证与发布流程全解析
BMAD-METHOD 仓库开发协作规范指南提交约定、质量门禁、Skill 验证与发布流程全解析【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD本文以 BMAD-METHOD 仓库根目录的 AGENTS.md 为骨架系统拆解这套开源框架Breakthrough Method for Agile AI-Driven Development为所有贡献者、Agent 与维护者制定的协作规则从 Conventional Commits 提交约定、tools/quality.py质量门禁、Skill 验证体系、提示词与测试编写原则到基于dev/main双分支的发布运行手册。读完本文你将能在本地完整复现 CI 检查、通过全部 Skill 校验规则并理解一个以「Skill Agent 工作流」为核心的开源仓库如何通过确定性工具约束 AI 时代的多角色协作。AGENTS.md 在仓库中的定位AGENTS.md是面向代码仓库贡献者的顶层协作入口文件全文仅 31 行却浓缩了 BMAD-METHOD 的工程治理核心它没有罗列仓库功能而是直接给出四组「硬约束」——提交规则、质量门禁、提示词编写原则、测试原则外加一条发布流程指引。它同时是文档体系的锚点AGENTS.md 引用了 tools/skill-validator.md、tools/validate_skills.py、docs/_STYLE_GUIDE.md 三份规范文件分别覆盖 Skill 校验、确定性检查与文档风格三者共同构成仓库的「规则三角」。提交与质量门禁推送前必须复现 CI 检查Conventional Commits 提交约定AGENTS.md 的第一条规则是所有提交必须使用 Conventional Commits 规范即形如fix: ...、feat: ...、chore(release): v6.13.0的提交信息。这条约定在发布流程中会被严格执行——发布脚本stamp_release.py跑完后要求以chore(release): v版本与chore: bump placeholder version to 版本提交说明提交信息格式不只是风格要求还被发布流水线依赖。推送前必跑的完整质量门禁AGENTS.md 规定推送前必须在将要推送的确切 checkout 上运行uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.py这条命令由三部分组成uv sync --frozen按 pyproject.toml 与uv.lock锁定版本安装 Python 依赖--frozen确保不修改锁文件(cd docs-site npm ci)按 docs-site/package-lock.json 精确安装文档站点依赖npm ci会删除并重装node_modules保证与 CI 环境一致uv run --frozen tools/quality.py执行六步检查流水线。quality.py 的源码明确定义了流水线顺序STEPS列表步骤执行位置命令作用1仓库根uv run --frozen pre-commit run --all-files --show-diff-on-failure全仓 Python 侧 lint、格式、文档、校验与测试2docs-sitenpm run lintESLint--max-warnings03docs-sitenpm run format:checkPrettier 格式检查4docs-sitenpm run build构建文档站点构建前内部执行链接校验5docs-sitenpm run validate-sidebar校验侧边栏顺序6docs-sitenpm test站点测试套件任何一步非零退出脚本立即在stderr打印quality: failed at: 步骤并以状态码 1 终止quality.py。文档注释明确说明该脚本与.github/workflows/quality.yaml对齐即本地跑一遍等于完整复现 CI。与 CI 工作流的对应关系.github/workflows/quality.yaml 将同一套检查拆成两个 jobpython jobactions/checkoutv4astral-sh/setup-uvv6uv sync --frozen然后运行uv run --frozen pre-commit run --all-files --show-diff-on-failure即质量门禁第 1 步docs-site jobnode-version-file: docs-site/.nvmrc指定 Node 版本npm ci后依次执行npm run lint、format:check、build、validate-sidebar、npm test即第 26 步。CI 在pushmain/dev 分支与pull_request上触发并支持workflow_dispatch手动触发。本地提交钩子pre-commit.pre-commit-config.yaml 定义了提交时的本地钩子集合AGENTS.md 要求每个 clone 执行一次uv run pre-commit install。钩子分为两组第三方钩子ruff-check带--fix、ruff-format、rumdlMarkdown lint、yamllint、yamlfix、check-json、pretty-format-json均固定版本号并通过uv run pre-commit autoupdate升级三个 local 钩子language: systemalways_run: truevalidate-file-refsuv run tools/validate_file_refs.py --strict校验文档中的文件引用有效性validate-skillsuv run tools/validate_skills.py --strict确定性 Skill 校验见下节pytestuv run --frozen pytest运行全仓 Python 测试。注意exclude: ^(docs-site/|.*/tests/fixtures/)——文档站点与测试夹具目录不参与 pre-commit 检查前者由独立的 npm 脚本负责。Skill 验证体系20 条规则的「确定性 推断」双通道BMAD-METHOD 的核心资产是skills/目录下 30 余个 Agent Skillbmad、bmad-brainstorming、bmad-prd、bmad-spec等因此 AGENTS.md 用两条规则把它们纳入治理规则文件在 tools/skill-validator.md确定性检查通过 tools/validate_skills.py 执行。两遍式验证流程skill-validator.md 规定 Skill 验证分两遍第一遍确定性运行uv run --python 3.11 tools/validate_skills.py --json path/to/skill-dir程序化检查 10 条规则SKILL-01SKILL-07、PATH-02、SEQ-02、TPL-01第二遍推断式人工/LLM 阅读 skill 目录内所有文件对剩余 10 条需要判断的规则PATH-01、PATH-03、PATH-04、PATH-05、STEP-04、STEP-05、SEQ-01、REF-01、REF-02、REF-03逐条审查。两遍均无 finding 才判定通过确定性检查中零 finding 的规则可跳过推断复查。输出采用规定的 Report Template摘要表按 CRITICAL/HIGH/MEDIUM/LOW 统计逐条列出 File/Line/Detail/Fix。确定性校验器的用法与实现validate_skills.py 支持三种调用方式uv run --python 3.11 tools/validate_skills.py # 校验 skills/ 下全部 skill人类可读输出 uv run --python 3.11 tools/validate_skills.py path/to/skill-dir # 校验单个 skill 目录 uv run --python 3.11 tools/validate_skills.py --strict # 存在 HIGH 级别 finding 时退出码 1 uv run --python 3.11 tools/validate_skills.py --json # JSON 输出便于机器消费从实现看校验器通过discover_skill_dirs递归扫描含SKILL.md的目录只检查.md/.yaml/.yml扩展名文件并在规则检测前用strip_code_blocks剥离代码块避免误报。几条代表性规则的实际实现SKILL-04name 格式正则^(?:bmad|bmad-[a-z0-9](?:-[a-z0-9])*)$即根 skill 必须叫bmad子 skill 必须以bmad-开头且仅含小写字母、数字、单连字符validate_skills.pySKILL-05name 与目录名一致frontmatter 的name必须与SKILL.md所在目录名完全一致因为目录名是安装器、manifest 与跨 skill 引用的规范标识SKILL-06description 质量description 必须同时说明「做什么」与「何时用」超过 1024 字符或缺少Use when/Use if触发短语即告警deprecated开头的 skill 豁免SEQ-02禁止时间估算通过 4 个正则takes X min、~N min、estimated time、ETA扫描因为 AI 执行速度差异过大时间估算无意义TPL-01模板禁含渲染期表达式文件名含template的 Markdown 不得包含{{ config.* }}/{{ workflow.* }}否则会把渲染机器的本地值烧进每个生成产物validate_skills.py。--strict模式下只要存在 CRITICAL 或 HIGH finding 就以退出码 1 失败仅有 MEDIUM/LOW 则通过validate_skills.py。在 CI 的 GitHub Actions 环境中它还会输出::warning file...,line...::注解并把摘要写入GITHUB_STEP_SUMMARY。推断式规则的关键约束skill-validator.md中需要人工判断的规则里最有代表性的是路径与引用规范PATH-01skill 内部引用必须相对引用文件自身目录./指同级/子级、../指父级严禁出现steps/steps/...这类二次嵌套错误PATH-03/PATH-05跨 skill 边界的引用禁止写死路径必须使用{project-root}/...或配置键派生路径如{planning_artifacts}/...需要调用别的 skill 时用叙述语言「Invoke theskill-nameskill」而非文件级动词REF-01所有 token 必须能解析到定义源——{workflow.key}必须存在于本 skill 的customize.toml的[workflow]表{{ config.a.b.c }}等渲染期表达式只允许出现在调用render_skill.py的渲染型 skill 中STEP-04/STEP-05/SEQ-01展示菜单的步骤必须显式 HALT 等待用户、不得提前加载后续步骤文件、不得出现「跳过步骤」类指令条件路由除外。提示词编写原则每次运行都支付的长度成本AGENTS.md 的「Writing prompts」段落是该仓库方法论的精髓值得完整继承Skills, workflows, tasks, and agent definitions are prompt text that an agent reads in full on every run. Length and ambiguity are paid on every run; a corner case is paid only when it occurs.翻译成工程决策就是提示词的长度与歧义是「每次运行都付费」的经常性成本而边界情况只在发生时付费一次。因此规则是——不要为罕见的边界场景添加指令模型通常会从上下文自行处理万一处理不好审查的人类可以在当时纠正。这条原则与 Skill 校验器中的 SEQ-02禁止时间估算一脉相承既然 AI 执行速度不可预测就不写「约 N 分钟」既然提示词全量重读就不为低概率场景堆砌指令。它同样解释了 docs/_STYLE_GUIDE.md 中「Plain English、gist 先行、删除不改变读者决策的告诫」等文风要求——文档与提示词共享同一条成本逻辑。测试原则只为确定性代码写自动化测试AGENTS.md 的 Testing 段落只有一句话却划出了清晰的边界自动化测试只断言确定性代码产生的结果不为 LLM 输出或静态源文本写测试。仓库实践印证了这条原则确定性工具脚本均有配套测试如 tools/tests/test_validate_skills.py、tools/tests/test_stamp_release.pyskill 内置脚本同样遵循如skills/bmad/scripts/tests/、skills/bmad-brainstorming/scripts/tests/test_brain.py、skills/bmad-retrospective/scripts/tests/等——它们测试的是pick_methods.py、brain.py、sprint_status.py这类纯逻辑而不是 prompt 文本本身文档站点测试docs-site/test/验证的是 rehype 插件、站点 URL、重定向与 locale 覆盖这类可断言的工程行为。发布流程dev 开发、main 发布、无 PR 回合并AGENTS.md 的 Releases 段落指向 tools/release.md其核心模型是dev接收开发 PRmain是仅发布的默认分支通过把mainfast-forward 到dev上的 stamped 提交来发布然后打 tag。没有发布分支、发布 PR、merge commit 或 back-mergemain始终是dev的祖先。五步发布运行手册tools/release.md 给出了完整脚本Prepare在干净 checkout 上确认HEAD origin/dev且origin/main是dev的祖先显式选择发布版本如bmad_release_version6.13.0与下一个占位版本6.13.1-nextStamp and push dev运行uv run --python 3.11 tools/stamp_release.py $bmad_release_version审查 diff只应有 29 个 manifest 的版本变化提交chore(release): v版本跑质量门禁后推送devFast-forward main and tag验证HEAD origin/dev bmad_release_commit后git push origin dev:main对同一提交打带注释 tagv版本并推送Stamp the next placeholder在dev上再次运行 stamper 写入-next占位版本并提交推送开发即可恢复无需任何合并回Rebuild and verify在插件仓库运行发布脚本通过npx skills add bmad-code-org/BMAD-METHOD验证并注意raw.githubusercontent.com有约五分钟缓存。stamp_release.py 的版本校验细节stamp_release.py 在写入前会做完整的 manifest 模式校验理解它有助于避免发布事故严格 schema每个skills/*/module-manifest.toml必须恰好包含module、version、update_source、knowledge四个键module只能是method或toolboxupdate_source固定为github:bmad-code-org/BMAD-METHOD/skillsstamp_release.py版本语法接受标准 SemVer可选 prerelease但拒绝包含-dev的版本——因为skills/bmad/scripts/setup.py无法对-dev版本排序已安装副本永远不会判定自己过期也拒绝带 build metadata...的版本——因为排序时会忽略 build 部分1.2.0x与1.2.0比较相等发布对已安装副本不可见stamp_release.py写入策略分两阶段执行——先计算全部新内容任一文件失败则整体不写再写入并从磁盘重读验证version ...行按文本重写保证同一 module 的所有 manifest 字节级一致setup.py的模块发现依赖原始字节比较。文档规范贡献文档必须遵循的样式指引AGENTS.md 同时把文档贡献者指向 docs/_STYLE_GUIDE.md。该指南基于 Google Developer Documentation Style Guide 与 Diataxis 结构包含几条硬规则不写水平分隔线、不用####标题、不设「Related/Next:」小节、表格单元格不超过 12 句、每篇文档 812 个##、Starlight admonition 语法:::tip/:::note/:::caution/:::danger并按 Tutorial / How-To / Explanation / Reference 四类给出标准结构与提交前校验命令npm run fix-links -- --write、npm run validate-links、npm run build。文档站点脚本清单见 docs-site/package.json。速查表与本地操作清单推送前必做与 CI 完全一致uv sync --frozen (cd docs-site npm ci) uv run --frozen tools/quality.pySkill 校验快捷命令uv run --python 3.11 tools/validate_skills.py --strict # 全量HIGH 即失败 uv run --python 3.11 tools/validate_skills.py --json skills/bmad # 单个 skillJSON 输出核心文件索引文件作用AGENTS.md仓库协作规则总入口tools/quality.py六步质量门禁流水线.github/workflows/quality.yaml与质量门禁对齐的 CI 工作流.pre-commit-config.yaml提交钩子ruff/rumdl/yamllint 三个 local 校验tools/skill-validator.md20 条 Skill 校验规则10 确定性 10 推断tools/validate_skills.py确定性 Skill 校验器tools/release.md发布运行手册tools/stamp_release.py版本 stamp 与 manifest schema 校验docs/_STYLE_GUIDE.md文档风格指南BMAD-METHOD 的治理思路可以概括为一句话凡是能用确定性工具约束的格式、版本、路径、引用、schema全部下沉为可执行脚本并在 CI 强制执行凡是需要判断力的提示词质量、Skill 语义、文档可读性则交给明确的规则文本与人工复查。对于任何以 AI 工作流为核心资产的开源项目这套「规则文本 确定性校验 双分支发布」的组合都是可直接借鉴的工程范式。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考