入门
基于 Clean Code / The Pragmatic Programmer / Staff Engineer 编写（2026.07 版本）
速查
- 沟通本质：让正确的信息、在正确的时间、以正确的形式、到达正确的人
- 代码评审沟通：对事不对人、建设性反馈、区分阻塞（blocking）与非阻塞（nits）意见
- 评审反馈分级：Blocking（必须改）/ Suggestion（建议）/ Nit（吹毛求疵，可忽略）/ Praise（点赞好的实践）
- 设计评审：用 **ADR（Architecture Decision Record）**或设计文档把决策显式化、可追溯
- 需求澄清：签订 AC（Acceptance Criteria，验收标准），明确「做完」的定义
- 跨团队协作：定义接口契约、划分边界、对齐依赖、设对接人
- 向上汇报三段式：ROI（收益）+ 风险 + 进度，给选项 + 推荐而非抛问题
- 冲突管理：数据驱动而非立场对抗，用 RFC/ADR 把分歧结构化讨论
- 异步沟通：结论先行（BLUF）、结构化表达、写清上下文
- 技术分享：受众先行、一个问题贯穿、代码 demo 而非 PPT 念字
- 三本核心书：Clean Code（命名即沟通）/ The Pragmatic Programmer（隐喻的力量）/ Staff Engineer（影响超出代码）
- 资深分水岭：技术深度决定解决多难的问题，沟通广度决定调动多少人解决更大的问题
- 资深工程师的沟通角色：驱动者（Driver）/ 楷模（Role Model）/ 引导者（Facilitator）
软件工程的沟通本质
软件工程是沟通密集型工作。研究显示工程师大量时间花在评审、设计、会议、文档，真正写代码的时间占比不高。沟通决定杠杆：
| 能力层级 | 关注点 | 沟通特征 |
|---|---|---|
| 初级 | 把功能做出来 | 听清需求，问对问题 |
| 中级 | 把模块设计好 | 写清设计文档，评审有效 |
| 高级 | 把系统/团队推动起来 | 跨团队协调，影响决策 |
| Staff+ | 做大杠杆的事 | 愿景沟通，影响组织方向 |
沟通是资深分水岭
技术深度决定你能解决多难的问题；沟通广度决定你能调动多少人来解决更大的问题。只会写代码的工程师有天花板，能把方案讲清楚、把人协调起来、把决策推动落地的工程师没有天花板。
代码评审沟通
核心原则：对事不对人
评审评论针对代码与决策，不针对人：
| ❌ 针对人 | ✅ 针对代码 |
|---|---|
| 「你这里写错了」 | 「这行在 X 情况下会返回 null，建议加判空」 |
| 「为什么这么乱」 | 「这个函数承担了 3 个职责，可否拆分以提高可测性」 |
| 「这不对」 | 「这与我们在 module Y 的约定不一致，参考 [链接]」 |
用「我们」「这个」「建议」而非「你」「错了」——降低防御性反应。
建设性反馈四要素
- 观察（事实）：指出具体代码位置与行为
- 影响：说明可能后果（bug 风险、可维护性、性能）
- 建议：给出可操作的改进方向
- 提问：用提问确认理解（「是否考虑到 X？」）比断言更易接受
评审意见分级（关键）
| 级别 | 含义 | 处理 |
|---|---|---|
| Blocking | 必须改（bug、安全问题、破坏性变更） | 合并前必须解决 |
| Suggestion | 建议改（更好实践、可读性） | 作者决定，鼓励采纳 |
| Nit（nits） | 吹毛求疵（拼写、格式细节） | 可忽略，注明 nit |
| Praise | 点赞好的实践 | 鼓励正向反馈，建立信任 |
未分级的评审是灾难——作者不知道哪些必须改、哪些可忽略，导致要么过度修改拖慢，要么忽略关键问题。每条评论应显式标明级别。
提 PR 的沟通
- PR 描述写清：做了什么、为什么、如何测试、影响范围
- 复杂 PR 附设计说明或链接 ADR
- 标注需要重点看的部分（「这块状态机改动需重点评审」）
- 小 PR：一次一个关注点，评审更高效
设计评审与 ADR
为什么需要设计评审
- 避免「写完才发现方向错」的最贵返工
- 让关键决策多人把关，减少盲区
- 决策可追溯——三个月后知道「为什么这么定」
ADR（Architecture Decision Record）
ADR 是轻量级的设计决策记录，一个文件一个决策：
markdown
# ADR-042: 使用 PostgreSQL 而非 MongoDB 作为主存储
## 状态
已接受（2026-07-15）
## 背景
订单系统需要强一致性事务，当前 MongoDB 文档模型在跨文档事务上性能不佳。
团队已有 PostgreSQL 运维经验。
## 决策
采用 PostgreSQL 14 作为主存储，MongoDB 保留给日志类非结构化数据。
## 后果
- 正面：强一致性事务、成熟运维、SQL 生态
- 负面：关系模式对半结构化数据不如 Mongo 灵活；需 ORM
- 缓解：用 JSONB 字段处理半结构化数据ADR 四要素：状态 / 背景 / 决策 / 后果。放在仓库 docs/adr/ 目录，纳入版本控制，随决策演进更新状态（提议→接受→废弃→替代）。
设计文档（更长篇）
复杂系统用完整设计文档，结构：
- 目标与非目标（明确边界）
- 背景与上下文
- 方案概述（含图）
- 详细设计（数据模型、API、关键流程）
- 权衡分析（备选方案 + 为何不选）
- 风险与缓解
- 里程碑
需求澄清与 AC
为什么要澄清
「做完了才发现不是想要的」是最贵的返工。澄清发生在编码前，成本最低。
AC（Acceptance Criteria，验收标准）
明确「做完」的定义，可测试、可验收：
用户故事：作为运营，我想导出订单报表，以便做月度结算。
AC：
1. 可按日期范围（起止）筛选订单
2. 导出 CSV，含字段：订单号、金额、状态、时间
3. 单次导出上限 10 万行，超过提示分批
4. 导出任务异步执行，完成后邮件通知
5. 权限：仅「运营」角色可见AC 签订后，开发、产品、测试三方对「完成」有共识，避免后期扯皮。
澄清的好问题
- 「这个功能的触发场景是什么？」（理解动机）
- 「如果不做这个，会发生什么？」（判断真实优先级）
- 「成功的度量指标是什么？」（对齐效果预期）
- 「有没有参考的实现？」（对齐风格预期）
- 「边界与异常情况？」（穷尽场景）
下一步
入门到此——你已经理解沟通的本质、掌握代码评审的建设性反馈与分级、会用 ADR 沉淀设计决策、能签订 AC 澄清需求。下一章 guide-line.md 深入讲 跨团队协作 / 向上汇报三段式 / 冲突管理与 RFC / 异步沟通进阶 / 技术分享演讲 / 资深工程师的沟通角色 / Clean Code·Pragmatic·Staff Engineer 核心思想落地。