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 开发者文档风格为语言基准、以 Diataxis 框架组织内容结构适用于该项目的全部文档页面——包括教程、使用指南、概念解释、参考文档与术语表。读者读完本文后将掌握 BMad Method 文档站点的完整写作约定、Starlight 提示框语法、六类文档的结构模板与自检清单以及提交前可执行的链接与构建校验命令。这份规范管什么一份多语言风格指南的定位docs/ko-kr/_STYLE_GUIDE.md是 BMad Method 文档站点的韩文风格指南与之对应的是英文原版 docs/_STYLE_GUIDE.md。规范本身遵循两条外部基准Google 开发者文档风格指南作为语言与表达基准与 Diataxis作为内容组织框架而文档内只收录项目自身特有的补充规则。从仓库结构看这套规范服务于一个多语言、多类型的文档体系多语言站点docs-site/src/lib/locales.mjs 定义了 6 种 locale——英语root无 URL 前缀、韩语ko-kr、越南语vi-vn、简体中文zh-cn、法语fr、捷克语cs每种语言下都维护一套explanation/、how-to/、reference/、tutorials/目录结构技术栈docs-site/package.json 显示文档站点基于 Astro Starlight 构建依赖astrojs/starlight提示框、右侧导航、本页目录等能力均由 Starlight 提供内容分类文档被划分为教程tutorials、使用指南how-to、概念解释explanation、参考文档reference、术语表glossary等类型每种类型有独立的结构模板。因此这份风格指南是项目内容质量的总闸门无论贡献者写哪种语言、哪种类型的页面都必须遵守同一套结构与表达约定。写作基本原则让核心信息易于查找、可直接行动规范首先提出适用于所有页面的写作原则韩文版表述为쉬운 한국어로 쓰기即用平易的韩语写作其他语言版本同理在文档开头明确说明页面用途以及读者需要从中获得什么使用具体、熟悉的词汇和短句只使用使用 BMad 所必需的术语陌生术语在首次出现时给出定义使用字面语言避免装饰性比喻不用比喻代替对机制的解释先给出要点再补充限定条件与细节机制只有当实现细节有助于读者理解页面目的或采取行动时才写入精确的机制与契约放在参考文档或链接的深入资料中删除重复内容、拖慢要点的开头、夸张的主张以及不会影响读者决策的保留性说明。这套原则直接呼应 Diataxis 的核心理念教程面向学习使用指南面向任务概念解释面向理解参考文档面向查阅。写作时先判断页面属于哪一类再决定该放多少机制细节。项目级规则表全局格式红线规范用一张规则表明确了全站统一的格式约束贡献者应逐条对照规则规范禁止使用水平分隔线---会打断阅读流程禁止使用####标题改用粗体或提示框禁止相关条目或下一步小节导航由侧边栏负责禁止深度嵌套的列表改用小节拆分非代码内容禁止使用代码块对话示例使用提示框禁止用粗体段落做提示改用提示框每个小节最多 1-2 个提示框教程允许每个大节 3-4 个表格单元格 / 列表项最多 1-2 句标题预算每篇文档##8-12 个每个小节###2-3 个其中标题预算与站点的目录配置相印证docs-site/astro.config.mjs 中将tableOfContents设置为{ minHeadingLevel: 2, maxHeadingLevel: 3 }即右侧本页目录只呈现##和###两级这正是不允许使用####的原因之一——四级标题既无法进入目录也会破坏扫描节奏。提示框AdmonitionsStarlight 语法与标准用途提示框是本项目文档的主要强调手段语法由 Starlight 提供astrojs/starlight依赖见 docs-site/package.json。完整语法如下:::tip[标题] 快捷键、最佳实践 ::: :::note[标题] 上下文、定义、示例、前置条件 ::: :::caution[标题] 注意事项、潜在问题 ::: :::danger[标题] 仅用于严重警告——数据丢失、安全问题 :::四种提示框有约定的标准用途避免随意混用提示框用途:::note[前置条件]开始前需要的依赖:::tip[快速路径]文档顶部的简短摘要:::caution[重要]重要的注意事项:::note[示例]命令/响应示例在实际文档中可以观察到这些用法。例如 docs/ko-kr/tutorials/getting-deeper.md 顶部用:::note[필수 조건]前置条件列出 Git、Node.js、uv 等环境要求docs/ko-kr/how-to/customize-bmad.md 用:::tip推荐bmad-customize技能、用:::caution警告不要整份复制customize.toml。标准表格格式阶段表与技能表规范定义了两种出现频率最高的表格范式确保全站表格视觉与语义一致。阶段表用于流程类页面| 步骤 | 名称 | 内容 | | --- | --- | --- | | 1 | 分析 | 头脑风暴、调研 *(可选)* | | 2 | 规划 | 需求——PRD 或规格 *(必需)* |技能表用于列出技能与对应代理| 技能 | 代理 | 目的 | | --- | --- | --- | | bmad-brainstorming | 分析师 | 新项目头脑风暴 | | bmad-prd | PM | 生成产品需求文档 |这两类表格在项目文档中大量出现——教程用阶段表呈现流程、用技能表呈现技能—代理—目的的映射参考文档的目录页也用同样结构组织条目。文件夹结构块展示交付物布局在你完成了什么What Youve Accomplished类小节中规范要求用树状代码块展示项目最终产出的目录结构 your-project/ ├── _bmad/ # BMad 配置 ├── _bmad-output/ │ ├── planning-artifacts/ │ │ └── PRD.md # 需求文档 │ ├── implementation-artifacts/ │ └── project-context.md # 实施规则 (可选) └── ... 这种写法让读者在教程结尾能直观确认自己做出了什么、文件落在哪里。_bmad/与_bmad-output/是 BMad 安装与运行产生的标准目录约定可在 docs/ko-kr/tutorials/getting-deeper.md 的实操中看到例如规格输出到_bmad-output/specs/spec-diffsettings-audit/。教程结构15 步标准骨架教程Tutorial面向从零开始的学习者规范给出了固定骨架1. 标题钩子句用 1-2 句说明成果 2. 版本/模块说明info 或 warning 提示框可选 3. 你将学到什么以成果为导向的列表 4. 前置条件info 提示框 5. 快速路径tip 提示框——TL;DR 摘要 6. 理解[主题]步骤前的上下文——用表格呈现阶段/代理 7. 安装可选 8. 步骤 1[第一个主要任务] 9. 步骤 2[第二个主要任务] 10. 步骤 3[第三个主要任务] 11. 你完成了什么摘要文件夹结构 12. 快速参考技能表 13. 常见问题FAQ 格式 14. 获取帮助社区链接 15. 核心要点tip 提示框对应的教程检查清单钩子句用 1-2 句说明成果有你将学到什么小节前置条件放在提示框中顶部有快速路径 TL;DR 提示框用表格呈现步骤、技能、代理有你完成了什么小节有快速参考表有常见问题小节有获取帮助小节末尾有核心要点提示框仓库中的韩文教程 docs/ko-kr/tutorials/getting-deeper.md 即按此骨架组织以在 Django 5.2.4 上为diffsettings命令扩展 JSON 输出为钩子句随后依次给出前置条件提示框、12 个编号步骤小节1. 精确检出 Django 版本到12. 继续构建、每步的 Bash 命令与预期输出步骤间穿插:::note[필수 조건]等提示框完全符合模板要求。使用指南结构面向任务的分步流程使用指南How-To解决在特定场景下如何完成任务1. 标题钩子句一句话使用 X 工作流来…… 2. 何时使用3-5 个要点列表 3. 何时跳过可选 4. 前置条件note 提示框 5. 步骤编号的 ### 子小节 6. 你得到什么产出/生成的工件 7. 示例可选 8. 提示可选 9. 下一步可选使用指南检查清单钩子句以使用X工作流来……开头何时使用有 3-5 个要点列出了前置条件步骤是动作动词开头的编号###子小节你得到什么描述输出工件docs/ko-kr/how-to/customize-bmad.md 是典型范例钩子句直接说明保持更新兼容性的同时定制代理与工作流随后是何时使用要点列表、前置条件提示框、四个编号步骤小节查找可定制范围、创建覆盖文件、定制所需条目、个人 vs 团队以及合并如何工作工作流定制集中配置等深层机制小节。概念解释结构按文档类型细分的模板概念解释Explanation面向理解规范先定义了四种类型类型示例索引/落地页core-concepts/index.md概念what-are-agents.md功能build.md哲学why-solutioning-matters.md通用模板1. 标题钩子句1-2 句 2. 概述/定义它是什么、为什么重要 3. 核心概念### 子小节 4. 对比表可选 5. 何时使用 / 何时不使用可选 6. 图示可选——mermaid每篇文档最多 1 个 7. 下一步可选索引/落地页1. 标题钩子句一句话 2. 内容表带说明的链接 3. 开始使用编号列表 4. 路径选择可选——决策树概念解释文档1. 标题钩子句它是什么 2. 类型/分类### 子小节可选 3. 主要差异表 4. 组成部分 5. 应该用哪个 6. 创建/定制链接到使用指南功能说明文档1. 标题钩子句它做什么 2. 快速信息可选——适合用于耗时 3. 何时使用 / 何时不使用 4. 工作方式图示可选 5. 核心优势 6. 对比表可选 7. 何时升级/毕业可选哲学/原理文档1. 标题钩子句原则 2. 问题 3. 解决方案 4. 核心原则### 子小节 5. 优势 6. 何时适用概念解释检查清单钩子句说明文档解释的内容内容组织成易于扫描的##小节有 3 个以上选项时使用对比表图示有清晰标签程序性问题给出使用指南链接每篇文档提示框最多 2-3 个项目中的概念解释文档如 docs/ko-kr/explanation/why-solutioning-matters.md哲学类即采用问题—解决方案—核心原则的骨架。参考文档结构目录、编目与深层条目参考文档Reference面向查阅同样按类型区分类型示例索引/落地页workflows/index.md编目agents/index.md深层说明document-project.md配置core-tasks.md术语表glossary/index.md综合指南bmgd-workflows.md参考索引页1. 标题钩子句一句话 2. 内容小节每个类别一个 ## - 带链接和说明的列表编目参考1. 标题钩子句 2. 条目每个条目一个 ## - 简短说明一句 - **技能** 或 **核心信息** 形式的平铺列表 3. 通用/共享小节## 小节可选条目深层参考1. 标题钩子句一句话目的 2. 快速信息note 提示框可选 - 模块、技能、输入、输出列表 3. 目的/概述## 小节 4. 如何调用代码块 5. 核心小节每个方面一个 ## - 子选项用 ### 6. 备注/注意事项tip 或 caution 提示框配置参考1. 标题钩子句 2. 目录条目 4 个以上时使用跳转链接 3. 条目每个配置/任务一个 ## - **粗体摘要** —— 一句话 - **何时使用** 要点列表 - **工作方式** 编号列表最多 3-5 个 - **输出** 预期结果可选综合参考指南1. 标题钩子句 2. 概述## 小节 - 展示组织的图示或表格 3. 主要小节每个阶段/类别一个 ## - 条目每个条目一个 ### - 标准字段技能、代理、输入、输出、说明 4. 下一步可选参考文档检查清单钩子句说明文档引用什么内容结构符合参考类型条目整体结构一致结构化/对比数据使用表格需要概念深度处链接概念解释文档提示框最多 1-2 个术语表结构表格化定义与上下文标记术语表有专门的约定。Starlight 会从标题自动生成右侧本页目录因此分类使用##标题会出现在右侧导航术语写在表格的紧凑行里而不是独立标题不使用内联 TOC右侧侧边栏承担导航职责。表格格式## 分类名称 | 术语 | 定义 | | --- | --- | | **代理** | 拥有特定专长、在工作流中引导用户的专业化 AI 人格。 | | **工作流** | 为产出交付物而编排 AI 代理活动的多步骤引导式流程。 |定义规则应该做不应该做以它是什么或它做什么开头以这是一个……或该术语是……开头控制在 1-2 句写成多段解释单元格内的术语名加粗术语用纯文本上下文标记对适用范围有限的术语在定义开头添加斜体上下文*仅限直接进入式实施。**BMad Method/企业版。**第 N 阶段。**BMGD。**既有项目。*术语表检查清单术语放在表格而非独立标题中分类内按字母排序定义 1-2 句上下文标记为斜体单元格内术语名加粗不使用这是一个……式定义FAQ 小节锚点导航与快捷回答FAQ 以问题即锚点的方式组织既便于跳转也便于维护## 问题 - [我总是需要架构吗](#我总是需要架构吗) - [我以后能改变计划吗](#我以后能改变计划吗) ### 我总是需要架构吗只有能从架构受益的工作才需要。范围明确的工作可以直接进入实施。 ### 我以后能改变计划吗可以。bmad-correct-course 工作流处理实施中途的范围变更。 **这里没有回答你的问题吗** 开一个 issue 或在社区中提问。注意 FAQ 中的锚点由 Starlight 根据标题自动生成中文/韩文标题的 slug 化规则见 docs-site/scripts/validate-doc-links.js 中的headingToAnchor实现——小写化、去 emoji、去特殊字符、空格转连字符。提交前的验证命令链接与构建质量门禁规范要求所有文档变更在提交前执行一组验证命令cd docs-site npm run fix-links # 预览链接格式修复 npm run fix-links -- --write # 应用修复 npm run validate-links # 检查链接是否存在 npm run build # 确认无构建错误这些命令与 docs-site/package.json 中的 scripts 一一对应底层实现可以在源码中直接查验npm run fix-links→node scripts/fix-doc-links.js。docs-site/scripts/fix-doc-links.js 将 Markdown 相对链接转换为以仓库根为起点的/docs/...路径如./file.md→/docs/当前路径/file.md、../other/file.md→/docs/解析后路径/file.md并跳过外部链接、纯锚点链接与非.md资源代码块中的链接会被占位符保护、不会被改动。不带参数运行时为 dry-run 预览模式加--write才实际写入文件npm run validate-links→node scripts/validate-doc-links.js。docs-site/scripts/validate-doc-links.js 校验站内相对链接是否指向存在的.md文件同时校验#锚点是否指向目标文件中的真实标题对能唯一定位的破损链接给出[FIX]自动修复建议多候选时给出[REVIEW]清单npm run build→node scripts/build-docs.mjs验证整个 Astro/Starlight 站点能否无错构建。除了风格指南列出的四条命令docs-site/package.json 还提供了配套的质量门禁可作为持续校验的补充npm run locale-coverage校验各语言文档的覆盖一致性对应 docs-site/scripts/validate-locale-coverage.mjs 与 docs-site/locale-coverage-baseline.json 基线npm run validate-sidebar校验侧边栏条目顺序对应 docs-site/scripts/validate-sidebar-order.jsnpm run test运行站点级测试套件URL、rehype 插件、重定向、locale 覆盖等。由于 docs-site/scripts/fix-doc-links.js 会跳过下划线开头的目录与文件见getMarkdownFiles中的entry.name.startsWith(_)判断风格指南文件本身不会被链接修复脚本改动这也解释了为何_STYLE_GUIDE.md可以作为全站约定长期稳定存在。从规范到站点风格约定如何被强制执行这份风格指南并非孤立文本它与站点构建管线深度耦合形成写作约定构建强制的双层保障标题层级tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 3 }docs-site/astro.config.mjs强制右侧目录只呈现两级标题呼应##8-12 个、###每节 2-3 个的标题预算链接规范文档中的链接在构建时经 rehype 插件rehypeMarkdownLinks、rehypeBasePaths见 docs-site/astro.config.mjs转换为站点路径配合fix-links/validate-links脚本保证仓库内链接与站点链接一致可用多语言一致性6 种 locale 由 docs-site/src/lib/locales.mjs 统一声明locale-coverage校验各语言文档树是否对齐——这也是为什么每种语言目录下都存在结构相同的_STYLE_GUIDE.md内容结构Starlight 的侧边栏配置见 docs-site/astro.config.mjs 中sidebar部分按 Start、Build、Plan Larger Work、Existing Codebases、Customize and Extend、Reference 分组承接了导航由侧边栏负责、不写相关条目小节的约定。结语一份可执行的文档质量协议docs/ko-kr/_STYLE_GUIDE.md是一份高度可执行的文档写作协议它以 Google 风格与 Diataxis 为理论底座用项目级规则表划出格式红线用提示框语法统一强调手段用六类结构模板教程、使用指南、概念解释、参考文档、术语表、FAQ固化每种页面的骨架再用fix-links、validate-links、build等命令把约定落到提交前的可验证流程。对于希望为 BMad Method 贡献文档的开发者或是在自己团队中建立多语言、多类型文档体系的团队这份规范连同 docs-site/ 下的脚本与测试实现构成了一套可以直接复用的完整参考。【免费下载链接】BMAD-METHODBreakthrough Method for Agile Ai Driven Development项目地址: https://gitcode.com/gh_mirrors/bm/BMAD-METHOD创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

