Engineering Review

工程评审清单。方案评审、PR 提交前、架构决策、重构前使用;检查异常路径、组件间状态一致性、可观测性、tech debt 归属、可维护性,识别把局部最优伪装成长期方案的做法;多考虑架构与接口而不是实现。

RedGranite f5a4e51 2.2 KB Updated

File contents

engineering-review:工程师的自我审查

何时用

方案定稿前、PR 前、任何"这样改就行了"的时刻。

硬规则

  • MUST 列出异常路径:每个外部调用失败、超时、返回空、返回脏数据时系统做什么。
  • MUST 改动涉及两个以上组件时,写出改动后各组件状态及一致性保证(谁先谁后、失败一半怎么办)。
  • MUST 关键路径有可观测手段:日志、指标或可查询状态,能在生产回答"现在卡在哪"。
  • MUST 写明本次引入的 tech debt:是什么、为何现在不还、谁维护、何时还。
  • NEVER 把"当前最省事"描述成"长期可维护";两者不同时写明选了哪个及理由。
  • MUST 先定边界与契约,再谈实现。
  • NEVER 为满足评审堆分析;不适用的维度省略,仅当前提可变时写一句(见 context-legibility)。

审问清单

  1. 这个系统会不会有异常路径?每条路径的终态?
  2. 会不会有并发问题?见 concurrency-modeling。
  3. 改动完成后各个 component 状态是否一致?中途失败呢?
  4. 哪些逻辑应该复用?见 ssot-reuse。
  5. 长期迭代时应该由谁维护这些知识?写在哪?
  6. 出问题时靠什么定位?
  7. 10 倍数据 / 流量 / 团队规模下还成立吗?切换成本?
  8. 删掉这个改动,系统会更差吗?

反模式

  • 错误:定时任务同步两个系统,失败就"下次再同步"。→ 正确:写出哪边是 source of truth、冲突怎么解;失败有告警与补偿。
  • 错误:为赶 demo 把配置写死,注释"以后改"。→ 正确:写死可以,但 tech debt 条目写进记录:内容、归属、还债触发条件。
  • 错误:评审只看代码风格。→ 正确:先审边界与契约,再审实现。

输出要求

评审结论至多四段:异常路径、状态一致性、可观测性、tech debt;每段一行结论,不适用的省略。

RedGranite/smartskill/tree/main/skills/coding/engineering-review commit f5a4e51a10

Frequently asked questions

npx skillmds@latest add redgranite/engineering-review