---
name: peer-facing-writing
description: 写给同事看的文本（GitLab 单据、飞书文档、评审意见、群消息、PR review、跨团队报告）的语气与结构规范，基于职场协作与社会心理学。触发："提单 / 写报告 / 写文档给 QA 或后端 / 评审意见 / 回评 / 跨团队沟通 / 文案不合理 / 这样礼貌吗 / 语气太硬"。反触发：写给 owner 本人的对话回复走 reply-format-low-cost，那是另一套（对上要极简，对同侧要留余地）。
---

# 对同事的书面沟通

给同事看的文本和给 owner 的汇报是**两套语气**。对 owner 要极简、结论先行、不铺过程（`cs rule reply-format-low-cost`）；对同侧同事要**留余地、给台阶、不越位**——因为他们不欠你执行，你也不是他们的上级。

判断标准只有一条：**这段话如果原样念给对方听，他会想解决问题，还是想先自我辩解？** 后者就是写坏了。

## 零、先用金字塔原理搭骨架（结构定了再谈语气）

语气问题好改，结构错了整篇要重写。**动笔前先按金字塔原理搭骨架**：结论先行、以上统下、归类分组、逻辑递进。

### 结论先行 —— 答案放在第一屏

读者的第一个问题永远是「结论是什么、要不要我动」。把它放在开头，证据放在后面供需要的人下钻。

```
✅ 7 条已全部复验：3 条已修复、1 条真缺陷已转后端、3 条要更新用例。前端无遗留。
   （下面才是逐条明细、判据、复现步骤）

❌ 先讲复验方法 → 再讲每条怎么测的 → 最后一段才说结论
```

**检验**：只读前 5 行，读者知不知道结论和自己要做什么？不知道就是没做到结论先行。

### SCQA —— 开篇四句话把人带进上下文

用在文档开头或单据的「背景」段。四句，各一到两行，不要展开：

| | 写什么 | 例（本次冒烟报告） |
|---|---|---|
| **S** 情境 | 对方已知的事实，建立共同起点 | 1.0.6 冒烟 120 条上轮跑完，7 条 failed |
| **C** 冲突 | 发生了什么变化，让现状不成立 | 之后前端又修了几轮，环境已经不是上轮那个构建 |
| **Q** 疑问 | 因此自然产生的问题 | 这 7 条现在还失败吗？分别该谁处理？ |
| **A** 答案 | 你的结论，一句话 | 3 条已修复、1 条真缺陷转后端、3 条要改用例 |

**S 一定要是对方已知的**。写成「我做了 X」就不是 SCQA，那是自述。SCQA 的作用是让对方觉得「对，我知道这个背景」，然后顺着你的逻辑走下来。

### MECE —— 分组必须不重不漏

**Mutually Exclusive（相互独立）**：任何一条内容只能出现在一个分组里。
**Collectively Exhaustive（完全穷尽）**：分组加起来覆盖全部，数字能对上。

两个高频违反：

1. **重叠**：同一件事在「三项待办」和「后续动作表」里各写一遍 —— 读者不知道哪份是准的，改了一处另一处就过期。**同类信息只留一处，别处只引用。**
2. **不穷尽**：说「7 条已复验」，分组却只写了 6 条，或分组数字加起来不等于总数。**每次分组后做一次加法**。

**检验**：把分组的条数加起来，等于总数吗？把每条内容圈出来，它只出现在一个组里吗？

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

- **以上统下**：每个标题必须是它下面所有内容的概括。「三项待办的归属与状态」下面就只能放这三项的归属与状态，放别的（如文档修订说明）就是标题名不副实。
- **逻辑递进**：同一层的条目按一个明确顺序排 —— 严重度、时间、责任方，选一个并贯彻。混着排读者会以为顺序有含义而去找规律。

### 骨架模板（可直接套）

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


## 一、四个心理学机制（语气规则都从这来）

