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 是一个面向 AI 驱动敏捷开发的方法论项目，其文档站点建立在 Astro + Starlight 之上，并以多语言（英文、法语、简体中文、韩语、越南语、捷克语）平行维护。本文以仓库中 docs/fr/_STYLE_GUIDE.md（法语版文档风格指南）为骨架，完整梳理该项目的文档写作规范——从项目级硬性规则、Starlight admonition 语法、标准表格模板，到 Tutorial / How-To / Explanation / Reference / Glossary / FAQ 六大文档类型的结构模板与检查清单，并结合 docs-site 下的校验脚本与构建配置，讲清每一条规范背后的工程落地方式。读完本文，你将能按 BMAD-METHOD 的规范撰写、校验并提交任何一篇文档。

规范体系的定位：两套外部基准 + 一层项目约束

BMAD-METHOD 的文档写作并非从零发明规则，而是建立在两个成熟的外部基准之上：

• Google Developer Documentation Style Guide（Google 开发者文档风格指南）：负责语言层面的通用规范——用词、句式、术语、标点等；
• Diataxis（diataxis.fr）：负责内容组织层面的分类框架，将文档划分为 Tutorial（教程）、How-To（操作指南）、Explanation（解释）、Reference（参考）四大类。

因此，各语言版本的_STYLE_GUIDE.md（如 docs/_STYLE_GUIDE.md、docs/zh-cn/_STYLE_GUIDE.md、docs/fr/_STYLE_GUIDE.md）都只列出「项目特有」的约定，避免与外部基准重复——这也是该指南文件体积不大、但约束力极强的根本原因。

从仓库结构看，这套规范直接服务于 docs-site 这个 Astro + Starlight 文档站点：astro.config.mjs中配置了@astrojs/starlight（版本^0.41.1，见 docs-site/package.json），并启用了lastUpdated、自定义侧边栏、tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }等选项。指南中「禁用####标题」「8-12 个##」等规则，正是为了让目录导航（On this page）在 2-3 级标题范围内保持整洁——规范与站点能力是互相咬合的。

项目特定规则：十项硬性约束

指南首先给出了一张项目级规则表，这些规则适用于所有页面：

逐一解读关键规则的设计意图：

• 禁用####：Starlight 的右侧「On this page」导航由标题层级生成，指南要求控制在##与###两级（与astro.config.mjs中tableOfContents的minHeadingLevel: 2, maxHeadingLevel: 3完全对应）。需要第四层表达时，用加粗短句或admonition代替，避免导航膨胀。
• 禁用水平分割线：Starlight 内容基于 markdown 片段组织，---既是 H2 的分隔符也是水平线的语法，容易造成解析歧义与阅读割裂。
• admonition 数量配额：指南对 admonition 数量做了明确预算——普通章节 1-2 个，教程大章节 3-4 个，Explanation/Reference 类文档全篇 2-3 个。这保证了提示框是「点睛」而非「噪音」。

Admonition 体系：Starlight 语法与四种语义

BMAD-METHOD 用 Starlight 的 admonition 语法统一表达提示、背景、警告与危险信息。完整语法如下：

:::tip[Titre] Raccourcis, bonnes pratiques ::: :::note[Titre] Contexte, définitions, exemples, prérequis ::: :::caution[Titre] Mises en garde, problèmes potentiels ::: :::danger[Titre] Avertissements critiques uniquement — perte de données, problèmes de sécurité :::

四种 admonition 各有明确的语义边界，指南规定了它们的标准用途：

值得注意的设计细节：

• danger仅限极端场景：只有数据丢失、安全问题等才允许使用，防止「狼来了」效应；
• tip用于 Quick Path：每篇文档顶部用 tip admonition 给出 TL;DR，让忙碌的读者 30 秒内掌握要点；
• 对话示例不放代码块：指南明确「非代码内容不要放入代码块」，对话、命令输出等一律用:::note[Example]承载——因为代码块会触发复制按钮、等宽字体等不适合对话场景的样式。

标准表格模板：Phases 与 Skills

表格是 BMAD-METHOD 文档展示结构化信息的主要手段。指南给出了两套标准模板。

阶段表（Phases）——用于 Tutorial 的 "Understanding [Topic]" 与 Explanation 文档：

