webkubor/writing-standard-skills/peer-facing-writing

对同事的书面沟通

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

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

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

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

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

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

✅ 7 条已全部复验：3 条已修复、1 条真缺陷已转后端、3 条要更新用例。前端无遗留。
   （下面才是逐条明细、判据、复现步骤）
 
❌ 先讲复验方法 → 再讲每条怎么测的 → 最后一段才说结论

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

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

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

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

MECE —— 分组必须不重不漏

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

两个高频违反：

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

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

以上统下 + 逻辑递进

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

骨架模板（可直接套）

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

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

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

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

怎么在一份文档里区分

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

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

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

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

四、逐句可套的替换表

五、结构要求

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

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

## 现象
（客观陈述 + 环境 + 版本 + 数据，不带评价词）
 
## 判据
（PRD/设计文档原文 + 章节号；接口实测；两者不一致处）
 
## 为什么找你
（这块归你 / 前端改不了的技术原因 / 与你之前那个单同族）
 
## 建议怎么做
（具体动作，给选项和推荐，不下命令）
 
## 不用你处理的部分
（明确划走，减负）
 
## 我这边的失误（如有）
（自曝，单独一段）

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

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

八、边界

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

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

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

通读清单

三条硬规矩

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

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

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

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

重写时：

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

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

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

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

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

三条心法：

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

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