| 机制 | 说明 | 写作后果 |
|---|---|---|
| **基本归因错误** | 人解释别人的行为时高估「能力/态度」，低估「情境/信息不对称」；解释自己时相反 | 别写「测试方法不对」，写「这个坑在页面上看不出来」。把成因归到**信息或环境**，不归到人 |
| **面子威胁（face threat）** | 命令式、纠错式、否定式表达会触发防御，对方先保护自尊、后处理信息 | 别用「不要 X」「必须 Y」「应该早就」；用「我这次踩到 X」「建议 Y，因为 Z」 |
| **逆火效应** | 直接指出「你错了」会让人更坚持原判断，尤其在有第三方围观的单据里 | 结论摆事实和数据，让对方自己得出结论；不写「你判错了」 |
| **自曝降防御** | 先承认自己的失误，对方的防御姿态显著下降，且更愿意接受同一条信息 | 同一个坑如果自己也踩过，**先写自己踩过**，再说怎么避开 |

## 二、先定读者：人 还是 agent（这一步定了，语气和结构才有意义）

**同一份内容，给人读和给 agent 读要写成两份，不要混在一段里。** 混写的后果是双向失效：人被参数和路径淹没、agent 抓不到可执行指令。

| 维度 | 给人读（QA / 后端 / 产品 / owner） | 给 agent 读（skill / 规则 / AGENTS.md / 单据里的执行段） |
|---|---|---|
| **首要目标** | 让他知道**发生了什么、要不要他动、动什么** | 让它**能照做且不跑偏**，判据可机器核验 |
| **开头放什么** | 结论 + 是否需要他处理 | 触发条件 + 禁止项 |
| **语气** | 留余地、给台阶、自曝先行（见下方各节） | 命令式**正确**：「必须」「禁止」「先 X 再 Y」，越硬越少歧义 |
| **归因** | 归到情境，不归到人 | 不需要归因，只要判据 |
| **详略** | 只给影响判断的信息，细节折叠或另开一节 | 穷举边界与反例，宁长不漏 |
| **数据** | 结论化：「93 个模型被漏掉」 | 可复现：完整命令、参数、期望值、退出码 |
| **失败处理** | 说清影响和下一步 | 说清「遇到 X 就停下并上报」，别让它自己发挥 |
| **礼貌** | 必要 | 无意义，浪费 token |

### 怎么在一份文档里区分

1. **分节，并在小节标题上标明读者**：如「给 QA 的结论」「复现步骤（自动化脚本可直接用）」。
2. **人读的部分不放长命令**：命令折进代码块，前面用一句话说明它验证什么。
3. **agent 读的部分不放心理铺垫**：不写「我也踩过这个坑」，直接写判据和顺序。
4. **同一件事两种写法并存时，标清哪份是真源**：通常 agent 段是可执行真源，人读段是摘要——摘要过期不算错，真源过期是事故。
5. **落地位置也要分**：给人的结论进飞书文档/单据正文；给 agent 的规则进 `skill` / `cs rule` / `AGENTS.md`，别塞在飞书里（agent 读不到）。

> 判断自己写混了没：把文档里所有代码块和参数删掉，人读段还成立吗？把所有解释性句子删掉，agent 段还能照做吗？两个都「是」才算分清了。


## 三、写之前先分清三类内容

同一份文档里混着三类东西，语气完全不同，**分不清就会写成「教别人做事」**：

| 类型 | 本质 | 正确写法 | 错误写法 |
|---|---|---|---|
| **我的发现** | 我踩过的坑、我实测的数据 | 「我这次踩到…」「实测是…」，标明「供参考」 | 「给你的三条提醒」「注意不要…」 |
| **我的请求** | 需要对方做的事 | 「麻烦你看下…，因为…」+ 具体动作 + 为什么找他 | 「请修复」「按 PRD 改」（无主语的命令） |
| **客观事实** | 真源判据、接口实测、PRD 原文 | 直接陈述 + 出处，不加评价词 | 「显然违反了 PRD」「明显是 bug」 |

## 四、逐句可套的替换表