BMad Method 文档写作规范指南：Google 风格与 Diataxis 驱动的多语言文档体系建设

相关推荐

从能播放到稳定交付：全链路媒体系统的稳定性设计实践

TP钱包浏览器插件版安装与使用全指南：Chrome、Brave、Edge配置及安全实践

数据分析最反直觉的真相：你缺的不是统计知识，是一个“敢问”的入口

更多资讯

SAP SD定价过程详解：从条件类型到存取顺序的配置与排错

从Word结构到自动评分：Python解析中文版NOS量表docx实践

用JUnit 5构建可修改的Java基础题库：从参数化测试到动态加载

SDK、API、Library别再搞混：从概念到报错排查一篇讲透

Altium Designer 2024安装教程：系统配置、组件选择与故障排查指南

Apache Spark SQL Pipe Syntax 完全指南：使用 `|＞` 链式组合查询操作符

今日更新

校园网认证计费模式详解：AAA与代拨架构、原理及排障

Spring Boot+Vue垃圾分类毕设：分层、权限与排错实战

把 Cline 的 Base URL 改到 TaoToken 之后，DeepSeek 仍能修调试配置

本周精选

AI驱动的自动化专利分析平台技术解析

LeetCode-Go 题解：1252. Cells with Odd Values in a Matrix（奇数值单元格计数）双解法剖析

在线答疑系统Java毕设实战：Spring Boot前后端分离与状态流转

本月热门

基于YOLO的焊缝缺陷检测：从数据标注到工业部署全流程实践

分布式服务的决策记录

创业产品的首版范围

读完文章，想聊聊您的网站？