illegalCreed

中文

English

中文

English

Appearance

参考 ​

基于 Clean Code / The Pragmatic Programmer / Staff Engineer 编写 —— 沟通场景速查 / 评审分级 / ADR 模板 / 汇报结构 / 书目要点

七大沟通场景速查 ​

场景核心原则关键产物
代码评审对事不对人、意见分级Blocking/Suggestion/Nit/Praise 标注
设计评审决策显式化、可追溯ADR / 设计文档
需求澄清明确「完成」定义AC（验收标准）
跨团队协作契约先行、边界对齐OpenAPI / 接口契约 / 对接人
向上汇报给选项 + 推荐ROI/风险/进度三段式
冲突管理数据驱动、书面化RFC / ADR + dissenting opinion
技术分享受众先行、问题贯穿演讲 + demo + 文档

代码评审意见分级 ​

级别含义示例处理
Blocking必须改「这里 SQL 拼接有注入风险」合并前必须解决
Suggestion建议改「可考虑用 map 替代 for 提升可读性」作者决定
Nit吹毛求疵「nit: 这里多了个空格」可忽略
Praise点赞「这个抽象很优雅，学到了」鼓励正向反馈
Question询问「为什么选这个库？」作者解释

建设性反馈四要素 ​

1. 观察（事实）：「第 42 行的 parseDate 在传入 null 时会抛异常」
2. 影响：「这会导致上游未校验的调用方崩溃」
3. 建议：「可以返回 null 或用 Optional 包装」
4. 提问：「是否考虑到上游可能传 null？」

评审反模式 ​

反模式问题
针对人（「你写错了」）引发防御
未分级（一堆评论不知哪些重要）作者迷茫
只挑刺不表扬打击士气
拖延评审阻塞交付
在 PR 里争论设计（应在设计阶段）PR 太大或太晚

ADR 模板 ​

markdown
# ADR-{编号}: {标题}

## 状态
{提议 | 已接受 | 已废弃 | 已替代}

## 背景
{为什么要做这个决策？现状、约束、问题}

## 决策
{我们决定什么？}

## 后果
- 正面：{收益}
- 负面：{代价、风险}
- 缓解：{如何应对负面影响}

## 备选方案（可选）
{考虑过但没选的方案，及为何不选}

放置：docs/adr/ADR-001-xxx.md，纳入版本控制，随决策更新状态。

设计文档结构 ​

1. 目标与非目标（边界）
2. 背景与上下文
3. 方案概述（含架构图）
4. 详细设计
   - 数据模型
   - API 设计
   - 关键流程（时序图）
5. 权衡分析（备选方案对比）
6. 风险与缓解
7. 里程碑与回滚

AC（验收标准）模板 ​

markdown
## 用户故事
作为 {角色}，我想 {功能}，以便 {价值}。

## 验收标准（AC）
1. {可测试条件 1}
2. {可测试条件 2}
3. {边界/异常处理}
4. {性能要求}
5. {权限/安全要求}

## 非功能要求
- 性能：P99 < 200ms
- 可用性：99.9%
- 兼容性：...

向上汇报三段式模板 ​

1. 背景 + 问题（1-2 句）
   {现状 + 痛点，附数据}

2. 选项 A / B / C
   - A: 成本 / 风险 / 收益（ROI）
   - B: 成本 / 风险 / 收益
   - C: 成本 / 风险 / 收益

3. 我的推荐 + 理由
   推荐 {X}，因为 {ROI 最高 / 风险可控 / 战略意义}
   需要你决策：{具体要什么}

状态汇报（红黄绿） ​

状态含义行动
🟢 Green正常，按计划正常同步
🟡 Yellow有风险但可控附缓解措施，盯紧
🔴 Red需帮助/升级立即升级，明确要什么支持

RFC 模板 ​

markdown
# RFC: {标题}

## 动机
{为什么要改？附数据/监控}

## 提案
{具体方案}

## 备选方案
- A: ...
- B: ...
（为何不选）

## 权衡
- 一致性 / 性能 / 复杂度 / 运维 的影响

## 开放问题
{待讨论的点}

## 时间线
{决策 / 实现 / 上线节点}

冲突降级路径 ​

1. 一对一私下沟通（留面子）
2. 数据/原型验证（事实胜于辩论）
3. RFC 书面化（结构化讨论）
4. 引入第三方仲裁（架构师/Tech Lead）
5. 决策并记录（ADR + dissenting opinion）
6. Disagree and Commit（全力执行）

异步沟通结构 ​

BLUF（结论先行） ​

【结论/请求】{一句话核心}

【背景】{为什么}
【细节】{选项/论据}
【下一步】{期望对方做什么}

金字塔原理 ​

        结论（塔尖）
       /    |    \
   论点1  论点2  论点3（中层）
   / \    / \    / \
 论据  论据 论据 论据 论据 论据（塔基）

技术分享结构 ​

1. 钩子（问题/痛点）    — 30s 引起兴趣
2. 背景（上下文）        — 让外行能懂
3. 旅程（尝试→失败→突破）— 故事弧线
4. 方案（核心做法）      — 图为主，少代码
5. 结果（数据证明）      — 量化效果
6. 教训（可迁移启示）    — 受众能带走什么
7. Q&A

受众适配表 ​

受众时长建议重点避免
同组工程师30-45min实现/权衡过度科普
跨组工程师20-30min价值/接口/影响细节实现
技术管理层10-15minROI/风险/业务影响代码
全公司分享20-30min故事/启发术语堆砌
外部技术大会30-45min通用经验/方法论内部专有

资深工程师三种模式 ​

模式定位典型沟通行为
驱动者 Driver主动发起、协调推动写 RFC、拉对齐、推落地
楷模 Role Model以身作则、树立标准高质量交付、mentoring
引导者 Facilitator帮他人成功解锁阻塞、跨团队搭桥

三本书核心思想 ​

Clean Code（Robert C. Martin） ​

思想沟通启示
命名即沟通好名字胜过注释
函数小而专注一个函数说清一件事
注释是失败代码的补丁能命名清楚就别加注释
代码写给人看机器顺便执行

The Pragmatic Programmer（Thomas & Hunt） ​

思想沟通启示
知识投资组合持续学习并分享
破碎的窗户坏沟通传染，及时修补
曳光弹用最小可用路径沟通方向
为沟通负责认错不甩锅

Staff Engineer（Will Larson） ​

思想沟通启示
资深 = 影响力影响超出自己代码
写下来文档/ADR/博客放大影响
建立信任兑现承诺、诚实汇报
大杠杆一个决策影响系统方向

参考 ​