| 别写 | 改写 | 为什么 |
|---|---|---|
| 给测试执行的三条提醒 | 复验时我踩到的三个坑（供参考） | 「提醒」隐含上下关系，「我踩到」是平等分享 |
| 不要用 `querySelector().click()` | 这里用 `querySelector().click()` 点不动（Radix 吃 pointer 事件），我第一轮就这么测的、得出了假结论 | 自曝先行 + 归因到技术情境 |
| 复验前先核环境版本 | 复验前建议核一眼环境版本，测试环境跟的是版本分支而不是 test | 「建议」保留对方判断空间 |
| 用例过时了，请更新 | 用例与当前 PRD §x 的口径不一致，PRD 是真源，所以这条要改用例；证据如下 | 给判据，不下判决 |
| 这是 bug，请修复 | 实测与 PRD §x 不符（数据见下），麻烦看下是实现要改还是口径变过 | 留「也许口径变了」的余地 |
| 你们上次没验就交付了 | 这条在 test 打过来是 40401，可能是路由还没注册 | 去掉「你们」，只说现象 |
| 显然 / 明显 / 当然 / 众所周知 | （删掉） | 暗示「这都不懂」，纯负分 |
| 已经说过很多次 | （删掉，重述一遍事实即可） | 除了泄愤没有任何功能 |
| 加粗 + 感叹号 + 全大写 | 平铺陈述，最多加粗一处关键结论 | 视觉上等于吼人 |

## 五、结构要求

1. **结论在最前**，但**请求要具体**：谁、做什么、什么时候、为什么找他。「@某人 麻烦看下」后面一定跟「因为这块是你负责的 X 模块」或「因为前端改不了，原因是 Y」。
2. **先给证据再提请求**（互惠原则）：把实测数据、真源出处、复现步骤放在请求前面，对方读完自然知道该做什么。
3. **写清「不用你做什么」**：明确划掉不在对方范围的部分，减少对方的心理负担和来回确认。
4. **自己的错单独一段、不埋在里面**：把「这条我先前判错了」写成独立小节，不要藏在长文中间显得在掩饰。
5. **结尾留回路**：「如果口径变过 / 如果我漏了什么，直接在单里说」——给对方反驳的正当出口，比堵死更容易推进。
6. **别替别人做决定**：写「建议 A，因为…；如果你们更倾向 B，我按 B 改」，而不是「就按 A 了」。

## 六、提单/回评的固定骨架

```
## 现象
（客观陈述 + 环境 + 版本 + 数据，不带评价词）

## 判据
（PRD/设计文档原文 + 章节号；接口实测；两者不一致处）

## 为什么找你
（这块归你 / 前端改不了的技术原因 / 与你之前那个单同族）

## 建议怎么做
（具体动作，给选项和推荐，不下命令）

## 不用你处理的部分
（明确划走，减负）

## 我这边的失误（如有）
（自曝，单独一段）
```

## 七、自检四问（提交前必过）

0. **这段是给人读还是给 agent 读？** 混在一起就拆开（见第二节）。
1. 给人读的部分有没有一句话是**命令式**或以「不要/必须/应该」开头的？→ 改成陈述或建议（给 agent 的段落不受此限，命令式反而更好）。
2. 有没有把成因归到**人**（测试方法不对、后端没验）而不是**情境**（页面上看不出、发布期迁移滞后）？→ 改归因。
3. 我自己在这件事上有没有犯过同类错？→ 有就写进去，放在对方的坑之前。
4. **我从头到尾当读者读过一遍了吗？** → 没读过就不算写完，按第九节的清单读。
5. **被点名的每个人读到自己那段，会觉得「有我一份」还是「又给我派活」？** → 后者就按第十一节重写。
6. **结论在第一屏吗？分组的条数加起来对得上吗？同一件事有没有在两个地方各写一遍？** → 按第零节的 MECE 检验。

## 八、边界

