分类型文档规范

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

解决的问题

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

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

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

三步

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

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

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

类型表

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

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

跨类型硬规则

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

1. 开篇第一屏只回答五件事：这是什么；为什么值得读；范围（做什么、不做什么）；读者是谁、需要先读什么；什么情况下不必读。五件事之外的内容一律后移，包括术语表、相邻文档的分工、方法论的来龙去脉。第一屏不得出现只在本文后半段才定义的词。
2. 结论先行。每一节的第一句给出这一节的结论或动作，依据、推导、例外放后面。标题层级不超过三层。
3. 一篇只有一个一级标题，文件里第一个标题就是正标题。不设「概述」「简介」「前言」这类前置章节。
4. 「不做什么」与「为什么没选别的」必须写。只列被选中的方案、不提被否决的方案，视为文档未完成。被否决的方案要写清代价与不选的理由，只写一句「不合适」不算写。
5. 状态只有一个字段，取值来自一个固定集合——提议 / 已批准 / 已落地 / 已否决 / 已被取代，放头部。区分「已批准」与「已落地」：标「已落地」的必须附一条可执行的确认方式（跑哪条命令、看哪个文件、grep 哪个字符串），给不出来就只能标「已批准」。已批准的记录不改写；要变就新开一条，新条写 supersedes、旧条写 superseded by，两头都写全。被否掉的文档不删，要写拒绝理由。这个取值集合管的是头部状态字段。机制说明、计划、复盘正文里的「已落地 / 蓝图 / 已否决」是节内分级标签，不是头部状态字段，用词也固定在这三个里，不另造「规划中」「进行中」这类说法。自带模板或 schema 的面（case / reference 词条、EV 卡、面板文案）以各自的模板或 schema 为准，见 references/repo-anchors.md §2。
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 字；一段建议 50–200 字，硬上限 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. 最后才过词句层。

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

校对与审阅：改动范围由任务定

先认任务，再动手。四种任务能改的东西不一样，别把校对做成改写：

• 写（新文档）：套骨架，见上面「三步」。
• 改写（结构或表达重做）：保留事实、逻辑关系与信息层级；默认交付完整改写稿，重大语义选择另说一句。
• 校对（只清句子与格式）：只改错字、标点、留白、大小写与术语一致性。未经要求，不动结构、语气与事实表达。
• 审阅（只出意见）：先列问题再给建议，按影响程度排序并引原文；未经授权不改文件。

判不准时按范围小的那个做，交付时说明还能往哪一步走。

与别的规范怎么分工