title: "文档风格指南"
本项目遵循 Google 开发者文档风格指南 并使用 Diataxis 来构建内容。仅项目特定约定如下。
项目特定规则
| 规则 | 说明 |
|---|---|
无水平分隔线 (---) | 打断阅读流 |
无 #### 标题 | 改用粗体文本或警告框 |
| 无“相关”或“下一篇：”部分 | 侧边栏处理导航 |
| 无深度嵌套列表 | 改为拆分成章节 |
| 非代码内容不用代码块 | 使用警告框展示对话示例 |
| 标注不用粗体段落 | 改用警告框 |
| 每章节最多 1-2 个警告框 | 教程允许每个主要部分 3-4 个 |
| 表格单元格 / 列表项 | 最多 1-2 句话 |
| 标题预算 | 每个文档 8-12 个 ##；每章节 2-3 个 ### |
警告框 (Starlight 语法)
md
:::tip[标题]
快捷方式、最佳实践
:::
:::note[标题]
上下文、定义、示例、先决条件
:::
:::caution[标题]
注意事项、潜在问题
:::
:::danger[标题]
仅限严重警告 — 数据丢失、安全问题
:::标准用法
| 警告框 | 用于 |
|---|---|
:::note[Prerequisites] | 开始前的依赖项 |
:::tip[Quick Path] | 文档顶部的简要总结 |
:::caution[Important] | 关键注意事项 |
:::note[Example] | 命令/响应示例 |
标准表格格式
阶段：
md
| Phase | Name | What Happens |
| ----- | -------- | -------------------------------------------- |
| 1 | Analysis | Brainstorm, research *(optional)* |
| 2 | Planning | Requirements — PRD or tech-spec *(required)* |命令：
md
| Command | Agent | Purpose |
| ------------ | ------- | ------------------------------------ |
| `brainstorm` | Analyst | Brainstorm a new project |
| `prd` | PM | Create Product Requirements Document |文件夹结构块
在“您已完成的内容”部分显示：
md
```
your-project/
├── _bmad/ # BMad configuration
├── _bmad-output/
├── PRD.md # Your requirements document
│ └── bmm-workflow-status.yaml # Progress tracking
└── ...
```教程结构
text
1. 标题 +以此吸引读者 (1-2 句话描述结果)
2. 版本/模块通知 (信息或警告框) (可选)
3. 您将学到什么 (结果的项目符号列表)
4. 先决条件 (信息警告框)
5. 快速路径 (提示警告框 - 简要总结)
6. 理解 [主题] (步骤前的上下文 - 阶段/代理表格)
7. 安装 (可选)
8. 步骤 1: [第一个主要任务]
9. 步骤 2: [第二个主要任务]
10. 步骤 3: [第三个主要任务]
11. 您已完成的内容 (总结 + 文件夹结构)
12. 快速参考 (命令表)
13. 常见问题 (FAQ 格式)
14. 获取帮助 (社区链接)
15. 关键要点 (提示警告框)教程检查清单
- [ ] 钩子用 1-2 句话描述结果
- [ ] 存在“您将学到什么”章节
- [ ] 警告框中的先决条件
- [ ] 顶部的快速路径 TL;DR 警告框
- [ ] 阶段、命令、代理的表格
- [ ] 存在“您已完成的内容”章节
- [ ] 存在快速参考表
- [ ] 存在常见问题章节
- [ ] 存在获取帮助章节
- [ ] 结尾处的关键要点警告框
操作指南结构
text
1. 标题 + 钩子 (一句话: "Use the `X` workflow to...")
2. 何时使用 (场景的 বুলেট列表)
3. 何时跳过 (可选)
4. 先决条件 (注意警告框)
5. 步骤 (编号的 ### 子章节)
6. 您得到什么 (产生的输出/工件)
7. 示例 (可选)
8. 提示 (可选)
9. 下一步 (可选)操作指南检查清单
- [ ] 钩子以 "Use the
Xworkflow to..." 开头 - [ ] “何时使用”有 3-5 个要点
- [ ] 列出先决条件
- [ ] 步骤是用
###子章节编号，带有动作动词 - [ ] “您得到什么”描述输出工件
解释结构
类型
| 类型 | 示例 |
|---|---|
| 索引/着陆页 | core-concepts/index.md |
| 概念 | what-are-agents.md |
| 功能 | quick-flow.md |
| 理念 | why-solutioning-matters.md |
| FAQ | brownfield-faq.md |
通用模板
text
1. 标题 + 钩子 (1-2 句话)
2. 概览/定义 (它是什么，为什么重要)
3. 关键概念 (### 子章节)
4. 对比表 (可选)
5. 何时使用 / 何时不使用 (可选)
6. 图表 (可选 - mermaid，每文档最多 1 个)
7. 下一步 (可选)索引/着陆页
text
1. 标题 + 钩子 (一句话)
2. 内容表 (带有描述的链接)
3. 开始使用 (编号列表)
4. 选择您的路径 (可选 - 决策树)概念解释
text
1. 标题 + 钩子 (它是什么)
2. 类型/类别 (### 子章节) (可选)
3. 关键差异表
4. 组件/部分
5. 您应该使用哪个？
6. 创建/自定义 (指向操作指南)功能解释
text
1. 标题 + 钩子 (它做什么)
2. 快速事实 (可选 - "Perfect for:", "Time to:")
3. 何时使用 / 何时不使用
4. 它如何工作 (mermaid 图可选)
5. 关键优势
6. 对比表 (可选)
7. 何时毕业/升级 (可选)理念/理由文档
text
1. 标题 + 钩子 (原则)
2. 问题
3. 解决方案
4. 关键原则 (### 子章节)
5. 优势
6. 适用情况解释检查清单
- [ ] 钩子说明文档解释的内容
- [ ] 内容在可扫描的
##章节中 - [ ] 3+ 选项的对比表
- [ ] 图表有清晰的标签
- [ ] 指向操作指南的链接，用于程序性问题
- [ ] 每个文档最多 2-3 个警告框
参考结构
类型
| 类型 | 示例 |
|---|---|
| 索引/着陆页 | workflows/index.md |
| 目录 | agents/index.md |
| 深入 | document-project.md |
| 配置 | core-tasks.md |
| 术语表 | glossary/index.md |
| 综合 | bmgd-workflows.md |
参考索引页
text
1. 标题 + 钩子 (一句话)
2. 内容章节 (每个类别的 ##)
- 带链接和描述的 বুলেট列表目录参考
text
1. 标题 + 钩子
2. 项目 (每个项目的 ##)
- 简短描述 (一句话)
- **Commands:** 或 **Key Info:** 作为扁平列表
3. 通用/共享 (## 章节) (可选)项目深入参考
text
1. 标题 + 钩子 (一句话目的)
2. 快速事实 (可选注意警告框)
- 模块、命令、输入、输出作为列表
3. 目的/概览 (## 章节)
4. 如何调用 (代码块)
5. 关键章节 (每个方面的 ##)
- 使用 ### 作为子选项
6. 说明/注意事项 (提示或小心警告框)配置参考
text
1. 标题 + 钩子
2. 目录 (如果 4+ 个项目跳转链接)
3. 项目 (每个配置/任务的 ##)
- **粗体总结** — 一句话
- **Use it when:** bullet list
- **How it works:** numbered steps (3-5 max)
- **Output:** expected result (optional)综合参考指南
text
1. 标题 + 钩子
2. 概览 (## 章节)
- 显示组织的图表或表格
3. 主要章节 (每个阶段/类别的 ##)
- 项目 (每个项目的 ###)
- 标准化字段：Command, Agent, Input, Output, Description
4. 下一步 (可选)参考检查清单
- [ ] 钩子说明文档参考的内容
- [ ] 结构匹配参考类型
- [ ] 项目贯穿始终使用一致的结构
- [ ] 结构化/比较数据的表格
- [ ] 链接到解释文档以获得概念深度
- [ ] 最多 1-2 个警告框
术语表结构
Starlight 从标题生成右侧的“本页内容”导航：
- 类别作为
##标题 — 出现在右侧导航中 - 表格中的术语 — 紧凑的行，而不是单独的标题
- 无内联 TOC — 右侧栏处理导航
表格格式
md
## 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. |定义规则
| Do | Don't |
|---|---|
| Start with what it IS or DOES | Start with "This is..." or "A [term] is..." |
| Keep to 1-2 sentences | Write multi-paragraph explanations |
| Bold term name in cell | Use plain text for terms |
上下文标记
在定义开始处添加斜体上下文，用于有限范围的术语：
*Quick Flow only.**BMad Method/Enterprise.**Phase N.**BMGD.**Brownfield.*
术语表检查清单
- [ ] 表格中的术语，而不是单独的标题
- [ ] 类别内的术语按字母顺序排列
- [ ] 定义 1-2 句话
- [ ] 上下文标记斜体
- [ ] 单元格中的术语名称加粗
- [ ] 没有“A [term] is...”定义
FAQ 章节
md
## 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 BMad Method and Enterprise tracks. Quick Flow skips to implementation.
### Can I change my plan later?
Yes. The SM agent has a `correct-course` workflow for handling scope changes.
**Have a question not answered here?** [[[[[Open an issue]]]]](...) or ask in [[[[[Discord]]]]](...).验证命令
在提交文档更改之前：
bash
npm run docs:fix-links # Preview link format fixes
npm run docs:fix-links -- --write # Apply fixes
npm run docs:validate-links # Check links exist
npm run docs:build # Verify no build errors