| Phase | Nom | Ce qui se passe | |-------|---------------|-------------------------------------------------------| | 1 | Analyse | Brainstorm, recherche *(optionnel)* | | 2 | Planification | Exigences — PRD ou spécification technique *(requis)* |

技能表（Skills）——用于 Quick Reference、Reference 类文档：

| Skill | Agent | Objectif | |----------------------|----------|---------------------------------------| | `bmad-brainstorming` | Analyste | Brainstorming pour un nouveau projet | | `bmad-prd` | PM | Créer un document d'exigences produit |

这些表中的技能名并非虚构：仓库 skills 目录下真实存在bmad-brainstorming、bmad-prd、bmad-spec、bmad-ux等模块，每个模块包含SKILL.md、module-manifest.toml与customize.toml，分别对应技能定义、模块清单与自定义入口；Agent 类型（Analyste、PM 等）也与bmad-agent-*系列模块一一对应。写文档时引用这些技能名，读者可以直接跳转到对应模块继续深入。

文件夹结构块：展示 "What You've Accomplished"

Tutorial 与 How-To 的结尾通常需要向读者展示「你完成了什么」，指南规定用文件夹树形结构块来呈现产出物：

``` votre-projet/ ├── _bmad/ # Configuration BMad ├── _bmad-output/ │ ├── planning-artifacts/ │ │ └── PRD.md # Votre document d'exigences │ ├── implementation-artifacts/ │ └── project-context.md # Règles d'implémentation (optionnel) └── ... ```

该结构块与实际产物目录吻合：_bmad/存放 BMad 配置（配置模板可见于 skills/bmad/assets/config.template.toml），_bmad-output/下按planning-artifacts/与implementation-artifacts/分类存放规划产物与实现产物。编写文档时应使用真实的目录名，避免虚构路径。

Tutorial 结构：15 步标准模板

Tutorial 是 Diataxis 中「以学习为目标」的文档类型。BMAD-METHOD 将一篇完整的教程固定为 15 个步骤：

1. Titre + Accroche（标题 + 开场白，1-2 句描述学习成果） 2. Notice de version/module（版本/模块提示，可选，用 info 或 warning admonition） 3. Ce que vous allez apprendre（你将学到什么，用项目符号列出成果） 4. Prérequis（前置条件，用 info admonition） 5. Chemin rapide（快速路径，用 tip admonition 给出 TL;DR） 6. Comprendre [Sujet]（理解主题，步骤前的背景说明，阶段/Agent 用表格） 7. Installation（安装，可选） 8. Étape 1 : [Première tâche majeure]（步骤 1） 9. Étape 2 : [Deuxième tâche majeure]（步骤 2） 10. Étape 3 : [Troisième tâche majeure]（步骤 3） 11. Ce que vous avez accompli（你已完成什么，总结 + 文件夹结构） 12. Référence rapide（快速参考，技能表） 13. Questions courantes（常见问题，FAQ 格式） 14. Obtenir de l'aide（获取帮助，社区链接） 15. Points clés à retenir（关键要点，结尾 tip admonition）

教程检查清单

每篇教程提交前，对照以下清单逐项核验：

• 开场白用 1-2 句描述学习成果
• 包含 "Ce que vous allez apprendre" 小节
• 前置条件放在 admonition 中
• 顶部有 Quick Path TL;DR admonition
• 阶段 / 技能 / Agent 用表格呈现
• 包含 "Ce que vous avez accompli" 小节
• 包含快速参考表
• 包含常见问题小节
• 包含获取帮助小节
• 结尾包含关键要点 admonition

这个模板在仓库中已有实例可对照，例如 docs/tutorials/getting-started.md（英文）与 docs/fr/tutorials/getting-started.md（法语）。

How-To 结构：以「操作」为中心的 9 步模板

How-To 解决「如何用工作流 X 完成某事」的实操问题，结构与 Tutorial 互补。指南规定的模板如下：

1. Titre + Accroche（单句开场，固定句式：「Utilisez le workflow `X` pour...」） 2. Quand utiliser ce guide（何时使用本指南，3-5 条场景） 3. Quand éviter ce guide（何时不需要本指南，可选） 4. Prérequis（前置条件，用 note admonition） 5. Étapes（操作步骤，用编号 `###` 子标题，动词开头） 6. Ce que vous obtenez（你将得到什么，产出物/产物说明） 7. Exemple（示例，可选） 8. Conseils（技巧，可选） 9. Prochaines étapes（后续步骤，可选）

