how-to-write git:20260926.5283a19A

Immutable. This exact content never changes and is served at /api/v1/blob/9544bee8fecb81b0.

---
name: how-to-write
description: 「怎么写文字」的总纲——先按金字塔原理搭骨架（结论先行 / SCQA / MECE），再按读者定语气（人还是 agent、上级还是同侧），最后必须以新读者身份通读自检。管一切要给别人看的文字：文档、单据、报告、评审意见、讲稿、群消息、PR 描述。触发："写文档 / 写报告 / 提单 / 写评审意见 / 文案不合理 / 逻辑不清 / 这样礼貌吗 / 结论说不清 / 讲稿检查"。
---

# 怎么写文字

一切要给别人看的文字，按同一个顺序做四件事。**顺序不能换**——结构错了改字没用，语气对了但结论找不到也没用。

```
① 搭骨架   金字塔原理：结论先行 · SCQA · MECE
② 定读者   给人 or 给 agent；上级 or 同侧
③ 调语气   归因情境 · 自曝先行 · 认对方贡献 · 允许被推翻
④ 当读者   以第一次看的人的身份通读全文，带清单查错
```

跳过任何一步的代价，在文末「三个真实案例」里有实测数字。

---

## ① 搭骨架：金字塔原理

### 结论先行

读者的第一个问题永远是「结论是什么、要不要我动」。答案放第一屏，证据放后面供下钻。

**检验**：只读前五行，读者知不知道结论和自己要做什么。

### SCQA：开篇四句带上下文

| | 写什么 | 关键 |
|---|---|---|
| **S** 情境 | 对方**已知**的事实 | 必须是共识，写成「我做了 X」就变自述 |
| **C** 冲突 | 发生了什么变化让现状不成立 | 这是读者继续读下去的动力 |
| **Q** 疑问 | 因此自然产生的问题 | 通常不用写出来，但心里要有 |
| **A** 答案 | 你的结论，一句话 | 这句话就是全文的塔尖 |

### MECE：分组不重不漏

- **相互独立**：任何一条内容只出现在一个分组里。同一件事写两处，读者不知哪份准，改一处另一处立刻过期。
- **完全穷尽**：分组加起来覆盖全部。**每次分组后做一次加法**——说「7 条」却只列 6 条是最常见的翻车。

### 以上统下 + 逻辑递进

标题必须是它下面所有内容的概括；同层条目按一个明确顺序排（严重度 / 时间 / 责任方），选一个并贯彻。

---

## ② 定读者

### 给人读 vs 给 agent 读——两套写法，不要混

| 维度 | 给人 | 给 agent |
|---|---|---|
| 首要目标 | 知道发生了什么、要不要他动 | 能照做且不跑偏 |
| 开头 | 结论 + 是否需要他处理 | 触发条件 + 禁止项 |
| 语气 | 留余地、给台阶 | 命令式**正确**，越硬越少歧义 |
| 详略 | 只给影响判断的信息 | 穷举边界与反例，宁长不漏 |
| 数据 | 结论化（「93 个模型被漏掉」） | 可复现（完整命令、参数、期望值） |
| 礼貌 | 必要 | 无意义，浪费 token |

**检验**：删掉所有代码块和参数，人读段还成立吗？删掉所有解释句，agent 段还能照做吗？

### 对上 vs 对同侧

- **对上（你的老板 / owner）**：极简，结论先行，不铺过程，客套是噪声。
- **对同侧（同事 / 跨团队）**：留余地、给台阶、不越位——他们不欠你执行，你也不是他们的上级。

### 人称要与署名一致

署名是「某人」的报告，正文里的「我」就等于那个人。**如果误判其实是 agent 犯的，写「我漏看了」会变成让署名人对外认错。** 署名报告用客观陈述（「初版有两条判错」），第一人称留给单据评论、群消息这类明确是自己在说话的场合。

---

## ③ 调语气

### 四个心理学机制

| 机制 | 写作后果 |
|---|---|
| **基本归因错误**（解释别人的行为高估能力、低估情境） | 别写「测试方法不对」，写「这个坑在页面上看不出来」——归因到**信息或环境** |
| **面子威胁** | 命令式触发防御，对方先保护自尊、后处理信息。别用「不要 X」「必须 Y」 |
| **逆火效应** | 直接说「你错了」会让人更坚持，尤其在有第三方围观的单据里。摆事实让对方自己得结论 |
| **自曝降防御** | 同一个坑自己也踩过，**先写自己踩过**，对方防御姿态显著下降 |

### 让读者感到自己是参与者，不是被通知的执行方

去掉命令口吻只是及格线。及格之上是四个动作：

| 动作 | 怎么写 |
|---|---|
| **认对方的贡献** | 「本轮能直接对着复现点核，是因为 QA 上一轮把成因和代码位置都记了」 |
| **把判据摊开，允许被推翻** | 「如果结论和你手上的信息不一致，或我漏看了某份文档，以你们的判据为准」 |
| **点名请教而不是派活** | 「这块是你写的，产品有没有改过口径你最清楚，想请你判断」 |
| **替对方卸掉不该背的锅** | 「组卷时模块的排期归属确实不容易提前确认，这条不是执行问题」 |

**检验**：把每个被点名的人圈出来，逐个问——他读到自己那段，会觉得「这事有我一份」还是「又给我派活」？

### 逐句替换表

