BMAD-METHOD 文档写作规范指南基于 Google 风格与 Diataxis 结构的项目文档体系【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD本文讲解 BMAD-METHOD 仓库Breakthrough Method for Agile AI Driven Development文档站点所采用的统一写作规范——它以 Google Developer Documentation Style Guide 为文风基准、以 Diataxis 方法论组织内容结构再叠加项目自身的约束规则。读完本文你将掌握如何按规范撰写 Tutorial、How-to、Explanation、Reference、Glossary 与 FAQ 六类文档理解:::note等提示块admonition的 Starlight 语法并能使用仓库内置的链接修复与校验脚本在提交前自动把关。核心规范见 docs/zh-cn/_STYLE_GUIDE.md英文原版见 docs/_STYLE_GUIDE.md。规范体系的三层结构BMAD-METHOD 的文档规范由三层组成层层递进文风基准遵循 Google Developer Documentation Style Guide——用具体、熟悉的词汇和短句让主要观点易于查找和行动只在读者使用 BMAD 确实需要时才引入专业术语且首次出现时给出定义先给结论再给限定条件与细节删掉重复、拖延进入主题的开场、夸大其词与不影响读者决策的免责声明。结构框架使用 Diataxis 方法论将文档分为 Tutorial教程、How-to操作指南、Explanation解释、Reference参考四大类型每类有固定的章节骨架。项目级约束在以上两者之上中文版规范 docs/zh-cn/_STYLE_GUIDE.md 用一张规则表明确可以做与不可以做保证全站格式一致。这套规范并非纸面要求而是由 docs-site/ 下的 Astro Starlight 站点落地执行astro.config.mjs中的 Starlight 配置、侧边栏定义与 rehype 插件链共同决定了文档如何被渲染、导航如何生成、多语言如何组织。项目特定规则一览中文版规范开篇即给出项目级约束表这是全站最核心的硬性规定规则规范禁用水平分割线---会打断阅读流禁用####标题用加粗短句或 admonition 替代避免 Related/Next 章节交给侧边栏导航避免深层嵌套列表拆成新段落或新小节非代码内容不要放代码块对话/提示用 admonition不用整段粗体做提醒统一用 admonition每节 1-2 个 admonition教程大节可放宽到 3-4 个表格单元格/列表项控制在 1-2 句标题预算每篇约 8-12 个##每节 2-3 个###逐条解读其中的设计意图标题层级预算##H2每篇限制在 8-12 个、每节内###H3限制在 2-3 个是因为 Starlight 的目录组件tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }见 docs-site/astro.config.mjs只把 H2/H3 纳入右侧 On this page 导航。层级越多导航越臃肿禁用####H4则避免导航失控。admonition 取代粗体与代码块对话、提示、风险提醒这类非代码内容放进提示块而不是塞进代码块或整段加粗是为了保证视觉语义统一——提示块有明确的类型色标tip/note/caution/danger。侧边栏接管导航由于 docs-site/astro.config.mjs 中配置了完整的 sidebar 结构Start、Build、Plan Larger Work、Existing Codebases、Customize and Extend、Reference、BMad EcosystemRelated/Next 这类文内跳转章节就变得多余统一交给侧边栏。提示块Admonition的 Starlight 语法规范定义的四类提示块使用 Starlight 的:::语法完整写法如下:::tip[Title] Shortcuts, best practices ::: :::note[Title] Context, definitions, examples, prerequisites ::: :::caution[Title] Caveats, potential issues ::: :::danger[Title] Critical warnings only — data loss, security issues :::四类提示块的职责边界非常明确tip放快捷键与最佳实践note放上下文、定义、示例与前置条件caution放注意事项与潜在问题danger只用于数据丢失、安全类严重警告不得滥用。标准用途提示块适用场景:::note[Prerequisites]开始前依赖与前置条件:::tip[Quick Path]文档顶部 TL;DR:::caution[Important]关键风险提醒:::note[Example]命令/响应示例说明这套用法在仓库文档中随处可见。以 docs/zh-cn/tutorials/getting-started.md 为例开篇用:::note[前置条件]列出 Node.js 20.12、Git、AI 驱动的 IDE 等依赖紧随其后用:::tip[最简单的路径]给出 安装 → 询问 → 构建 的 TL;DR文中还用:::caution[新对话]提醒始终为每个工作流开始一个新的对话并在结尾用:::tip[记住这些]收束关键要点——与规范中Quick Path 放文档顶部、Key Takeaways 放末尾的要求完全吻合。标准表格模板规范为最常见的两类信息提供了可直接复用的表格模板阶段表用于描述 BMad 的四阶段流程与技能表用于列出工作流、所属智能体与用途。| Phase | Name | What Happens | | ----- | -------- | -------------------------------------------- | | 1 | Analysis | Brainstorm, research *(optional)* | | 2 | Planning | Requirements — PRD or spec *(required)* || Skill | Agent | Purpose | | -------------------- | ------- | ------------------------------------ | | bmad-brainstorming | Analyst | Brainstorm a new project | | bmad-prd | PM | Create Product Requirements Document |从 docs/zh-cn/tutorials/getting-started.md 的实际使用可以看到这两个模板的演化阶段表被扩展为分析、规划、解决方案设计、实现四行并标注可选/按需技能表则扩展为工作流 | 命令 | 智能体 | 目的四列把bmad-help、bmad-prd、bmad-build等 8 个核心工作流一次列全作为文末的快速参考。文件结构块Folder Structure用于 What Youve Accomplished你已完成的工作类章节展示项目落地后应拥有的目录骨架your-project/ ├── _bmad/ # BMad configuration ├── _bmad-output/ │ ├── planning-artifacts/ │ │ └── PRD.md # Your requirements document │ ├── implementation-artifacts/ │ └── project-context.md # Implementation rules (optional) └── ...中文版规范在此基础上补充了注释说明_bmad/存放 BMad 配置_bmad-output/下的planning-artifacts/存放 PRD、architecture、epics 等规划产物implementation-artifacts/存放实现产物project-context.md记录实现规则可选。这一结构在 docs/zh-cn/tutorials/getting-started.md 的你已完成的工作一节中被完整实例化目录树展开为planning-artifacts/下的PRD.md、architecture.md、epics/以及implementation-artifacts/下的sprint-status.yaml。教程Tutorial结构教程是引导读者从零到一完成任务的内容类型规范规定其固定骨架1. Title Hook1-2 句结果导向开场 2. Version/Module Notice可选信息或警告提示块 3. What Youll Learn结果清单 4. Prerequisites前置条件提示块 5. Quick PathTL;DR 提示块 6. Understanding [Topic]步骤前的背景说明可配表格 7. Installation可选 8. Step 1: [First Major Task] 9. Step 2: [Second Major Task] 10. Step 3: [Third Major Task] 11. What Youve Accomplished总结 文件结构 12. Quick Referenceskills 表 13. Common QuestionsFAQ 14. Getting Help社区入口 15. Key Takeaways末尾 tip 提示块教程检查清单Hook 用 1-2 句明确结果包含 What Youll Learn前置条件放在 admonition顶部有 Quick Path TL;DR关键信息用 phases/skills/agents 表格包含 What Youve Accomplished包含 Quick Reference 表包含 Common Questions包含 Getting Help末尾包含 Key Takeaways 提示块中文快速入门教程 正是这一骨架的完整范本它从你将学到与前置条件提示块开始依次经过认识 BMad-HelpUnderstanding 部分、安装Installation、步骤 1选择规划深度与步骤 2构建你的项目编号步骤、你已完成的工作含文件结构块、快速参考技能表、常见问题FAQ、获取帮助Getting Help直到关键要点末尾 tip——15 个环节逐一命中可作为撰写新教程时的对照样本。How-to 结构操作指南解决具体怎么做的问题骨架如下1. Title Hook单句形如 Use the X workflow to... 2. When to Use This3-5 条场景 3. When to Skip This可选 4. Prerequisitesnote 提示块 5. Steps编号 ### 动词开头 6. What You Get产出物说明 7. Example可选 8. Tips可选 9. Next Steps可选How-to 检查清单Hook 以 Use theXworkflow to... 开头When to Use This 有 3-5 条场景明确前置条件步骤为编号###子标题且动词开头What You Get 明确产出物How-to 与 Tutorial 的核心区别在于Tutorial 面向第一次学的读者、按顺序走完整个流程How-to 面向要解决特定问题的读者、可直接定位到所需步骤。规范要求 Hook 必须采用 Use theXworkflow to... 的单句句式让读者一眼判断本文是否适用步骤一律用###子标题且以动词开头如调用 PM 智能体运行bmad-prd工作流便于目录扫描与快速跳转。Explanation 结构解释类文档回答它是什么、为什么这样设计是理解 BMAD 各阶段与模块的入口。类型类型示例Index/Landingcore-concepts/index.mdConceptwhat-are-agents.mdFeaturebuild.mdPhilosophywhy-solutioning-matters.mdFAQestablished-projects-faq.md通用模板1. Title Hook1-2 句 2. Overview/Definition是什么为什么重要 3. Key Concepts### 小节 4. Comparison Table可选 5. When to Use / When Not to Use可选 6. Diagram可选单文档最多 1 个 mermaid 7. Next Steps可选针对不同子类型规范还给出了更细的骨架Index/Landing 页由单句 Hook 内容表链接描述 Getting Started编号步骤 Choose Your Path可选决策树组成**概念解释页Concept**遵循定义性开场 → Types/Categories → Key Differences 对比表 → Components/Parts → Which Should You Use → Creating/Customizing指向 how-to**功能解释页Feature**则按功能作用 → Quick Facts → When to Use/Not to Use → How It Works → Key Benefits → 对比表 → When to Graduate/Upgrade组织**原理/哲学页Philosophy**聚焦核心原则 → The Problem → The Solution → Key Principles → Benefits → When This Applies。Explanation 检查清单Hook 清楚说明本文解释什么内容分布在可扫读的##区块3 个以上选项时使用对比表图示有清晰标签程序性问题链接到 how-to每篇控制在 2-3 个 admonition特别值得注意的是程序性问题链接到 how-to这一条Explanation 只负责解释概念与原因凡是怎么做的步骤性问题必须链接到对应的 How-to 文档二者职责分离、互不越界。仓库 docs/zh-cn/explanation/ 目录下的project-context.md、why-solutioning-matters.md等文件即属此类。Reference 结构参考类文档提供可查证的事实与参数按详尽程度分为六种类型类型示例Index/Landingworkflows/index.mdCatalogagents/index.mdDeep-Divedocument-project.mdConfigurationcore-tasks.mdGlossaryglossary/index.mdComprehensivebmgd-workflows.md各类型的骨架要点Reference 索引页单句 Hook 按类别组织的##内容区每类下列链接 简短描述。Catalog 参考页Hook 每项一个##单句说明 Skills:或Key Info:平铺列表 可选的 Universal/Shared 节。Deep-Dive 参考页单句用途说明 → Quick Factsnote 提示块列出 Module/Skill/Input/Output→ Purpose/Overview → How to Invoke代码块→ Key Sections每个方面一个##子选项用###→ Notes/Caveatstip/caution。Configuration 参考页Hook 可选目录4 项以上建议加 每项一个##统一采用粗体摘要单句→Use it when:场景列表 →How it works:3-5 步 →Output:可选的结构。综合参考页ComprehensiveOverview用图或表解释组织方式 每个阶段/类别一个## 每项一个###字段统一为 Skill、Agent、Input、Output、Description。Reference 检查清单Hook 说明本文引用什么结构匹配参考页类型条目结构前后一致结构化信息优先表格表达概念深度指向 explanation 页面每篇 1-2 个 admonition从源码可以印证 Reference 目录的设计仓库 docs/zh-cn/reference/ 下的agents.md、commands.md、core-tools.md、modules.md、testing.md、workflow-map.md均为该类型而 docs-site/astro.config.mjs 中 Reference 侧边栏采用autogenerate: { directory: reference }自动生成条目——因此这些文档的 frontmatter 与标题层级必须严格一致才能保证侧边栏渲染稳定。Glossary 结构术语表是 Starlight 站内可被右侧 On this page 导航索引的结构化词条集合分类使用##会进入右侧导航术语放在表格行中不要给每个术语单独标题不要再写内联 TOC表格模板## Category Name | Term | Definition | | ------------ | ---------------------------------------------------------------------------------------- | | **Agent** | Specialized AI persona with specific expertise that guides users through workflows. | | **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |定义规则推荐避免直接写它是什么/做什么以 This is... 或 A [term] is... 开头控制在 1-2 句多段长解释术语名称加粗术语用普通文本语境标记Context Markers对于只在特定场景下成立的术语在定义开头用斜体标记适用范围*Direct-entry implementation only.**BMad Method/Enterprise.**Phase N.**BMGD.**Established projects.*Glossary 检查清单术语以表格维护不用独立标题同分类内按字母序排序定义控制在 1-2 句语境标记使用斜体术语名称在单元格中加粗避免 A [term] is... 句式语境标记的设计值得展开BMAD 的术语经常跨版本与场景例如Direct-entry implementation与Established projects的上下文含义不同斜体标记让读者在阅读词条的第一眼就确认它是否适用于自己的场景避免误用。FAQ 章节模板FAQ 并非独立文档类型而是可作为任何文档末尾的收尾章节。规范给出了标准模板## Questions - [Do I always need architecture?](#do-i-always-need-architecture) - [Can I change my plan later?](#can-i-change-my-plan-later) ### Do I always need architecture? Only for work that benefits from architecture. Clear work can enter implementation directly. ### Can I change my plan later? Yes. The bmad-correct-course workflow handles scope changes mid-implementation. **Have a question not answered here?** Open an issue or ask in Discord.模板要求顶部用问题 锚点链接清单充当快速索引每个问题一个###子标题回答保持 1-2 句、直接给出结论。这一模板在 docs/zh-cn/tutorials/getting-started.md 的常见问题一节中得到印证我总是需要架构吗我可以稍后更改我的计划吗等。校验命令与仓库中的自动化工具规范最后给出提交文档改动前的完整校验流程这些命令在 docs-site/package.json 中均有对应实现cd docs-site npm run fix-links # 预览链接修复结果 npm run fix-links -- --write # 写回链接修复 npm run validate-links # 校验链接是否存在 npm run build # 校验站点构建深入源码可以看到这套校验体系的实际机制fix-doc-links.js扫描docs/下全部 Markdown 文件跳过_*开头路径将相对链接./file.md、../other/file.md、/path/file/目录引用统一转换为仓库相对路径并补全.md扩展名同时跳过代码块内的链接、外部链接与锚点链接。这保证了同一份文档在 GitHub 与 Starlight 站点上都能正确跳转。默认是 dry-run 预览模式加--write才实际写回。validate-doc-links.js校验站点相对链接/开头是否指向存在的.md文件、锚点链接是否指向有效标题对失效链接还会尝试在同目录下搜索同名文件并给出自动修复建议。校验失败时以非零退出码结束process.exit(totalIssues 0 ? 1 : 0)可直接接入 CI。validate-sidebar-order.js校验 frontmatter 中sidebar.order的编号是否重复、是否断号、是否为合法正整数对翻译文档还会对比其与英文原版的 order 是否漂移drift 仅告警不阻断。它通过正则解析 YAML frontmatter 中的 block mapping 与 flow mapping 两种写法并以LOCALE_RE /^[a-z]{2}(?:-[a-zA-Z0-9])*$/识别语言目录如zh-cn、ko-kr。多语言与站点渲染机制这套规范之所以强调标题预算与结构一致性根源在于站点是多语言多主题渲染的docs-site/src/lib/locales.mjs 定义了 6 个语言环境root/en、ko-kr、vi-vn、zh-cn、fr、csStarlight 为每种语言生成带 URL 前缀的独立页面docs-site/astro.config.mjs 中tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }直接决定了只有 H2/H3 进入页面导航——任何文档若突破标题预算或使用####就会立刻反映在目录可用性上。此外仓库的 rehype 插件链rehype-inline-diagrams.js、rehype-markdown-links、rehype-base-paths会在构建期把文档中的/diagrams/*.svg图内联进页面、按语言替换 SVG 内的data-i18n标签文本并重写链接路径这意味着文档中引用的所有资源路径都必须真实存在也正因如此只引用已确认存在的路径成为撰写规范的一部分。写在最后对于想要为 BMAD-METHOD 贡献文档或在自己的项目中建立类似文档体系的读者建议按以下顺序落地先固定项目特定规则表禁用####、控制标题预算、admonition 取代粗体提醒再按 Diataxis 四类文档骨架分门别类组织内容最后把链接修复、链接校验、侧边栏顺序校验接入提交前检查。中文版规范 docs/zh-cn/_STYLE_GUIDE.md 与英文原版 docs/_STYLE_GUIDE.md 结构对应docs/zh-cn/tutorials/getting-started.md 则是规范落地的完整示例可作为新文档撰写的直接参照物。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 BMAD-METHOD 文档写作规范指南：基于 Google 风格与 Diataxis 结构的项目文档体系
BMAD-METHOD 文档写作规范指南基于 Google 风格与 Diataxis 结构的项目文档体系【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD本文讲解 BMAD-METHOD 仓库Breakthrough Method for Agile AI Driven Development文档站点所采用的统一写作规范——它以 Google Developer Documentation Style Guide 为文风基准、以 Diataxis 方法论组织内容结构再叠加项目自身的约束规则。读完本文你将掌握如何按规范撰写 Tutorial、How-to、Explanation、Reference、Glossary 与 FAQ 六类文档理解:::note等提示块admonition的 Starlight 语法并能使用仓库内置的链接修复与校验脚本在提交前自动把关。核心规范见 docs/zh-cn/_STYLE_GUIDE.md英文原版见 docs/_STYLE_GUIDE.md。规范体系的三层结构BMAD-METHOD 的文档规范由三层组成层层递进文风基准遵循 Google Developer Documentation Style Guide——用具体、熟悉的词汇和短句让主要观点易于查找和行动只在读者使用 BMAD 确实需要时才引入专业术语且首次出现时给出定义先给结论再给限定条件与细节删掉重复、拖延进入主题的开场、夸大其词与不影响读者决策的免责声明。结构框架使用 Diataxis 方法论将文档分为 Tutorial教程、How-to操作指南、Explanation解释、Reference参考四大类型每类有固定的章节骨架。项目级约束在以上两者之上中文版规范 docs/zh-cn/_STYLE_GUIDE.md 用一张规则表明确可以做与不可以做保证全站格式一致。这套规范并非纸面要求而是由 docs-site/ 下的 Astro Starlight 站点落地执行astro.config.mjs中的 Starlight 配置、侧边栏定义与 rehype 插件链共同决定了文档如何被渲染、导航如何生成、多语言如何组织。项目特定规则一览中文版规范开篇即给出项目级约束表这是全站最核心的硬性规定规则规范禁用水平分割线---会打断阅读流禁用####标题用加粗短句或 admonition 替代避免 Related/Next 章节交给侧边栏导航避免深层嵌套列表拆成新段落或新小节非代码内容不要放代码块对话/提示用 admonition不用整段粗体做提醒统一用 admonition每节 1-2 个 admonition教程大节可放宽到 3-4 个表格单元格/列表项控制在 1-2 句标题预算每篇约 8-12 个##每节 2-3 个###逐条解读其中的设计意图标题层级预算##H2每篇限制在 8-12 个、每节内###H3限制在 2-3 个是因为 Starlight 的目录组件tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }见 docs-site/astro.config.mjs只把 H2/H3 纳入右侧 On this page 导航。层级越多导航越臃肿禁用####H4则避免导航失控。admonition 取代粗体与代码块对话、提示、风险提醒这类非代码内容放进提示块而不是塞进代码块或整段加粗是为了保证视觉语义统一——提示块有明确的类型色标tip/note/caution/danger。侧边栏接管导航由于 docs-site/astro.config.mjs 中配置了完整的 sidebar 结构Start、Build、Plan Larger Work、Existing Codebases、Customize and Extend、Reference、BMad EcosystemRelated/Next 这类文内跳转章节就变得多余统一交给侧边栏。提示块Admonition的 Starlight 语法规范定义的四类提示块使用 Starlight 的:::语法完整写法如下:::tip[Title] Shortcuts, best practices ::: :::note[Title] Context, definitions, examples, prerequisites ::: :::caution[Title] Caveats, potential issues ::: :::danger[Title] Critical warnings only — data loss, security issues :::四类提示块的职责边界非常明确tip放快捷键与最佳实践note放上下文、定义、示例与前置条件caution放注意事项与潜在问题danger只用于数据丢失、安全类严重警告不得滥用。标准用途提示块适用场景:::note[Prerequisites]开始前依赖与前置条件:::tip[Quick Path]文档顶部 TL;DR:::caution[Important]关键风险提醒:::note[Example]命令/响应示例说明这套用法在仓库文档中随处可见。以 docs/zh-cn/tutorials/getting-started.md 为例开篇用:::note[前置条件]列出 Node.js 20.12、Git、AI 驱动的 IDE 等依赖紧随其后用:::tip[最简单的路径]给出 安装 → 询问 → 构建 的 TL;DR文中还用:::caution[新对话]提醒始终为每个工作流开始一个新的对话并在结尾用:::tip[记住这些]收束关键要点——与规范中Quick Path 放文档顶部、Key Takeaways 放末尾的要求完全吻合。标准表格模板规范为最常见的两类信息提供了可直接复用的表格模板阶段表用于描述 BMad 的四阶段流程与技能表用于列出工作流、所属智能体与用途。| Phase | Name | What Happens | | ----- | -------- | -------------------------------------------- | | 1 | Analysis | Brainstorm, research *(optional)* | | 2 | Planning | Requirements — PRD or spec *(required)* || Skill | Agent | Purpose | | -------------------- | ------- | ------------------------------------ | | bmad-brainstorming | Analyst | Brainstorm a new project | | bmad-prd | PM | Create Product Requirements Document |从 docs/zh-cn/tutorials/getting-started.md 的实际使用可以看到这两个模板的演化阶段表被扩展为分析、规划、解决方案设计、实现四行并标注可选/按需技能表则扩展为工作流 | 命令 | 智能体 | 目的四列把bmad-help、bmad-prd、bmad-build等 8 个核心工作流一次列全作为文末的快速参考。文件结构块Folder Structure用于 What Youve Accomplished你已完成的工作类章节展示项目落地后应拥有的目录骨架your-project/ ├── _bmad/ # BMad configuration ├── _bmad-output/ │ ├── planning-artifacts/ │ │ └── PRD.md # Your requirements document │ ├── implementation-artifacts/ │ └── project-context.md # Implementation rules (optional) └── ...中文版规范在此基础上补充了注释说明_bmad/存放 BMad 配置_bmad-output/下的planning-artifacts/存放 PRD、architecture、epics 等规划产物implementation-artifacts/存放实现产物project-context.md记录实现规则可选。这一结构在 docs/zh-cn/tutorials/getting-started.md 的你已完成的工作一节中被完整实例化目录树展开为planning-artifacts/下的PRD.md、architecture.md、epics/以及implementation-artifacts/下的sprint-status.yaml。教程Tutorial结构教程是引导读者从零到一完成任务的内容类型规范规定其固定骨架1. Title Hook1-2 句结果导向开场 2. Version/Module Notice可选信息或警告提示块 3. What Youll Learn结果清单 4. Prerequisites前置条件提示块 5. Quick PathTL;DR 提示块 6. Understanding [Topic]步骤前的背景说明可配表格 7. Installation可选 8. Step 1: [First Major Task] 9. Step 2: [Second Major Task] 10. Step 3: [Third Major Task] 11. What Youve Accomplished总结 文件结构 12. Quick Referenceskills 表 13. Common QuestionsFAQ 14. Getting Help社区入口 15. Key Takeaways末尾 tip 提示块教程检查清单Hook 用 1-2 句明确结果包含 What Youll Learn前置条件放在 admonition顶部有 Quick Path TL;DR关键信息用 phases/skills/agents 表格包含 What Youve Accomplished包含 Quick Reference 表包含 Common Questions包含 Getting Help末尾包含 Key Takeaways 提示块中文快速入门教程 正是这一骨架的完整范本它从你将学到与前置条件提示块开始依次经过认识 BMad-HelpUnderstanding 部分、安装Installation、步骤 1选择规划深度与步骤 2构建你的项目编号步骤、你已完成的工作含文件结构块、快速参考技能表、常见问题FAQ、获取帮助Getting Help直到关键要点末尾 tip——15 个环节逐一命中可作为撰写新教程时的对照样本。How-to 结构操作指南解决具体怎么做的问题骨架如下1. Title Hook单句形如 Use the X workflow to... 2. When to Use This3-5 条场景 3. When to Skip This可选 4. Prerequisitesnote 提示块 5. Steps编号 ### 动词开头 6. What You Get产出物说明 7. Example可选 8. Tips可选 9. Next Steps可选How-to 检查清单Hook 以 Use theXworkflow to... 开头When to Use This 有 3-5 条场景明确前置条件步骤为编号###子标题且动词开头What You Get 明确产出物How-to 与 Tutorial 的核心区别在于Tutorial 面向第一次学的读者、按顺序走完整个流程How-to 面向要解决特定问题的读者、可直接定位到所需步骤。规范要求 Hook 必须采用 Use theXworkflow to... 的单句句式让读者一眼判断本文是否适用步骤一律用###子标题且以动词开头如调用 PM 智能体运行bmad-prd工作流便于目录扫描与快速跳转。Explanation 结构解释类文档回答它是什么、为什么这样设计是理解 BMAD 各阶段与模块的入口。类型类型示例Index/Landingcore-concepts/index.mdConceptwhat-are-agents.mdFeaturebuild.mdPhilosophywhy-solutioning-matters.mdFAQestablished-projects-faq.md通用模板1. Title Hook1-2 句 2. Overview/Definition是什么为什么重要 3. Key Concepts### 小节 4. Comparison Table可选 5. When to Use / When Not to Use可选 6. Diagram可选单文档最多 1 个 mermaid 7. Next Steps可选针对不同子类型规范还给出了更细的骨架Index/Landing 页由单句 Hook 内容表链接描述 Getting Started编号步骤 Choose Your Path可选决策树组成**概念解释页Concept**遵循定义性开场 → Types/Categories → Key Differences 对比表 → Components/Parts → Which Should You Use → Creating/Customizing指向 how-to**功能解释页Feature**则按功能作用 → Quick Facts → When to Use/Not to Use → How It Works → Key Benefits → 对比表 → When to Graduate/Upgrade组织**原理/哲学页Philosophy**聚焦核心原则 → The Problem → The Solution → Key Principles → Benefits → When This Applies。Explanation 检查清单Hook 清楚说明本文解释什么内容分布在可扫读的##区块3 个以上选项时使用对比表图示有清晰标签程序性问题链接到 how-to每篇控制在 2-3 个 admonition特别值得注意的是程序性问题链接到 how-to这一条Explanation 只负责解释概念与原因凡是怎么做的步骤性问题必须链接到对应的 How-to 文档二者职责分离、互不越界。仓库 docs/zh-cn/explanation/ 目录下的project-context.md、why-solutioning-matters.md等文件即属此类。Reference 结构参考类文档提供可查证的事实与参数按详尽程度分为六种类型类型示例Index/Landingworkflows/index.mdCatalogagents/index.mdDeep-Divedocument-project.mdConfigurationcore-tasks.mdGlossaryglossary/index.mdComprehensivebmgd-workflows.md各类型的骨架要点Reference 索引页单句 Hook 按类别组织的##内容区每类下列链接 简短描述。Catalog 参考页Hook 每项一个##单句说明 Skills:或Key Info:平铺列表 可选的 Universal/Shared 节。Deep-Dive 参考页单句用途说明 → Quick Factsnote 提示块列出 Module/Skill/Input/Output→ Purpose/Overview → How to Invoke代码块→ Key Sections每个方面一个##子选项用###→ Notes/Caveatstip/caution。Configuration 参考页Hook 可选目录4 项以上建议加 每项一个##统一采用粗体摘要单句→Use it when:场景列表 →How it works:3-5 步 →Output:可选的结构。综合参考页ComprehensiveOverview用图或表解释组织方式 每个阶段/类别一个## 每项一个###字段统一为 Skill、Agent、Input、Output、Description。Reference 检查清单Hook 说明本文引用什么结构匹配参考页类型条目结构前后一致结构化信息优先表格表达概念深度指向 explanation 页面每篇 1-2 个 admonition从源码可以印证 Reference 目录的设计仓库 docs/zh-cn/reference/ 下的agents.md、commands.md、core-tools.md、modules.md、testing.md、workflow-map.md均为该类型而 docs-site/astro.config.mjs 中 Reference 侧边栏采用autogenerate: { directory: reference }自动生成条目——因此这些文档的 frontmatter 与标题层级必须严格一致才能保证侧边栏渲染稳定。Glossary 结构术语表是 Starlight 站内可被右侧 On this page 导航索引的结构化词条集合分类使用##会进入右侧导航术语放在表格行中不要给每个术语单独标题不要再写内联 TOC表格模板## Category Name | Term | Definition | | ------------ | ---------------------------------------------------------------------------------------- | | **Agent** | Specialized AI persona with specific expertise that guides users through workflows. | | **Workflow** | Multi-step guided process that orchestrates AI agent activities to produce deliverables. |定义规则推荐避免直接写它是什么/做什么以 This is... 或 A [term] is... 开头控制在 1-2 句多段长解释术语名称加粗术语用普通文本语境标记Context Markers对于只在特定场景下成立的术语在定义开头用斜体标记适用范围*Direct-entry implementation only.**BMad Method/Enterprise.**Phase N.**BMGD.**Established projects.*Glossary 检查清单术语以表格维护不用独立标题同分类内按字母序排序定义控制在 1-2 句语境标记使用斜体术语名称在单元格中加粗避免 A [term] is... 句式语境标记的设计值得展开BMAD 的术语经常跨版本与场景例如Direct-entry implementation与Established projects的上下文含义不同斜体标记让读者在阅读词条的第一眼就确认它是否适用于自己的场景避免误用。FAQ 章节模板FAQ 并非独立文档类型而是可作为任何文档末尾的收尾章节。规范给出了标准模板## Questions - [Do I always need architecture?](#do-i-always-need-architecture) - [Can I change my plan later?](#can-i-change-my-plan-later) ### Do I always need architecture? Only for work that benefits from architecture. Clear work can enter implementation directly. ### Can I change my plan later? Yes. The bmad-correct-course workflow handles scope changes mid-implementation. **Have a question not answered here?** Open an issue or ask in Discord.模板要求顶部用问题 锚点链接清单充当快速索引每个问题一个###子标题回答保持 1-2 句、直接给出结论。这一模板在 docs/zh-cn/tutorials/getting-started.md 的常见问题一节中得到印证我总是需要架构吗我可以稍后更改我的计划吗等。校验命令与仓库中的自动化工具规范最后给出提交文档改动前的完整校验流程这些命令在 docs-site/package.json 中均有对应实现cd docs-site npm run fix-links # 预览链接修复结果 npm run fix-links -- --write # 写回链接修复 npm run validate-links # 校验链接是否存在 npm run build # 校验站点构建深入源码可以看到这套校验体系的实际机制fix-doc-links.js扫描docs/下全部 Markdown 文件跳过_*开头路径将相对链接./file.md、../other/file.md、/path/file/目录引用统一转换为仓库相对路径并补全.md扩展名同时跳过代码块内的链接、外部链接与锚点链接。这保证了同一份文档在 GitHub 与 Starlight 站点上都能正确跳转。默认是 dry-run 预览模式加--write才实际写回。validate-doc-links.js校验站点相对链接/开头是否指向存在的.md文件、锚点链接是否指向有效标题对失效链接还会尝试在同目录下搜索同名文件并给出自动修复建议。校验失败时以非零退出码结束process.exit(totalIssues 0 ? 1 : 0)可直接接入 CI。validate-sidebar-order.js校验 frontmatter 中sidebar.order的编号是否重复、是否断号、是否为合法正整数对翻译文档还会对比其与英文原版的 order 是否漂移drift 仅告警不阻断。它通过正则解析 YAML frontmatter 中的 block mapping 与 flow mapping 两种写法并以LOCALE_RE /^[a-z]{2}(?:-[a-zA-Z0-9])*$/识别语言目录如zh-cn、ko-kr。多语言与站点渲染机制这套规范之所以强调标题预算与结构一致性根源在于站点是多语言多主题渲染的docs-site/src/lib/locales.mjs 定义了 6 个语言环境root/en、ko-kr、vi-vn、zh-cn、fr、csStarlight 为每种语言生成带 URL 前缀的独立页面docs-site/astro.config.mjs 中tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }直接决定了只有 H2/H3 进入页面导航——任何文档若突破标题预算或使用####就会立刻反映在目录可用性上。此外仓库的 rehype 插件链rehype-inline-diagrams.js、rehype-markdown-links、rehype-base-paths会在构建期把文档中的/diagrams/*.svg图内联进页面、按语言替换 SVG 内的data-i18n标签文本并重写链接路径这意味着文档中引用的所有资源路径都必须真实存在也正因如此只引用已确认存在的路径成为撰写规范的一部分。写在最后对于想要为 BMAD-METHOD 贡献文档或在自己的项目中建立类似文档体系的读者建议按以下顺序落地先固定项目特定规则表禁用####、控制标题预算、admonition 取代粗体提醒再按 Diataxis 四类文档骨架分门别类组织内容最后把链接修复、链接校验、侧边栏顺序校验接入提交前检查。中文版规范 docs/zh-cn/_STYLE_GUIDE.md 与英文原版 docs/_STYLE_GUIDE.md 结构对应docs/zh-cn/tutorials/getting-started.md 则是规范落地的完整示例可作为新文档撰写的直接参照物。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考