BMAD-METHOD 文档风格指南全解基于 Google 风格与 Diataxis 的多语言文档工程规范【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHODBMAD-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 GuideGoogle 开发者文档风格指南负责语言层面的通用规范——用词、句式、术语、标点等Diataxisdiataxis.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 级标题范围内保持整洁——规范与站点能力是互相咬合的。项目特定规则十项硬性约束指南首先给出了一张项目级规则表这些规则适用于所有页面规则规范禁用水平分割线---会打断文档片段的阅读流禁用####四级标题用加粗文本或 admonition 替代不设 Related/Next 章节导航交给侧边栏处理避免深层嵌套列表拆成新小节或新段落非代码内容不要放进代码块对话类示例用 admonition 呈现不用整段粗体做提醒统一改用 admonition每节最多 1-2 个 admonition教程的每个主要章节可放宽到 3-4 个表格单元格 / 列表项控制在 1-2 句话以内标题预算每篇文档约 8-12 个##每个章节 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 各有明确的语义边界指南规定了它们的标准用途Admonition用途:::note[Pré-requis]开始前的依赖与前置条件:::tip[Chemin rapide]文档顶部的 TL;DR 摘要:::caution[Important]关键风险提醒:::note[Exemple]命令 / 响应示例值得注意的设计细节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 dexigences produit |这些表中的技能名并非虚构仓库 skills 目录下真实存在bmad-brainstorming、bmad-prd、bmad-spec、bmad-ux等模块每个模块包含SKILL.md、module-manifest.toml与customize.toml分别对应技能定义、模块清单与自定义入口Agent 类型Analyste、PM 等也与bmad-agent-*系列模块一一对应。写文档时引用这些技能名读者可以直接跳转到对应模块继续深入。文件夹结构块展示 What Youve AccomplishedTutorial 与 How-To 的结尾通常需要向读者展示「你完成了什么」指南规定用文件夹树形结构块来呈现产出物 votre-projet/ ├── _bmad/ # Configuration BMad ├── _bmad-output/ │ ├── planning-artifacts/ │ │ └── PRD.md # Votre document dexigences │ ├── implementation-artifacts/ │ └── project-context.md # Règles dimplé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 laide获取帮助社区链接 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 中概念密度最高的一类。指南首先定义了五种子类型类型示例Index/Page daccueil索引/首页core-concepts/index.mdConcept概念what-are-agents.mdFonctionnalité功能build.mdPhilosophie哲学/原理why-solutioning-matters.mdFAQ常见问题established-projects-faq.md这五种类型在仓库中都能找到对应实例例如 docs/explanation/why-solutioning-matters.md哲学类、docs/explanation/established-projects-faq.mdFAQ 类。通用模板1. Titre Accroche1-2 句 2. Vue densemble/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 sapplique何时适用Explanation 检查清单开场白说明「本文解释什么」内容分布在可扫读的##区块3 个以上选项时使用对比表图示有清晰标签程序性问题链接到 How-To 指南全篇不超过 2-3 个 admonitionReference 结构六类参考页Reference 是读者「快速查证」的场所追求一致性与可扫描性。指南定义了六种子类型类型示例Index/Page daccueil索引/首页workflows/index.mdCatalogue目录agents/index.mdApprofondissement深入解析document-project.mdConfiguration配置core-tasks.mdGlossaire术语表glossary/index.mdComplet综合参考bmgd-workflows.md参考索引页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 densemble目标/概述## 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 densemble概述##用图示或表格展示组织结构 3. Sections majeures主要章节每个阶段/类别一个 ## - 条目每项 ### - 统一字段Skill、Agent、Entrée、Sortie、Description 4. Prochaines étapes后续步骤可选Reference 检查清单开场白说明「本文引用什么」结构匹配参考页类型所有条目结构保持一致结构化/对比数据用表格概念深度链接到 Explanation 文档全篇 1-2 个 admonitionGlossary 结构术语表规范术语表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. |定义规则推荐避免直接写「它是什么 / 做什么」以「Cest...」或「Un [terme] est...」开头控制在 1-2 句写多段长解释术语名称在单元格内加粗术语用普通文本语境标记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 darchitecture ?](#ai-je-toujours-besoin-darchitecture) - [Puis-je modifier mon plan plus tard ?](#puis-je-modifier-mon-plan-plus-tard) ### Ai-je toujours besoin darchitecture ? Uniquement pour les travaux qui bénéficient dune architecture. Un travail clair peut entrer directement dans limplémentation. ### Puis-je modifier mon plan plus tard ? Oui. Utilisez bmad-correct-course pour gérer les changements de portée en cours dimplé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实现上有三个值得注意的细节跳过外部链接与锚点convertToRepoRelative对包含://、以//开头、mailto:、tel:的链接直接返回null锚点链接#开头同样跳过代码块保护processFile先用占位符替换所有 代码块只处理代码块之外的链接避免误改代码示例中的路径目录路径解析当链接以/结尾时按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 插件链rehypeInlineDiagrams将/diagrams/*.svg图片内联为 SVG 节点而非img使custom.css的样式能渗透到图内实现一套图纸深浅双主题同时根据data-i18n键从name.labels.json按页面语言替换标签文本——图纸不重画、只翻译rehypeMarkdownLinks处理.md链接的最终路由化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-2 句内说清本文目的与读者收获标题层级是否控制在##/###且全篇##数量在 8-12 个是否误用了水平分割线、####标题、Related/Next 章节或深层嵌套列表对话/命令示例是否放进了 admonition 而非代码块admonition 数量是否在预算内普通节 1-2 个、全篇 Explanation/Reference 2-3 个表格单元格与列表项是否控制在 1-2 句文档类型Tutorial / How-To / Explanation / Reference / Glossary是否选对并套用了对应模板引用的技能名bmad-*、目录结构_bmad-output/是否为仓库中的真实存在所有相对链接是否转换为以仓库根目录为起点的路径是否已运行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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考