How-To 检查清单

• 开场白以「Utilisez le workflowXpour...」句式开头
• "Quand utiliser ce guide" 包含 3-5 个要点
• 前置条件已列出
• 步骤为编号###子标题且以动作动词开头
• "Ce que vous obtenez" 明确描述产出物

注意 Tutorial 与 How-To 的分工：Tutorial 面向「学习」，以结果清单开头、以收获总结结尾；How-To 面向「完成一项任务」，以场景判断开头、以产出物说明结尾。写作者应先判断文档属于哪一类，再套用对应模板，而不是混合两种结构。

Explanation 结构：五类解释文档

Explanation 回答「为什么」与「是什么」，是 Diataxis 中概念密度最高的一类。指南首先定义了五种子类型：

这五种类型在仓库中都能找到对应实例，例如 docs/explanation/why-solutioning-matters.md（哲学类）、docs/explanation/established-projects-faq.md（FAQ 类）。

通用模板

1. Titre + Accroche（1-2 句） 2. Vue d'ensemble/Définition（概述/定义：是什么、为什么重要） 3. Concepts clés（核心概念，用 `###` 小节） 4. Tableau comparatif（对比表，可选） 5. Quand utiliser / Quand ne pas utiliser（何时使用/不使用，可选） 6. Diagramme（图示，可选——单篇文档最多 1 个） 7. Prochaines étapes（后续步骤，可选）

索引/首页页面

1. Titre + Accroche（单句） 2. Tableau de contenu（内容表，链接 + 描述） 3. Pour commencer（开始，编号列表） 4. Choisissez votre parcours（选择你的路径，可选——决策树）

概念解释页

1. Titre + Accroche（定义性开场） 2. Types/Catégories（类型/分类，可选，`###` 小节） 3. Tableau des différences clés（关键差异表） 4. Composants/Parties（组成部分） 5. Lequel devriez-vous utiliser ?（你应该用哪个？） 6. Création/Personnalisation（创建/自定义，链接到 How-To 指南）

功能解释页

1. Titre + Accroche（功能作用） 2. Faits rapides（快速事实，可选，如 "Idéal pour :"、"Temps :"） 3. Quand utiliser / Quand ne pas utiliser 4. Comment cela fonctionne（工作原理，可选 mermaid 图示） 5. Avantages clés（核心优势） 6. Tableau comparatif（对比表，可选） 7. Quand évoluer/mettre à niveau（何时升级/演进，可选）

哲学/原理文档

1. Titre + Accroche（核心原则） 2. Le problème（问题） 3. La solution（解决方案） 4. Principes clés（核心原则，`###` 小节） 5. Avantages（优势） 6. Quand cela s'applique（何时适用）

Explanation 检查清单

• 开场白说明「本文解释什么」
• 内容分布在可扫读的##区块
• 3 个以上选项时使用对比表
• 图示有清晰标签
• 程序性问题链接到 How-To 指南
• 全篇不超过 2-3 个 admonition

Reference 结构：六类参考页

Reference 是读者「快速查证」的场所，追求一致性与可扫描性。指南定义了六种子类型：

参考索引页

1. Titre + Accroche（单句） 2. Sections de contenu（内容章节，每个类别一个 `##`） - 项目符号列表，含链接与描述

目录参考页

1. Titre + Accroche 2. Éléments（条目，每项一个 `##`） - 单句简介 - **Skills :** 或 **Infos clés :** 平铺列表 3. Universel/Partagé（通用/共享，可选）

条目深入解析参考页

1. Titre + Accroche（单句说明用途） 2. Faits rapides（快速事实，可选 note admonition） - Module、Skill、Entrée、Sortie 以列表呈现 3. Objectif/Vue d'ensemble（目标/概述，`##`） 4. Comment invoquer（如何调用，代码块） 5. Sections clés（关键章节，每个方面一个 `##`） - 子选项用 `###` 6. Notes/Mises en garde（注意/警告，tip 或 caution admonition）

配置参考页

1. Titre + Accroche 2. Table des matières（目录，4 项以上时用跳转链接） 3. Éléments（条目，每项一个 `##`） - **Résumé en gras**（加粗摘要，单句） - **Utilisez-le quand :**（何时使用，项目符号列表） - **Comment cela fonctionne :**（工作原理，3-5 步编号步骤） - **Sortie :**（输出，可选）

