把决策与事故变成不含机密的作品集

一句话总结

ADR 保留做出决策时的上下文、备选方案、选择和结果；事故报告记录实际影响、时间线、根本原因、检测过程，以及有负责人的纠正措施。作品集不复制这些原始材料，只发布获准公开的摘要。

概念图: 获准公开的摘要 · 寻找责任人的文档 · 时间线要包含时区，并区分三个时刻。 · “为什么 40 分钟内都没有发现”

为什么仅凭代码无法解释判断

ON CONFLICT 语句能说明选择了什么，却无法解释为何选择数据库边界，而不是仅由客户端去重。六个月后看到这段代码的人会做两件事中的一件：因为不知道理由而原样保留，或因为不知道理由而删除。两者都不好。

ADR(Architecture Decision Record) 会记录当时的约束、比较过的方案，以及预期成本。格式越短越好。

# ADR-014: 중복 제거를 DB 제약으로 옮긴다

- 상태: 채택 (2026-03-11)
- 맥락: 결제 웹훅이 재시도로 같은 이벤트를 최대 3번 보낸다. 클라이언트 쪽
  메모리 캐시로 걸렀는데 파드가 늘면서 캐시가 나뉘어 중복이 새기 시작했다.
- 대안:
  1. Redis 분산 락 — 새 의존성이 생기고, 락 해제 실패 시 결제가 멈춘다.
  2. 애플리케이션 조회 후 삽입 — 조회와 삽입 사이에 경쟁이 남는다.
  3. unique 제약 + ON CONFLICT DO NOTHING — 경쟁이 DB 안에서 끝난다.
- 결정: 3안. 멱등 키를 (provider, event_id) 로 두고 유니크 인덱스를 건다.
- 결과: 중복 결제 0건. 대신 삽입 지연이 p99 기준 4ms 늘었다.
- 되돌리는 조건: 삽입 지연이 p99 20ms 를 넘으면 재검토한다.

有“回滚条件”的 ADR 和没有这一条件的 ADR 是不同的文档。有条件，就能在以后测量并作出判断；没有条件，决定就会永久保留。

如何让事故报告成为学习记录

事故发生后，应通过事故报告回顾设计假设是否符合实际。它不应是寻找责任人的文档，而应是用于构建下一道系统安全措施的学习记录。为保持这一性质，需要几项约束。

时间线要包含时区，并区分三个时刻。

时刻	含义	数值较大说明什么
开始	用户影响开始的时间	—
检测	人员发现问题的时间	可观测性不足
恢复	影响结束的时间	响应流程缓慢

如果用了 40 分钟才检测到问题，那么无论根本原因是什么，**“为什么 40 分钟内都没有发现”**都应成为独立的纠正项。事故中有一半的改进来自这里。

根本原因应指向条件，而不是人。 不要写“某人部署了错误配置”，而应写“错误配置到达部署阶段的路径中缺少验证”。前一句无法阻止下一次事故，后一句可以。

纠正措施不能只是“以后注意”，而应包含负责人、期限和可验证的完成条件。

- [ ] values 스키마 검증을 CI 에 추가 (담당: 배포팀, 기한: 3/25)
      완료 조건: 잘못된 replicas 값을 넣은 PR 이 CI 에서 떨어지는 것을 확인
- [ ] 에러율 경보를 백엔드별로 분리 (담당: 관측팀, 기한: 3/20)
      완료 조건: 한 대만 죽였을 때 5분 안에 경보가 울리는 것을 확인

如何在实际工作中制作公开证据

招聘作品集中不要放入原始 Authorization 头、令牌、密码、私有 IP、内部 .svc.cluster.local 地址，或完整终端输出。事故报告原文可能包含客户名称和营收影响，ADR 也可能暴露内部系统结构。

应只挑选获准公开的证据发布。

不应放入的内容	替代内容
完整的 `curl -H "Authorization: Bearer ey..."`	“6 项 HTTP 行为测试通过”
`10.0.3.12`, `db.internal.svc`	“三层架构，数据库位于私有子网”
“A 公司支付中断 12 分钟，营收损失 3200 万韩元”	“支付路径中断 12 分钟，影响规模不公开”
粘贴完整日志	指标名称列表和一张图表

固定模式版本并拒绝未知字段，防止后续工具误把原始秘密加入其中。

{"schema": "labhub.portfolio/v1",
 "evidence": [
   {"kind": "test", "name": "http-contract", "passed": 6, "failed": 0},
   {"kind": "image", "claim": "non-root, digest-pinned"},
   {"kind": "adr", "id": "ADR-014", "one_line": "중복 제거를 DB 제약으로 옮김"},
   {"kind": "incident", "id": "INC-2026-03", "one_line": "설정 검증 부재로 12분 중단"}
 ]}

用 additionalProperties: false 锁定模式后，只要有人为了方便添加 raw_log 字段，验证就会失败。让工具拦截，而不是依赖人的注意力。

实务判断标准

优秀的作品集展示的不是华丽截图，而是可复现的契约和判断能力。面试中真正会问的也是这些。

测试了哪些失败反例——只测试成功路径不算完整测试。
如何划分数据边界和权限边界——为什么在那里划线，才是设计。
从故障中改变了什么——止步于原因分析的报告只完成了一半。
是否预先定义回滚条件——具备这一点，说明懂得如何管理决策。

本课程最后的测验将确认实现、运维与文档证据能否串联成一个完整故事。