架构决策记录(ADR)

在 LabHub 中继续学习

一句话总结

**为什么当时做出这个选择，比选择了什么更重要。**这是前提变化后能够重新审视决策的唯一方法。

分层图: 为什么当时做出这个选择，比选择了什么更重要。 · 谁都不敢碰 · 随意修改 · 交换条件（trade-off）

为什么需要它

六个月后，有人会问：“这里为什么没用 NAT，而用了 endpoint？”没有人记得，于是会发生两种情况之一。

谁都不敢碰——不知道原因，所以害怕。陈旧的决定原样保留下来。
随意修改——不知道原因，所以以为根本没有原因。随后同一个问题再次发生。

两种情况都很糟糕。真正需要记录的是“当时知道什么，又拿什么作了交换”。

它如何工作

一份 ADR 的结构

一个文件、一页内容就足够。

# ADR-014: 프라이빗 서브넷의 S3 접근에 게이트웨이 엔드포인트 사용

- 상태: 채택
- 날짜: 2026-08-20
- 관련: ADR-009(VPC 설계)

## 맥락
로그 적재로 S3 트래픽이 월 8TB. 현재 전량이 NAT 를 경유해
NAT 데이터 처리 요금이 월 비용의 31% 를 차지한다.

## 선택지
1. 현행 유지 — 변경 없음, 비용 유지
2. 게이트웨이 엔드포인트 — 요금 없음, 라우팅 테이블 변경 필요
3. 로그를 리전 밖 수집기로 전송 — 리전 간 요금 발생

## 결정
2번. 게이트웨이 엔드포인트를 추가하고 프라이빗 라우팅 테이블에 경로를 넣는다.

## 근거
- 엔드포인트 자체 요금이 없어 절감액이 그대로 남는다(월 약 240만 원 추정)
- 인터넷을 경유하지 않아 보안상으로도 낫다
- 엔드포인트 정책으로 우리 계정 버킷만 허용해 반출 경로를 좁힌다

## 맞바꾼 것
- 라우팅 테이블이 하나 더 복잡해진다
- 엔드포인트 정책을 잘못 쓰면 접근이 막힌다 → 스테이징에서 먼저 검증

## 언제 다시 볼 것인가
- S3 외 서비스 트래픽이 커지면(인터페이스형 엔드포인트 검토)
- 멀티 리전으로 가면 전체 재검토

两个尤其重要的章节

交换条件（trade-off）——没有这一节，文档就只是一篇宣传稿。每个决定都有放弃的东西；只有写下来，日后才能说明“不是不知道，而是在知情的情况下作出了选择”。

何时重新审视——每项决定都有生效条件。提前写明条件何时失效，可以减少陈旧决定永久留存的情况。

哪些事情应记录为 ADR

没有必要记录全部事项，标准是回退成本高的决定。

应记录：VPC CIDR、Region 选择、托管还是自建、数据存储选择、认证方式、是否采用多 Region
无需记录：调整实例类型、更改日志保留期限、修改告警阈值

放在哪里

放在代码仓库内（docs/adr/）。放在 wiki 中会与代码脱节，最终无人查看。放在仓库中，变更会通过 PR 接受 review，也会与代码一起保留版本。

实际工作中的表现

“不知道为什么这样做，但感觉不能动” → 没有 ADR。
三年前的决定一直保留 → 没有人检查前提是否已经改变。
每年重复同一场争论 → 没有记录结论。

如何用数字记录成本决策

如果 ADR 只写“更便宜”，六个月后就无法验证。写下三个数值，文档才可验证。

## 대안 비교 (월 기준, 2026-09 단가)

| 안 | 고정비 | 변동비 | 예상 총액 | 손익분기 |
|---|---|---|---|---|
| A. m6i.2xlarge 온디맨드 ×3 | $0 | $0.384/h ×3 | $840 | — |
| B. 1년 예약 ×3 | 선납 $2,900 | $0.242/h ×3 | $530 | 8개월 |
| C. Fargate (평균 40% 사용) | $0 | $0.049/vCPU·h | $610 | — |

## 가정
- 평균 vCPU 사용률 40%, 피크 85% (지난 90일 CloudWatch)
- 트래픽 연 20% 증가
- 인스턴스 타입을 1년 안에 바꾸지 않는다   ← 이 가정이 깨지면 B 는 손해

## 결정: B
## 되돌리는 조건: 사용률이 3개월 연속 25% 아래이거나, 타입 변경이 필요해지면 재검토

关键是单独写出假设。结论日后可能错误，但只要记录了假设，就能知道“什么发生了变化，导致结论失效”。没有假设的 ADR，六个月后会变成谁也不敢碰的文档。

何时重新审视这个决定

越来越多团队会在 ADR 中写明到期日，例如写下“2027-03 重新审视”，再加入日历。否则，三年前的决定会一直保留，而期间价格、服务和流量早已全部改变。

重新审视时应检查三件事。

假设是否仍然成立——利用率、流量和单价。
替代方案是否增加——云平台每年都会推出新实例和计费方案。
实际成本与预估相差多少——这一差异会提高下一次估算的准确度。

第三项最有价值。持续积累预估与实际的对比记录，团队的估算能力才会真正提高。

课程结束语

在云上，架构决策就是成本决策，成本决策也就是业务决策。能够用数字说明，会议就会缩短；把依据记录下来，后来者就不必重走同一条路。