综合参考指南

1. Titre + Accroche 2. Vue d'ensemble（概述，`##`，用图示或表格展示组织结构） 3. Sections majeures（主要章节，每个阶段/类别一个 `##`） - 条目（每项 `###`） - 统一字段：Skill、Agent、Entrée、Sortie、Description 4. Prochaines étapes（后续步骤，可选）

Reference 检查清单

• 开场白说明「本文引用什么」
• 结构匹配参考页类型
• 所有条目结构保持一致
• 结构化/对比数据用表格
• 概念深度链接到 Explanation 文档
• 全篇 1-2 个 admonition

Glossary 结构：术语表规范

术语表（Glossary）是唯一不遵循「每术语一个标题」规则的文档类型——因为 Starlight 会从标题生成右侧「On this page」导航，为每个术语建标题会导致导航失控。

三条铁律

• 分类用##标题（会进入右侧导航）
• 术语放进表格行（紧凑行，不单独建标题）
• 不写内联 TOC（右侧边栏负责导航）

表格模板

## Nom de catégorie | Terme | Définition | |--------------|------------------------------------------------------------------------------------------------------------| | **Agent** | Personnalité IA spécialisée avec une expertise spécifique qui guide les utilisateurs dans les workflows. | | **Workflow** | Processus guidé en plusieurs étapes qui orchestre les activités des agents IA pour produire des livrables. |

定义规则

语境标记（Context Markers）

对于适用范围有限的术语，在定义开头用斜体标注语境：

• *Implémentation en entrée directe uniquement.*（仅限直接输入式实现）
• *méthode BMad/Enterprise.*（BMad 方法 / 企业版）
• *Phase N.*（第 N 阶段）
• *BMGD.*
• *Projets établis.*（既有项目）

Glossary 检查清单

• 术语放在表格中，不单独建标题
• 同分类内术语按字母序排列
• 定义控制在 1-2 句
• 语境标记使用斜体
• 术语名称在单元格中加粗
• 避免「Un [terme] est...」句式

FAQ 章节模板

FAQ 可用于 Tutorial 的「Questions courantes」小节，也可作为独立的 Explanation 子类型。标准格式如下：

## Questions - [Ai-je toujours besoin d'architecture ?](#ai-je-toujours-besoin-darchitecture) - [Puis-je modifier mon plan plus tard ?](#puis-je-modifier-mon-plan-plus-tard) ### Ai-je toujours besoin d'architecture ? Uniquement pour les travaux qui bénéficient d'une architecture. Un travail clair peut entrer directement dans l'implémentation. ### Puis-je modifier mon plan plus tard ? Oui. Utilisez `bmad-correct-course` pour gérer les changements de portée en cours d'implémentation. **Une question sans réponse ici ?** Ouvrez une issue ou posez votre question sur Discord.

结构要点：先集中列出问题锚点，再逐题以###作答，答案遵循「1-2 句、直接回答」原则。示例中的bmad-correct-course是真实存在的技能（见 skills/bmad-correct-course/SKILL.md），用于处理实施中途的需求范围变更——文档示例应始终引用真实的工作流名称。

提交前的校验命令与底层实现

这是风格指南中「工程化落地」最强的部分：所有规范并非只靠人工自觉，而是由脚本强制校验。提交文档改动前必须执行：

cd docs-site npm run fix-links # 预览链接格式修复 npm run fix-links -- --write # 应用链接修复 npm run validate-links # 校验链接是否存在 npm run build # 校验站点能否正常构建

这些命令的实现在 docs-site/scripts 目录下，与 docs-site/package.json 中定义的 scripts 一一对应（另有validate-sidebar、locale-coverage、test等配套命令）。

fix-doc-links.js：链接格式的统一器

fix-doc-links.js 将所有 markdown 链接转换为仓库相对路径 +.md扩展名的规范格式，转换规则在其头部注释中说明：

• ./file.md→/docs/当前路径/file.md
• ../other/file.md→/docs/解析后路径/file.md
• /path/file/→/docs/path/file.md（若为目录则解析到index.md）

实现上有三个值得注意的细节：

