---
name: doc-organization
description: 撰写或审阅技术文档时，处理结构、信息归属、重复结论和缺少上下文的问题。仅检查 Markdown 标记与排版用 markdown-style。
allowed-tools: Read, Glob, Grep, AskUserQuestion
---

# 文档信息组织

**管信息落在文档的哪个位置，不管表达文笔。**

这里只有五条原则，没有判据、没有阈值、没有严重级。审阅文档时按这五条**判断**，并明确说明这是判断而非检测——内容组织的问题无法机械判定。

**本 skill 只判断与说明，不执行修改。** 若据此改文档，改动限于三类：搬位置、补定义、删重复副本；任何需要重写句子才能达成的"改进"都不属于本文范围。

## Language

- 接受中英文提问，统一中文回复，文档用中文

---

## 1. 正文只写当前状态，变更历史另置

**危害不是难读，是当前状态失去确定性。**

历史与当前混在同一处时，读者无法判断哪一句是活的。一份文档的引言里放两条修订记录、而正文还留着被它们推翻的旧说法，等于对"当前设计是什么"给出了两个答案。

**怎么做**：变更理由归入变更记录 / ADR 章节，正文引言只留当前结论。

**两条别做**：

- 不要把变更理由集中搬到文末——那是把理由从它解释的对象旁边移走，制造另一种碎片化。正确落法是合并进覆盖这些内容的那一节，或已有的决策记录条目
- 不要指望 git 承担这件事——"为什么否决了初版方案"这类推理，从 diff 里读不出来

**一条修订影响多个章节时**：保留一个完整、原子的决策记录条目，放在覆盖这些章节的共同上层或明确的主责位置；各受影响章节只写本节后果并单跳引用。不要每节复制一份摘要（会各自漂移），也不要把因果链拆散到几节。

## 2. 编号先定义，再使用

给一个东西编号之后，首次出现时就说明它指什么；或者干脆不用编号，直接描述。

最典型的失败是**被否决的东西留下了名字却没留下所指**：文档里反复出现"已删除""已作废""曾采用的那个方案"，带着编号，而那个编号从未被定义——读者永远不知道它原本是什么。

**为什么这条只能在写的时候守住**：事后没人能补这个定义，AI 更不能——它无从得知那个编号指什么，补任何一个都是在猜事实。写的时候一句话的事，写完就是永久缺口。

## 3. 引言是"要不要读下去"的判断依据

不是内容摘要的堆放处。引言给结论与范围，细节下沉到对应章节。

**一个反直觉的提醒**：判断"太密"时不要把表格和列表当散文。一大张结构化表格是**好的**内容组织——可扫读、可定位；同样字数的散文才是病。收紧引言时只看散文部分。

## 4. 同一结论只在一处定义

同一个结论散布在多个文件里，改一次就要同步多处，且必然有漏。定一处为出处，其他地方引用。

**但这不是禁令。** 复述有时是有意的：测试用例引用需求原文是为了本地可读、运行手册要离线自包含。本条的要求是**知道自己在付什么代价**，而不是一律去重。

改成引用也不是免费的——它会把一处自包含的声明变成对另一份文件的动态依赖，可能丢失本地语境。是否去重需要判断，不要机械执行。

## 5. 写给缺少你现在上下文的人

这是"黑话"的根源。写的人当时全知全能，所以看不出哪些词需要解释——一段几百字的引言里塞十个未定义的标识符、内部简称、章节交叉引用，写的时候毫无察觉。

**AI 每次都是"当时全知"的那一方，所以这个问题在 AI 写作中会系统性恶化。** 没有任何环节会让写的人自己发现——审阅者往往也刚从同一段上下文里出来。

**怎么做**：写完问一句——没有今天这段对话的人，读这段能懂吗。

---

## 边界

- **`markdown-style`** 管"用什么标记"（标题层级、代码块语言、中英文空格、全角标点），本 skill 管"信息放哪里"。列表嵌套过深、列表仅含一项属于标记用法，归 `markdown-style`
- **`code-quality`** 管代码，本 skill 管文档
- 本 skill 不管表达文笔——句子是否拗口、术语密度高低、是否"读起来舒服"，都需要重写句子才能改善，超出边界