| 别写 | 改写 |
|---|---|
| 给你的三条提醒 | 我踩到的三个坑（供参考） |
| 不要用 X | 这里用 X 点不动，我第一轮就这么测的、得出了假结论 |
| 用例过时了，请更新 | 用例与 PRD §x 口径不一致，PRD 是真源，所以这条要改用例；证据如下 |
| 这是 bug，请修复 | 实测与 PRD §x 不符，麻烦看下是实现要改还是口径变过 |
| 你们上次没验就交付了 | 这条在 test 打过来是 40401，可能是路由还没注册 |
| 显然 / 明显 / 当然 / 已经说过很多次 | （删掉） |
| 加粗 + 感叹号 + 全大写 | 平铺陈述，最多加粗一处关键结论 |

---

## ④ 当读者：写完必须通读

**写完不等于交付。** 以「第一次看到这份文档的人」的身份从头读一遍，手里拿着清单。

| 查什么 | 典型症状 |
|---|---|
| 归属错位 | 某节的条目挂到了下一节（多见于删改标题后） |
| 失效引用 | 「详见下方 X」而 X 已被删或改名 |
| 前后矛盾 | 标题说「已定」正文说「待回复」；表格与正文结论不一致 |
| 编号断裂 | 1 / 某标题 / 3；或两套编号混用 |
| 数字不一致 | 同一件事数字不同；分母口径变了但旧百分比还留着 |
| 过时留存 | 已完成的仍写「待办」；已拍板的仍写「待确认」 |
| 字段堆砌 | 8 位小数、hex、下划线字段名——问一句：读者拿它能判断什么？不能就删 |
| 命令口吻 | 「不要」「必须」开头（给 agent 的段落除外） |
| 元信息过量 | 一行塞六项；文档修订史占了正文位置 |

**三条硬规矩**

1. **读全文，不是读 diff。** 只看刚改的段落，永远发现不了「这段和三屏外那段打架」。
2. **删改章节后必须重读相邻两节。** 删标题会让下面的条目并进邻节，这是错位的头号来源。
3. **能自动查的先自动查，但别以为够了。** 脚本能扫词面残留（`待确认`、`详见下方`、长小数），**错位、编号、逻辑打架只有人眼能看见**。

### 改超过三轮就重写

反复追加「更正记录」「补充说明（第二轮）」的文档会变成一份**返工日志**：读者要在你的心路历程里找结论。

**判据**：更正/补充/作废类章节超过总篇幅四分之一，或读者需要先理解「初版说错了什么」才能看懂现在的结论 → 重写。过程性内容进单据评论或独立文档，正文只放结果。

---

## 骨架模板

```
标题
├─ SCQA 四句（背景 → 变化 → 问题 → 结论）
├─ 结论（分组 MECE，条数加得上）
├─ 明细（一条一行，与结论分组对应）
├─ 待办（按责任方分组，每人只出现在自己那组）
└─ 备注/留档（过程性内容，不占正文）
```

提单/回评另有骨架：**现象 → 判据 → 为什么找你 → 建议怎么做 → 不用你处理的部分 → 我这边的失误**。

---

## 自检六问（交付前必过）

1. 结论在第一屏吗？
2. 分组条数加得上吗？同一件事有没有在两个地方各写一遍？
3. 这段给人读还是给 agent 读？混在一起就拆开。
4. 给人读的部分有没有命令式句子？
5. 被点名的每个人读到自己那段，会觉得「有我一份」还是「又给我派活」？
6. **我从头到尾当读者读过一遍了吗？** 没读过就不算写完。

---

## 三个真实案例（都是代价换来的）

**案例一：不通读的代价。** 一份 9918 字的技术复验报告，写完直接发。事后以新读者身份通读，揪出 20 处问题，其中三处硬伤：某节内容错位挂到了下一节、引用了已被删掉的章节、同一份文档里两处结论互相打脸。**19 处是通读才发现的，脚本只扫出 1 类词面残留。**

**案例二：不做 MECE 的代价。** 同一份报告里，7 条用例每条散在 3–4 个章节，「三项待办」和「后续动作表」互相重叠。读者不知道哪份是准的，改一处另一处立刻过期。重写后每条只在「结论概览」和「逐条明细」出现两处（以上统下的正常层级），后续动作表整个删掉。

**案例三：人称与署名不一致的代价。** 报告署名是团队里的人，正文却写「我误判了」「我漏切了下拉」——而那些误判是 agent 犯的。等于让署名人在一份对外文档里认错。改成客观陈述后，「我」只保留在主动请对方推翻自己的句子里（「如果我漏看了某份文档，以你们的判据为准」）——那是示弱和邀请，不是认错。

---

## 相关 skill 与原子矩阵

- `platform-voices`：全平台表达风格与媒介心智分册（网易云情怀/小红书生活/X极客/GitHub客观/公众号长文）
- `scenario-openers`：场景接待词、破冰与去 AI 味真实表达规范（消除机器假人味，真人声腔与开场钩子）
- `atomic-matrix`：[5D 原子表达组合矩阵速查](../atomic-matrix.md)（角色 × 平台 × 场景 × 口吻 × 开场白自由拼装）
- `peer-facing-writing`：对同事书面沟通的完整版（提单骨架、逐句替换表、边界）
- `talk-text-review`：讲稿姿态验收——这份稿子是「我教你们」还是「我跟你们聊」
- `talk-visual-review`：讲稿视觉验收