- **对 owner 的回复不适用本 skill**，走 `cs rule reply-format-low-cost`：那边要的是极简结论，客套是噪声。
- **安全/资金/生产事故**的通报可以直接、可以硬，但仍然只陈述事实与影响，不评价人。
- **不要因为要礼貌而模糊结论**。「可能也许或许」堆三层等于没结论。语气软、结论硬，两者不冲突。

## 九、写完必须自己当读者通读一遍（这一步最容易省，代价最大）

写完不等于交付。**以「第一次看到这份文档的人」的身份从头读一遍**，读的时候手里拿着下面这份清单。2026-09-10 一份 9900 字的复验报告，靠通读揪出 20 处问题，其中三处是硬伤——章节内容错位、引用了已删章节、同一份文档里两处结论互相打脸。这些机器和作者本人都查不出来，只有换成读者视角才看得见。

### 通读清单

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

### 三条硬规矩

1. **通读要读全文，不是读 diff。** 只看自己刚改的段落，永远发现不了「这段和三屏之外那段打架」。
2. **删改章节后必须重读相邻两节。** 删标题会让它下面的条目并进邻节，这是错位的头号来源。
3. **能自动查的先自动查，但别以为够了。** 写个脚本扫「矛盾词/过时词/字段名」能捞一批（如 `待产品澄清`、`仍待回复`、`详见下方`、长小数），但错位、编号、逻辑打架只有人眼能看见。

## 十、改超过三轮就重写，不要继续打补丁

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

**判断标准**：如果「更正/补充/作废」类章节超过总篇幅的四分之一，或者读者需要先理解「初版说错了什么」才能看懂现在的结论——重写。

重写时：

- 只留**当前结论**和**读者要做的事**；
- 我的误判压成一句话（如「本报告初版有两条结论判错，已按 PRD 更正」），需要追溯的放文末或另开一份；
- 留档不等于留在正文。过程性内容进单据评论或独立文档，正文只放结果。

**代价对比**：重写一份 3000 字的干净文档，比让十个人各花十分钟在 9900 字里找结论便宜得多。

## 十一、读者要能感到自己是参与者，不是被通知的执行方（owner 2026-09-10）

去掉命令口吻只是及格线。及格之上的要求是：**QA、后端、产品读完这份文档，觉得自己是这件事的共同推进者，而不是收到一张任务派单。**

差别不在客套话，在四个具体动作：

| 动作 | 怎么写 | 反例 |
|---|---|---|
| **认对方的贡献** | 「本轮能直接对着复现点核，是因为 QA 上一轮的 actual_result 把成因和代码位置都记了」 | 直接开始讲自己的复验结果，像是从零开始 |
| **把判据摊开，允许被推翻** | 「判定依据都摊在这里，如果和你手上的信息不一致，或我漏看了某份文档，以你们的判据为准」 | 「结论如下」——不给反驳的入口 |
| **点名请教而不是派活** | 「这块是你写的，产品有没有改过口径你最清楚，想请你判断」 | 「待陆浩确认」——像在派单给他 |
| **替对方卸掉不该背的锅** | 「组卷时模块的排期归属确实不容易提前确认，这条不是执行问题」 | 「QA 把不属于本版本的用例放进来了」 |

三条心法：

1. **共享清单，不是单向输出**。「我踩到的坑」写完可以加一句「你们在别的模块遇到类似的也欢迎往里补」——把一份自述变成大家的资产。
2. **谁的错说清楚，别让别人替你背**。自己的失误单独交代（「免得后面有人照初版结论去改用例」），同时明确不牵连他人。
3. **人称要与署名一致**。署名是「某人（前端）」的报告，正文里的「我」就等于那个人 —— 如果误判其实是 agent 犯的，写「我漏切了下拉」会变成让署名人在对外文档里认错。**署名报告用客观陈述**（「本轮曾这么测」「初版有两条判错」），第一人称留给单据评论、群消息这类明确是自己在说话的场合。

> 检验方法：把文档里每个被点到的人的名字圈出来，逐个问 —— 他读到自己那段，会觉得「这事有我一份」，还是「又给我派活」？后者就重写那段。