1. 跳过外部链接与锚点：convertToRepoRelative对包含://、以//开头、mailto:、tel:的链接直接返回null，锚点链接（#开头）同样跳过；
2. 代码块保护：processFile先用占位符替换所有 ``` 代码块，只处理代码块之外的链接，避免误改代码示例中的路径；
3. 目录路径解析：当链接以/结尾时，按index.md→同名.md的顺序探测真实文件，探测不到则回退为index.md并交给校验环节兜底。

validate-doc-links.js：链接与锚点的双校验器

validate-doc-links.js 是更严格的一道关卡，检查两类问题：

• 站点相对链接（以/开头）是否指向真实存在的.md文件；
• 锚点链接（#section）是否指向目标文件中的有效标题——通过HEADING_PATTERN提取标题、headingToAnchor将标题转换为 slug（转小写、去 emoji、去特殊字符、空格转连字符）后比对。

它还会尝试自动修复：当链接失效且能在 docs 中找到「文件名 + 父目录」都匹配的唯一候选文件时，标记为auto-fixable并给出建议修复路径（fileToSiteRelative将文件路径转换为站点相对 URL）。运行npm run validate-links后，脚本会输出三类问题统计：Auto-fixable（可自动修复）、Needs review（多候选需人工裁决）、Manual check（需手动处理），并有问题的链接会让进程以退出码 1 结束——这正是 CI 中拦截坏链接的机制。

npm run build与 rehype 插件链

构建命令背后是 astro.config.mjs 中配置的三段式 rehype 插件链：

1. rehypeInlineDiagrams：将/diagrams/*.svg图片内联为 SVG 节点（而非<img>），使custom.css的样式能渗透到图内，实现一套图纸深浅双主题；同时根据data-i18n键从<name>.labels.json按页面语言替换标签文本——图纸不重画、只翻译；
2. rehypeMarkdownLinks：处理.md链接的最终路由化；
3. rehypeBasePaths：为以/开头的绝对 URL 前缀base路径（如/img/foo.png→/BMAD-METHOD/img/foo.png），保证站点部署在子路径下资源不 404。

这也解释了风格指南中「图示可选、单篇最多 1 个、必须带清晰标签」等约束：图示由 docs-site/src/diagrams 下手写的 SVG 驱动，每张图需要配套<name>.labels.json做多语言标签，属于高成本资产，应当克制使用。

配套的多语言文档工程

最后值得强调：风格指南本身也是多语言维护的。仓库 docs 目录下_STYLE_GUIDE.md同时存在于根目录（英文）、fr/、zh-cn/、cs/、vi-vn/、ko-kr/等语言目录中，内容保持平行。站点侧的语言配置集中在 docs-site/src/lib/locales.mjs，翻译字符串在 docs-site/src/content/i18n 下的fr-FR.json、zh-CN.json、ko-KR.json、vi-VN.json中维护，并有 validate-locale-coverage.mjs 配合 locale-coverage-baseline.json 校验各语言覆盖度。

对写作者的启示：当你为某语言新增或修改一篇文档时，应同步对照同目录下的_STYLE_GUIDE.md检查结构与格式，并在提交前跑完fix-links→validate-links→build三道校验——这是让多语言文档保持长期一致的最低成本路径。

快速自检：写一篇合格文档的最后十问

无论撰写哪类文档，提交前都可以用风格指南汇总成的问题做终检：

1. 开场白是否在 1-2 句内说清本文目的与读者收获？
2. 标题层级是否控制在##/###，且全篇##数量在 8-12 个？
3. 是否误用了水平分割线、####标题、"Related/Next" 章节或深层嵌套列表？
4. 对话/命令示例是否放进了 admonition 而非代码块？
5. admonition 数量是否在预算内（普通节 1-2 个、全篇 Explanation/Reference 2-3 个）？
6. 表格单元格与列表项是否控制在 1-2 句？
7. 文档类型（Tutorial / How-To / Explanation / Reference / Glossary）是否选对并套用了对应模板？
8. 引用的技能名（bmad-*）、目录结构（_bmad-output/）是否为仓库中的真实存在？
9. 所有相对链接是否转换为以仓库根目录为起点的路径？
10. 是否已运行npm run fix-links、npm run validate-links、npm run build三道校验？

把这份来自 docs/fr/_STYLE_GUIDE.md 的规范内化为一套写作习惯，就能让每一篇 BMAD-METHOD 文档既保持多语言一致性，又经得起自动化脚本的严格检验。

【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD