doc-standards git:20261008.0c86d61A

Immutable. This exact content never changes and is served at /api/v1/blob/15cd0d34b283bffa.

---
name: doc-standards
description: >
  写或改任何给人读的文档之前，先定类型、再套骨架、最后过反例清单。覆盖 docs/ 六层、
  README、定位报告、case/reference 词条、EV 卡、postmortem、PR body、skill 正文。给出九类
  文档的固定小节与顺序、跨类型硬规则、状态标注、图与外部讨论的摆放位置，并分清哪几条能写成
  检查、哪几条只能人审。用户要写新文档、重写一篇结构散掉的文档、或问「这篇文档该怎么组织 /
  该有哪些节」时使用。
---

# 分类型文档规范

> `docs/spec/writing-norms.md` 管**词句层**：一句话怎么说、哪个词不能用。本规范管**篇章层**：这是哪类文档、该有哪些节、按什么顺序、多长、图放哪、状态怎么标。两篇互指，不互为副本。
> 本仓的层名、路径与已有的机械门在 `references/repo-anchors.md`，换项目只改那一份。

## 解决的问题

同一层的两篇文档，一篇把结论放在开头，一篇把结论埋在第五节；一篇写了「不做什么」，一篇没写；已落地、蓝图、已否决三种状态混在同一节里，读者读不出哪个是真的。

三处代价一起出现：读者每读一篇都要重新判断哪节才是结论；作者每动笔都要重新发明一次大纲；评审只能说「读起来累」，说不出该改哪里。

这里给的是结构契约。类型定了，骨架就定了，谁写都一样。

## 三步

**第一步，定类型。** 到下面的类型表里找一行。判不准时问两件事：读者是在**学**还是在**做**（学 → 导览、机制说明；做 → 操作指南、计划）；这份内容让人**理解**什么，还是让人**据以判断**（理解 → 导览、机制说明、复盘；判断 → 规范条文、决策记录、提案）。

**第二步，套骨架。** 到 `references/type-catalog.md` 找那一类，照它列的小节顺序写。列出来的小节一个不落、顺序不改；某一节确实没有内容，就写一句「无」并说明为什么没有，不要删节——读者分不清「没有」和「忘了写」。

**第三步，过反例清单。** 提交前对着 `references/anti-patterns.md` 逐条自查。那份清单里的每条都是这个仓库真实出现过的写法，不是通用文风建议。

## 类型表

| 类型 | 读者读完能做什么 | 本仓写点 |
|---|---|---|
| 导览 | 知道这套系统在做什么，接下来该读哪篇 | `docs/README.md`、`docs/demo-walkthrough.md` |
| 规范条文 | 判断某个设计或改动合不合规 | `docs/spec/` |
| 机制说明 | 说清某个机制怎么运作，边界在哪 | `docs/mechanism/` |
| 操作指南 | 按步骤把某件事做出来 | `docs/guide/` |
| 计划 | 知道下一步做什么，什么时候算做完 | `docs/plan/` |
| 决策记录 | 知道当初为什么这样选，还能不能推翻 | `docs/adr/` |
| 提案 | 判断这个改动该不该做，代价是什么 | `proposals/` |
| 复盘 | 知道一次事件里发生了什么，下次怎么避免 | `postmortems/`、`traces/*.report.md` |
| 参考词条 | 查到一条事实、一个字段、一条命令 | `knowledge/`、`references/` |

一篇文档只装一件事。装不下就拆成两篇，在各自开篇互相链出。

类型名不跨规范搬运：同一个词在别的社区可能指别的东西（`Tutorial` 在 Diátaxis 是新手课，在 Kubernetes 是端到端走查）。引入一个新类型名之前先写判据——读者当时是在学还是在做、内容作用于理解还是判断、颗粒度是一篇还是一节——判据写在 `references/type-catalog.md` 开头的三条约定里。

## 跨类型硬规则

下面九条不问类型，任何一篇都成立。

1. **开篇第一屏只回答五件事**：这是什么；为什么值得读；范围（做什么、不做什么）；读者是谁、需要先读什么；什么情况下不必读。五件事之外的内容一律后移，包括术语表、相邻文档的分工、方法论的来龙去脉。第一屏不得出现只在本文后半段才定义的词。
2. **结论先行**。每一节的第一句给出这一节的结论或动作，依据、推导、例外放后面。标题层级不超过三层。
3. **一篇只有一个一级标题**，文件里第一个标题就是正标题。不设「概述」「简介」「前言」这类前置章节。
4. **「不做什么」与「为什么没选别的」必须写**。只列被选中的方案、不提被否决的方案，视为文档未完成。被否决的方案要写清代价与不选的理由，只写一句「不合适」不算写。
5. **状态只有一个字段，取值来自一个固定集合**——提议 / 已批准 / 已落地 / 已否决 / 已被取代，放头部。区分「已批准」与「已落地」：标「已落地」的必须附一条可执行的确认方式（跑哪条命令、看哪个文件、grep 哪个字符串），给不出来就只能标「已批准」。已批准的记录不改写；要变就新开一条，新条写 supersedes、旧条写 superseded by，两头都写全。被否掉的文档不删，要写拒绝理由。
6. **一个概念一个词**，全篇一致，别同义轮换。术语在首次出现处给一句定义，之后靠链接回那一处。补一句适用范围：不解释读者读不懂，解释多了读者读不动；首次出现的密度没有权威数值，遇到术语密集的段落优先把这节拆开，而不是往上加解释。
7. **图只在两三句话说不清关系时用**。图要能脱离正文读懂：标题写明图的类型与范围，有图例，每个元素给类型与一句职责，关系线写清传什么、调什么。图后跟一段说明，正文不复述图里的每一格。用 Mermaid 写进 Markdown，改动能在 PR 里逐行 diff。
8. **外部讨论单独成节，放文末**。与别的项目、别的论文、别的做法对比属于这一节。凡是读者不读也不影响理解本文设计的内容，一律不许出现在前文。
9. **篇幅不设字数上限**，换成结构性约束：一段一个主题，段落不超过六句；一节不超七个小节；每节末尾的「继续读」不超五条。

## 冲突先后

两条规则撞上时按这个顺序裁决，取高的那个，不做折中，并在评审说明里写一句取了哪个：

1. **事实与可核查性**：编号、命令、数字、报错原文、枚举值不得为了行文好看而改写或删除——这四类是 `docs/spec/writing-norms.md` §2 的有意保留项。
2. **项目已定约定**，见 `references/repo-anchors.md` 第 4 节。
3. **本规范的骨架与顺序**。
4. **语气与节奏**。

## 能写成检查的，与只能人审的

先分清两件事：能不能写成检查，和该不该进 CI。

能写成检查的（本仓自写 Python 即可，不必引 Node 或 Go；目前都还没有脚本）：一个一级标题、标题不跳级、文件末恰好一个换行、行尾无空格、代码块标语言、头部状态字段取值合法、骨架小节齐备且顺序正确、文档内相对链接与锚点存在、段落句数、每节出边条数、同一个概念只有一种写法（靠一份词表）、句长与段落长度。
阈值取的是中文语料的经验值（一句 100 字、一段 250 字；来源见 `references/rule-sources.md`），要收紧就收紧，但**必须标明是本仓自定**，不要写成引用了谁。**外链不要拦**——外链可达性天然不稳，Kubernetes 一类大项目直接关掉了这道检查。

写不成检查的：开篇是否只回答了那五件事、结论是否先行、「不做什么」与否决理由是否写到了点上、术语是否真说清了、论断是否都有出处、同一件事是否只有一个来源、篇幅与读者的时间是否相称。这几条是判断，进 CI 只会产生人要不断绕过的告警。

接入这些检查时按三档推进，不要一次全开：先加零争议的格式项（末行换行、行尾空格、代码块标语言），再加配置项（单 h1、标题不跳级、状态枚举、骨架齐备），最后才是要维护词表的项（术语写法唯一、句长）——最后两项先以只报告跑一个周期。误报怎么处置、存量文档第一次接入怎么办、哪些结论不许交给工具，口径在 `docs/spec/writing-norms.md` §5，本节不重复。

进 CI 还要过本仓三条准入（机械可查、后果确定、复发过两次）。目前本规范里没有一条已经满足三条——缺的都是复发证据，要用 git 历史与 postmortem 补。缺证据之前，上面那些检查最多以只报告的方式跑，不进阻断路径。本仓已有哪几道门、各管什么，见 `references/repo-anchors.md` 第 5 节。

## 改一篇已有的文档，按这个顺序

1. 先判类型。类型判错的文档，改词句救不回来。
2. 只看小节骨架：缺哪节、哪节顺序反了、哪节混装了两件事。先动结构，别动句子。
3. 重排开篇：按那五件事过一遍，把读者此时还读不懂的术语移到首次需要它的地方。
4. 把外部讨论、蓝图、已否决内容挑出来——该单独成节的成节，该删的删。
5. 最后才过词句层。

结构没重排完就开始改句子，是把力气花在会返工的地方。

## 与别的规范怎么分工

| 问题 | 去哪查 |
|---|---|
| 这句话怎么写、这个词能不能用 | `docs/spec/writing-norms.md` |
| 这篇该有哪些节、按什么顺序 | 本规范 + `references/type-catalog.md` |
| 这个面该不该有自己的一套写法 | `docs/spec/writing-norms.md` §4 的三问 |
| 某条规则能不能进 CI | 本规范上一节 + `docs/spec/writing-norms.md` §5 |
| 本仓某个路径对应哪一类 | `references/repo-anchors.md` |
| 这条规则是从哪来的、将来该重查谁 | `references/rule-sources.md` |