企业官网建设流程全解析

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 的核心理念：教程面向"学习"，使用指南面向"任务"，概念解释面向"理解"，参考文档面向"查阅"。写作时先判断页面属于哪一类，再决定该放多少机制细节。

项目级规则表：全局格式红线

规范用一张规则表明确了全站统一的格式约束，贡献者应逐条对照：

其中"标题预算"与站点的目录配置相印证：docs-site/astro.config.mjs 中将tableOfContents设置为{ minHeadingLevel: 2, maxHeadingLevel: 3 }，即右侧"本页目录"只呈现##和###两级，这正是不允许使用####的原因之一——四级标题既无法进入目录，也会破坏扫描节奏。

提示框（Admonitions）：Starlight 语法与标准用途

提示框是本项目文档的主要强调手段，语法由 Starlight 提供（@astrojs/starlight依赖见 docs-site/package.json）。完整语法如下：

:::tip[标题] 快捷键、最佳实践 ::: :::note[标题] 上下文、定义、示例、前置条件 ::: :::caution[标题] 注意事项、潜在问题 ::: :::danger[标题] 仅用于严重警告——数据丢失、安全问题 :::

四种提示框有约定的标准用途，避免随意混用：

在实际文档中可以观察到这些用法。例如 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 You've 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）面向"理解"，规范先定义了四种类型：

通用模板：

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）面向"查阅"，同样按类型区分：

参考索引页：

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 代理活动的多步骤引导式流程。 |

定义规则：

上下文标记：对适用范围有限的术语，在定义开头添加斜体上下文：

• *仅限直接进入式实施。*
• *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.js）；
• npm 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