설계 문서 완전 가이드: 결정을 남기는 문서와 사라지는 문서

들어가며
1. 언제 문서를 쓰고 언제 쓰지 않는가
2. 문서 유형 네 가지와 고르는 기준
3. 설계 문서의 표준 섹션과 각 섹션이 실제로 하는 일
- 3-1. 머리말에 반드시 넣을 네 줄
4. Non-Goals와 Alternatives Considered — 가장 자주 비어 있는 두 칸
5. 리뷰를 운영하는 법
6. 결정에는 유통기한이 있다 — ADR 상태 전이
- 6-1. 재검토 조건을 결정과 함께 적는다
- 6-2. 4-2절과의 연결
7. 문서가 낡는 문제와 대응
8. 문서가 실패하는 방식들
퀴즈: 실력을 확인해 보세요
마치며
참고 자료
이어서 읽기

들어가며

설계 문서는 결국 두 종류로 갈립니다. 6개월 뒤에 누군가 "이거 왜 이렇게 만들었지?"라고 물었을 때 답이 되는 문서와, 그때쯤이면 아무도 링크를 찾지 못하는 문서입니다. 둘의 차이는 문장력이 아닙니다. 무엇을 기록했느냐, 그리고 그 기록이 조직의 어느 지점에 꽂혀 있느냐의 차이입니다.

이 블로그에는 이미 글로 설득하기 — 디자인 문서와 RFC가 통과되는 구조와 엔지니어의 쓰는 능력이 있습니다. 두 글은 수사와 통과를 다룹니다. 어떻게 써야 읽히고, 어떻게 해야 문서가 승인되는가. 이 글은 그 앞과 뒤를 다룹니다. 문서를 글이 아니라 팀의 의사결정 인프라로 놓고, 언제 어떤 형식을 쓰는지, 리뷰를 어떤 절차로 굴리는지, 내려진 결정이 어떻게 만료되는지, 그리고 문서가 어떤 방식으로 실패하는지를 정리합니다. 목표는 잘 쓰인 문서가 아니라 결정을 남기는 문서입니다.

기준점은 구글의 「Design Docs at Google」입니다. 이 글에서 정의를 인용하되, 실무에서 자주 비는 칸과 자주 무너지는 절차 쪽에 무게를 둡니다.

1. 언제 문서를 쓰고 언제 쓰지 않는가

「Design Docs at Google」은 설계 문서를 코딩 전에 쓰는 비공식 문서로 정의하면서, 담아야 할 것을 "높은 수준의 구현 전략과 핵심 설계 결정, 그중에서도 트레이드오프에 방점을 둔 것"이라고 설명합니다. 같은 글은 엔지니어의 일이 "코드를 생산하는 것 자체가 아니라 문제를 푸는 것"이라고 말합니다. 이 두 문장을 붙이면 판별 기준이 나옵니다. 트레이드오프가 없으면 문서도 없습니다.

1-1. 쓰지 않아도 되는 경우

해법이 명백하고 의미 있는 트레이드오프가 없을 때. 원문이 직접 지목하는 생략 조건입니다.
문서가 사실상 구현 매뉴얼이 될 때. 코드를 그대로 산문으로 옮긴 문서는 리뷰어에게 판단할 거리를 주지 않습니다. 그럴 바에는 코드를 쓰는 편이 빠릅니다.
되돌리는 비용이 한 사람의 반나절인 변경. 실험해 보고 아니면 지우는 쪽이 싸게 먹힙니다.

1-2. 써야 하는 경우 — 다섯 가지 판별 질문

질문	예라면 문서가 필요한 이유
되돌리는 비용이 사람·주 단위인가	되돌릴 수 없는 결정은 결정 시점에 근거를 남겨야 감사 가능
두 팀 이상이 이 결정에 묶이는가	합의 지점이 없으면 각 팀이 다른 가정 위에서 개발
합리적인 대안이 둘 이상인가	선택의 근거가 없으면 6개월 뒤 같은 논쟁 반복
데이터 모델이나 외부 계약이 바뀌는가	이행 절차 자체가 설계 대상
보안·프라이버시·규제 판단이 들어가는가	판단 주체와 시점 기록이 필수

두 개 이상 해당하면 문서를 씁니다. 하나만 해당하면 1-pager로 충분한 경우가 많습니다. 하나도 해당하지 않으면 코드부터 씁니다.

1-3. 자주 틀리는 지점

문서 여부를 규모로 판단하는 조직이 많습니다. "3주 이상 걸리는 작업은 설계 문서 필수" 같은 규칙입니다. 규모는 대리 지표일 뿐입니다. 3주짜리 반복 작업에는 문서가 필요 없고, 반나절짜리 저장 포맷 변경에는 필요합니다. 기준은 되돌림 비용과 대안의 존재입니다.

2. 문서 유형 네 가지와 고르는 기준

같은 "설계 문서"라는 말이 네 가지 다른 물건을 가리킵니다. 셋을 섞어 쓰면 문서가 아무 일도 하지 않습니다.

목적: 해법이 아니라 문제의 존재와 우선순위에 합의
분량: 한 페이지. 배경, 증상, 영향 범위, 하지 않았을 때의 비용, 다음 단계
수명: 며칠에서 몇 주. 설계 문서로 승격되거나 폐기됨
실패 모드: 해법을 미리 적어 넣어 문제 정의 논의가 건너뛰어짐

2-2. 설계 문서 — 구현 전략과 트레이드오프

목적: 어떻게 만들 것인가에 대한 합의. 원문이 말하는 "구현 전략과 핵심 설계 결정"
분량: 보통 몇 페이지. 시스템 규모에 비례하지 않고 불확실성에 비례
수명: 구현 기간. 끝나면 대개 동결됨
실패 모드: 대안 분석 없이 결론만 있는 문서

2-3. ADR — 결정 하나를 불변 기록으로

목적: 결정 하나의 맥락, 선택, 결과를 짧게 고정
분량: 한 화면. 맥락, 결정, 결과, 상태
수명: 영구. 내용을 고치지 않고 새 ADR로 대체
실패 모드: 결정이 아니라 설명을 적어 놓아 무엇이 정해졌는지 알 수 없음

2-4. RFC — 조직 경계를 넘는 합의

목적: 여러 팀·여러 시스템에 걸친 표준이나 방향을 정함
분량: 설계 문서보다 김. 이행 계획과 영향받는 팀 목록이 필수
수명: 승인 이후에는 참조 문서. 개정판을 새로 냄
실패 모드: 절차가 무거워 아무도 시작하지 않음, 혹은 형식만 남고 실제 합의는 채팅에서 이루어짐

2-5. 무엇을 언제 쓰는가

상황	형식
문제가 진짜인지 아직 모름	1-pager
해법이 갈리고 팀 내부에서 결정 가능	설계 문서
결정은 이미 났고 근거만 남기면 됨	ADR
다른 팀이 따라야 하는 규칙을 정함	RFC

2-6. 논쟁 지점 — 무거운 RFC 대 가벼운 ADR

여기는 업계 의견이 갈립니다. 승자를 정하지 말고 축을 봅시다.

결정 빈도: 결정이 잦으면 무거운 절차가 병목이 됩니다. 드물고 크면 절차 비용이 상대적으로 작습니다.
관계자 분산도: 결정에 묶인 팀이 한 자릿수면 대화가 절차를 대체할 수 있습니다. 두 자릿수를 넘으면 대화로는 도달하지 못합니다.
되돌림 비용: 되돌릴 수 있는 결정에 RFC를 쓰면 학습 속도가 떨어집니다.
기록 유지 비용: ADR은 싸게 쓰이지만 그만큼 방치되기 쉽습니다. RFC는 비싸게 쓰이는 대신 존재감이 오래갑니다.
조직의 신뢰 수준: 신뢰가 낮은 조직에서 가벼운 절차는 "누가 언제 정했는지 모르겠다"로 귀결됩니다.

두 형식을 함께 쓰는 조직도 많습니다. RFC로 방향을 정하고, 그 방향 안에서 각 팀이 ADR로 세부 결정을 남기는 방식입니다.

3. 설계 문서의 표준 섹션과 각 섹션이 실제로 하는 일

「Design Docs at Google」이 드는 전형적인 구성은 Context and Scope, Goals and Non-Goals, The Actual Design, Alternatives Considered, 그리고 보안·프라이버시·관측 같은 교차 관심사입니다. 껍데기만 복사하면 아무 일도 하지 않으므로, 각 칸이 실제로 수행하는 기능으로 다시 씁니다.

[머리말]  제목 / 작성자 / 최종 수정일 / 상태 / 리뷰 마감일

1. Context and Scope        이 문제가 왜 지금 존재하는가
2. Goals                    무엇이 참이 되면 성공인가
3. Non-Goals                목표일 수 있었지만 목표가 아닌 것
4. The Actual Design        실제 설계와 그 안의 트레이드오프
5. Alternatives Considered  고려했고 택하지 않은 안, 그리고 그 조건
6. Cross-cutting concerns   보안 / 프라이버시 / 관측 / 운영

Context and Scope: 리뷰어가 판단하는 데 필요한 최소 배경만 채웁니다. 하는 일은 "독자와 작성자의 지식 격차를 없애는 것"입니다. 회사 연혁을 쓰는 순간 실패합니다.
Goals: 리뷰어가 설계를 평가할 자를 제공합니다. 목표가 "성능 개선"이면 자가 없는 것과 같습니다. "p99 응답 시간을 800ms 아래로"처럼 판정 가능해야 합니다.
Non-Goals: 범위를 잠급니다. 다음 절에서 따로 다룹니다.
The Actual Design: 여기가 본문입니다. 하는 일은 구조 설명이 아니라 트레이드오프의 제시입니다. 데이터 흐름, 저장 모델, 실패 시 동작, 마이그레이션 경로가 들어갑니다.
Alternatives Considered: 미래의 재논쟁을 막습니다. 역시 다음 절에서 다룹니다.
Cross-cutting concerns: 나중에 조직의 다른 부서가 반드시 물어볼 질문을 선점합니다. 비어 있으면 리뷰가 끝난 뒤에 보안 검토가 붙어 일정이 다시 밀립니다.

3-1. 머리말에 반드시 넣을 네 줄

상태(초안·리뷰 중·확정·폐기), 최종 수정일, 담당자, 리뷰 마감일. 이 네 줄이 없으면 6개월 뒤 독자가 이 문서를 믿어도 되는지 판단할 수 없습니다. 문서 본문의 품질보다 이 네 줄의 유무가 문서 수명을 더 크게 좌우합니다.

4. Non-Goals와 Alternatives Considered — 가장 자주 비어 있는 두 칸

4-1. Non-Goals는 "안 하는 일" 목록이 아니다

Non-Goal은 합리적으로 목표일 수 있었지만 이번에는 목표가 아닌 것입니다. 애초에 아무도 기대하지 않는 것을 적으면 칸만 채운 것입니다.

나쁜 Non-Goal: "이 시스템은 우주선을 제어하지 않는다"
좋은 Non-Goal: "다중 리전 동시 쓰기는 이번 범위가 아니다. 단일 리전 쓰기 + 비동기 복제로 간다"
좋은 Non-Goal: "기존 v1 API의 응답 지연 개선은 목표가 아니다. v2 경로만 대상으로 한다"

좋은 Non-Goal에는 공통점이 있습니다. 읽는 사람이 아쉬워합니다. 아쉬움이 없으면 범위를 잠근 것이 아닙니다.

4-2. Alternatives Considered의 유일한 안티패턴

가장 흔한 실패는 자기 안이 이기도록 만든 가짜 대안입니다. 셋을 적어 놓고 둘이 명백히 나쁘면, 그 문서는 대안을 검토한 것이 아니라 결론을 장식한 것입니다.

각 대안마다 다음 한 줄을 강제하면 대부분 해결됩니다.

대안 B가 선택되려면 무엇이 참이어야 하는가?
→ "쓰기 QPS가 지금의 10배가 되고, 팀이 운영 인력을 2명 더 확보하면 B가 유리하다"

이 한 줄은 세 가지를 동시에 해 줍니다. 첫째, 대안을 진지하게 다뤘다는 증거가 됩니다. 둘째, 6개월 뒤 상황이 바뀌었을 때 재검토 조건이 그대로 튀어나옵니다. 셋째, 리뷰어가 반대할 지점을 구체화해 줍니다. "B가 낫지 않나요"가 "QPS 10배 가정이 틀렸습니다"로 바뀝니다.

4-3. 대안에 반드시 포함할 하나

아무것도 하지 않는 안입니다. 현 상태를 유지하면 어떤 비용이 계속 발생하는지 적어야 프로젝트의 정당성이 검증됩니다. 이 칸을 채우다가 프로젝트가 취소되는 일도 실제로 일어나며, 그것은 문서가 제 역할을 한 사례입니다.

5. 리뷰를 운영하는 법

문서 리뷰는 코드 리뷰와 실패 양상이 거의 같습니다. 구글의 엔지니어링 관행 문서가 코드 리뷰에 대해 정리한 원칙은 문서 리뷰에도 그대로 적용됩니다.

5-1. 속도가 품질보다 먼저 무너진다

「Speed of Code Reviews」는 "코드 리뷰 요청에 응답하기까지 걸려야 하는 최대 시간은 영업일 하루"라고 못 박습니다. 집중 작업 중이 아니라면 요청이 들어온 직후에 처리하라고도 합니다.
같은 문서는 "코드 리뷰 프로세스에 대한 불만의 대부분은 프로세스를 더 빠르게 만드는 것으로 실제로 해결된다"고 말합니다.
또 느린 리뷰는 "정리 작업과 리팩터링, 기존 변경의 추가 개선을 위축시킨다"고 지적합니다.

문서에 대입하면 이렇게 됩니다. 리뷰가 느린 조직에서는 사람들이 문서를 쓰지 않게 됩니다. 문서 문화가 죽는 첫 번째 원인은 글쓰기 부담이 아니라 응답 지연입니다.

5-2. 승인 기준을 낮춰야 리뷰가 돈다

「The Standard of Code Review」는 "리뷰어는 변경이 시스템의 전체 코드 건강을 확실히 개선하는 상태가 되면, 완벽하지 않더라도 승인하는 쪽을 택해야 한다"고 말합니다. 문서도 같습니다. 승인 기준은 완결성이 아니라 개선 여부입니다. 완벽한 문서를 기다리면 문서는 영원히 초안으로 남습니다.

같은 문서의 나머지 원칙도 그대로 유효합니다. 기술적 사실과 데이터가 개인 취향을 이깁니다. 필수가 아닌 다듬기 제안에는 "Nit: " 접두어를 붙여 작성자가 무시할 수 있게 합니다. 그리고 "작성자와 리뷰어가 합의에 이르지 못한다는 이유로 변경을 방치하지 말라"고 명시합니다. 문서 리뷰에는 이 조항이 특히 중요합니다. 합의가 되지 않을 때 누가 결정하는지를 미리 정해 두지 않으면 문서는 영원히 열려 있습니다.

5-3. 3단 리뷰

「Design Docs at Google」이 말하는 문서 수명 주기는 생성과 빠른 반복 → 리뷰 → 구현과 반복 → 유지·학습입니다. 리뷰 단계를 세 겹으로 나누면 통과율이 크게 올라갑니다.

1인 리뷰: 가장 반대할 만한 사람 한 명에게 먼저 보냅니다. 여기서 절반이 걸러집니다.
소그룹 리뷰: 직접 영향받는 3~5명. 비동기 코멘트로 진행합니다.
광역 공지: 나머지에게는 결정 마감일과 함께 링크만 보냅니다. 반대 없으면 통과입니다.

회의는 비동기로 좁혀지지 않을 때만 엽니다. 반대 의견이 두 갈래로 갈리고 코멘트가 20개를 넘으면, 그때가 30분 회의를 잡을 때입니다.

5-4. 코멘트를 세 종류로 라벨링하기

차단: 이대로 가면 안 되는 이유. 반드시 해소해야 승인
질문: 이해가 안 되는 부분. 답변으로 종료 가능
취향: 나라면 다르게 하겠다는 의견. 작성자가 무시 가능

라벨이 없으면 모든 코멘트가 차단처럼 읽힙니다. 문서 리뷰가 무서운 조직은 대개 이 라벨이 없습니다.

5-5. 결정 마감일

정족수 대신 마감일을 씁니다. "8월 20일 오후 6시까지 반대 의견이 없으면 이 안으로 진행합니다"라고 문서 상단에 적습니다. 정족수 방식은 바쁜 사람 한 명이 문서를 무기한 잡아 둘 수 있게 만들고, 마감일 방식은 침묵을 명시적인 동의로 바꿉니다.

6. 결정에는 유통기한이 있다 — ADR 상태 전이

ADR의 핵심은 형식이 아니라 불변성입니다. 이미 내려진 결정의 본문을 고치면, 그 결정이 어떤 제약 아래에서 내려졌는지가 사라집니다. 결정의 근거는 그 시점의 제약에 묶여 있으므로, 제약이 바뀌면 결정을 수정하는 것이 아니라 새 결정을 내리고 이전 결정을 대체 표시합니다.

Proposed ──승인──▶ Accepted ──대체──▶ Superseded (by ADR-0031)
    │                  │
    │ 반려             │ 더는 쓰지 않음 (대체안 없음)
    ▼                  ▼
 Rejected          Deprecated

Proposed: 제안됨. 리뷰 중
Accepted: 확정. 지금 유효한 결정
Rejected: 검토했으나 채택하지 않음. 지우지 않고 남깁니다. 같은 제안이 다시 올라올 때 이 기록이 가장 값집니다
Deprecated: 더 이상 따르지 않음. 대체안은 없음
Superseded: 새 ADR이 대체함. 반드시 대체 ADR 번호를 함께 적습니다

6-1. 재검토 조건을 결정과 함께 적는다

날짜로 만료를 거는 방식("1년 뒤 재검토")은 대개 지켜지지 않습니다. 조건으로 걸어야 알람이 울립니다.

# ADR-0012: 주문 상태 저장소로 관계형 DB를 쓴다

- 상태: Accepted (2026-08-15)
- 결정자: 결제팀
- 재검토 조건: 주문 테이블이 5억 행을 넘거나, 쓰기 QPS가 3,000을 넘을 때

### 맥락
현재 주문량은 하루 40만 건, 쓰기 QPS 최대 120. 트랜잭션 경계가 주문·결제·재고에 걸쳐 있음.

### 결정
관계형 DB 단일 인스턴스 + 읽기 복제본으로 간다.

### 결과
- 좋아지는 것: 트랜잭션 경계를 코드에서 다루지 않아도 됨
- 나빠지는 것: 쓰기 확장이 수직 확장에 묶임
- 감시할 지표: 쓰기 QPS, 테이블 행 수, 복제 지연

재검토 조건에 적은 지표를 실제 대시보드에 올리면 문서가 살아 있는 상태로 유지됩니다. 이 연결이 없으면 조건은 그냥 문장입니다.

6-2. 4-2절과의 연결

4-2절에서 각 대안마다 강제한 "이 대안이 선택되려면 무엇이 참이어야 하는가"가 그대로 재검토 조건이 됩니다. 설계 문서에서 한 번 쓴 문장이 ADR의 만료 조건으로 재활용되는 구조입니다.

7. 문서가 낡는 문제와 대응

「Design Docs at Google」은 설계 문서가 "다른 모든 문서와 마찬가지로 시간이 지나면서 현실과 어긋나는 경향이 있다"고 인정하고, 원본을 갱신하거나 후속 문서를 붙여 링크하는 방식을 제시합니다. 이 문제는 없앨 수 없고 관리 방식을 선택할 수 있을 뿐입니다.

7-1. 세 가지 전략과 적용 대상

전략	하는 일	적합한 문서
갱신	본문을 최신 상태로 유지	운영 문서, 온보딩 문서, API 참조
동결 + 후속 링크	본문은 그대로 두고 상단에 후속 문서 링크	설계 문서
불변 + 상태 전이	본문 수정 금지, 새 문서로 대체	ADR, RFC

가장 흔한 실수는 설계 문서를 살아 있는 문서로 유지하려 드는 것입니다. 설계 문서는 특정 시점의 판단 기록입니다. 계속 고치면 "이 문서가 언제의 진실인가"를 잃습니다. 구현이 끝나면 동결하고, 달라진 부분은 상단 한 줄로 알립니다.

> 이 문서는 2026-08-15 시점의 설계입니다. 캐시 계층은 2026-11-02에
> ADR-0031로 대체되었습니다. 현재 구조는 그쪽을 보세요.

7-2. 낡음을 감지하는 값싼 장치

최종 검토일: 갱신일이 아니라 검토일을 적습니다. 내용이 안 바뀌어도 "아직 유효함"을 확인한 날짜가 필요합니다.
담당자 공석 감지: 담당자가 퇴사·이동하면 문서 상태를 자동으로 "주인 없음"으로 표시합니다.
코드와의 거리: 문서가 코드 저장소 안에 있으면 변경과 함께 눈에 띕니다. 별도 위키에 있으면 눈에 띄지 않습니다. 이 하나가 낡음 속도를 크게 바꿉니다.
링크 부패 점검: 문서 안 링크가 깨졌는지 정기적으로 확인합니다. 깨진 링크는 그 문서가 오래 방치됐다는 가장 신뢰할 만한 신호입니다.

7-3. 삭제도 유지 관리다

폐기된 문서를 지우지 말고 상태만 폐기로 바꾸고 검색에서 내립니다. 지우면 링크가 깨지고, 남기면 잘못된 정보가 유통됩니다. 상태 표시 + 검색 제외가 절충안입니다.

8. 문서가 실패하는 방식들

여덟 가지 실패 모드를 증상 · 원인 · 대응으로 정리합니다.

8-1. 구현 매뉴얼

증상: 문서가 코드를 산문으로 옮긴 것. 트레이드오프 문단이 없음
원인: 결정이 이미 끝난 뒤에 형식을 채우려고 문서를 씀
대응: 원문이 말하듯 이런 문서는 쓰지 말고 코딩을 시작합니다

8-2. 승인 극장

증상: 8명이 승인했는데 코멘트가 0개
원인: 리뷰가 통과 의례가 됨. 반대 비용이 높은 조직 문화
대응: 1인 리뷰를 앞에 두고, "차단/질문/취향" 라벨을 도입해 반대 비용을 낮춥니다

8-3. 스트로맨 대안

증상: 대안 셋 중 둘이 명백히 나쁨
원인: 결론을 정한 뒤 근거를 만든 것
대응: 각 대안에 "이 안이 이기려면 무엇이 참이어야 하는가"를 강제합니다

8-4. 범위 무한 확장

증상: Non-Goals가 비어 있고, 리뷰 코멘트가 새 요구사항으로 채워짐
원인: 범위를 잠그지 않음
대응: 읽는 사람이 아쉬워하는 Non-Goal을 최소 셋 적습니다

8-5. 결정 없는 문서

증상: 배경 설명은 훌륭한데 무엇이 정해졌는지 알 수 없음
원인: 정보 공유 문서와 결정 문서를 구분하지 않음
대응: 문서 상단에 "이 문서가 확정하려는 결정"을 한 문장으로 씁니다

8-6. 리뷰 정체

증상: 초안 상태로 3주 이상 열려 있는 문서가 쌓임
원인: 응답 지연과 결정권자 부재
대응: 영업일 하루 응답 기준과 결정 마감일을 씁니다

8-7. 채팅에만 남은 결정

증상: 문서에는 안 A, 실제 코드는 안 B. 근거는 3개월 전 채팅방
원인: 리뷰 후 변경을 문서에 반영하지 않음
대응: 구현 중 설계가 바뀌면 ADR 한 장을 추가하는 것을 배포 조건으로 둡니다

8-8. 코드보다 오래 살아남아 거짓말하는 문서

증상: 신입이 문서대로 만들었는데 실제 시스템과 다름
원인: 상태·검토일이 없어 신뢰 여부를 판단할 수 없음
대응: 머리말 네 줄과 폐기 상태 표시를 강제합니다

8-9. 설계 문서가 팀을 느리게 만든다는 주장

이것도 논쟁 지점입니다. 한쪽은 문서 작성과 리뷰가 착수를 지연시킨다고 말하고, 다른 쪽은 잘못된 방향으로 3주를 태우는 비용이 문서 이틀보다 크다고 말합니다. 축은 세 가지입니다. 되돌림 비용(싸면 문서보다 실험이 빠릅니다), 관계자 수(많으면 문서 없이 합의가 안 됩니다), 리뷰 응답 속도(느린 조직에서는 문서가 실제로 병목이 됩니다). 세 번째 축이 특히 중요합니다. 문서 자체보다 리뷰 지연이 느림의 원인인 경우가 많고, 그렇다면 고쳐야 할 것은 문서 정책이 아니라 리뷰 응답 시간입니다.

퀴즈: 실력을 확인해 보세요

퀴즈 1: 설계 문서 리뷰에서 8명이 모두 승인했고 코멘트는 0개입니다. 무엇을 먼저 의심해야 할까요?

정답: 아무도 읽지 않았을 가능성입니다. 리뷰가 통과 의례가 된 상태를 의심해야 합니다.

설명: 의미 있는 설계 문서는 트레이드오프를 담고 있고, 트레이드오프에는 항상 손해 보는 쪽이 있습니다. 손해 보는 쪽에서 아무 말도 나오지 않았다는 것은 읽히지 않았거나, 반대 비용이 너무 높다는 뜻입니다. 대응은 두 가지입니다. 가장 반대할 만한 사람 한 명에게 먼저 보내는 1인 리뷰를 앞에 두고, 코멘트에 차단·질문·취향 라벨을 도입해 반대 비용을 낮춥니다.

퀴즈 2: Alternatives Considered에 대안이 셋 있는데 읽어 보니 둘이 명백히 나쁩니다. 문서의 문제는 무엇인가요?

정답: 대안을 검토한 것이 아니라 결론을 장식한 것입니다. 스트로맨 대안 안티패턴입니다.

설명: 진짜로 고려된 대안이라면 특정 조건에서는 그 안이 이겨야 합니다. 각 대안 아래에 "이 안이 선택되려면 무엇이 참이어야 하는가"를 한 줄로 강제하면 이 문제는 대부분 사라집니다. 그 한 줄은 나중에 ADR의 재검토 조건으로 그대로 재활용되므로, 강제할 값어치가 두 배입니다.

퀴즈 3: 2년 전 ADR의 결정이 지금 상황과 맞지 않습니다. ADR 본문을 고쳐야 할까요?

정답: 아니요. 본문은 그대로 두고 상태를 Superseded로 바꾸며 새 ADR 번호를 함께 적습니다.

설명: ADR의 가치는 "그때 어떤 제약 아래에서 무엇을 알고 그 결정을 내렸는가"에 있습니다. 본문을 고치면 그 정보가 사라지고, 남는 것은 현재 상태를 설명하는 또 하나의 문서일 뿐입니다. 대체 관계를 명시적으로 남기면 결정의 계보를 따라갈 수 있고, 같은 논쟁이 다시 올라왔을 때 이전 판단의 전제가 바뀌었는지 확인할 수 있습니다. 같은 이유로 Rejected 상태의 ADR도 지우지 않습니다.

퀴즈 4: 팀에서 "3주 이상 걸리는 작업은 설계 문서 필수"라는 규칙을 만들려고 합니다. 어떤 문제가 있나요?

정답: 규모는 대리 지표일 뿐이고, 실제 기준은 되돌림 비용과 합리적 대안의 존재입니다.

설명: 3주짜리 단순 반복 작업에는 문서가 필요 없고, 반나절짜리 저장 포맷 변경이나 식별자 형식 결정에는 필요합니다. 규모 기준을 쓰면 두 가지가 동시에 일어납니다. 트레이드오프 없는 긴 작업에 형식적인 문서가 양산되고, 짧지만 되돌릴 수 없는 결정은 기록 없이 지나갑니다. 판별 질문은 되돌림 비용, 묶이는 팀 수, 대안 수, 외부 계약 변경 여부, 보안·규제 판단 포함 여부입니다.

퀴즈 5: RFC 프로세스를 도입한 뒤 "문서 때문에 개발이 느려졌다"는 불만이 나옵니다. 무엇을 먼저 측정해야 할까요?

정답: 작성 시간이 아니라 리뷰 응답 시간과 문서가 초안 상태로 머문 기간을 먼저 측정합니다.

설명: 구글의 코드 리뷰 문서는 "코드 리뷰 프로세스에 대한 불만의 대부분은 프로세스를 더 빠르게 만드는 것으로 실제로 해결된다"고 말하고, 응답까지 걸려야 하는 최대 시간을 영업일 하루로 제시합니다. 문서도 같습니다. 병목이 작성이면 템플릿을 줄이는 것이 답이지만, 병목이 대기면 템플릿을 줄여도 아무것도 나아지지 않습니다. 측정 없이 형식부터 줄이면 문서 품질만 떨어지고 지연은 그대로 남습니다.

퀴즈 6: 구현이 끝난 설계 문서를 계속 최신 상태로 갱신하는 팀이 있습니다. 무엇이 문제인가요?

정답: 설계 문서는 특정 시점의 판단 기록입니다. 계속 고치면 "이 문서가 언제의 진실인가"를 잃습니다.

설명: 문서는 성격에 따라 관리 전략이 다릅니다. 운영·온보딩·API 참조 문서는 갱신하고, 설계 문서는 구현 종료 시점에 동결한 뒤 달라진 부분을 상단 링크로 알리고, ADR과 RFC는 본문을 고치지 않고 상태 전이로 관리합니다. 설계 문서를 살아 있는 문서로 만들면 결정 시점의 제약이 지워지고, 결국 왜 그렇게 만들었는지를 답할 수 없는 문서가 됩니다.

마치며

문서가 남기려는 것은 설명이 아니라 결정과 그 결정의 조건입니다. 조건이 적혀 있으면 문서는 만료 시점을 스스로 알리고, 조건이 없으면 문서는 조용히 거짓말이 됩니다.

실무에서 가장 값싼 개선 세 가지를 꼽으면 이렇습니다. 첫째, 머리말 네 줄(상태·최종 검토일·담당자·결정 마감일)을 모든 문서에 강제합니다. 둘째, 모든 대안에 "이 안이 이기려면 무엇이 참이어야 하는가" 한 줄을 붙입니다. 셋째, 리뷰 응답 시간을 영업일 하루로 정하고 실제로 측정합니다. 셋 다 템플릿을 늘리지 않으면서 문서의 수명을 크게 늘립니다.

형식은 조직마다 다를 수 있습니다. 하지만 "무엇이 정해졌는가", "왜 그때 그렇게 정했는가", "언제 다시 봐야 하는가" 세 질문에 답하지 못하는 문서는 형식이 무엇이든 사라지는 문서입니다.

참고 자료

Design Docs at Google — Industrial Empathy (Malte Ubl) — 설계 문서의 정의(구현 전략과 트레이드오프 중심), "엔지니어의 일은 코드 생산이 아니라 문제 해결"이라는 문장, 표준 섹션 구성(Context and Scope / Goals and Non-Goals / The Actual Design / Alternatives Considered / 교차 관심사), 문서를 쓰지 않아도 되는 조건, 문서 수명 주기, 문서가 현실과 어긋나는 문제와 대응 방식을 인용했습니다. 2026-08-15 확인.
The Standard of Code Review — Google Engineering Practices — "전체 코드 건강을 확실히 개선하면 완벽하지 않아도 승인" 원칙, 기술적 사실이 취향을 이긴다는 원칙, "Nit: " 접두어, 합의 실패를 이유로 변경을 방치하지 말라는 조항을 문서 리뷰에 대입했습니다. 2026-08-15 확인.
Speed of Code Reviews — Google Engineering Practices — 영업일 하루 응답 기준, "불만의 대부분은 프로세스를 빠르게 만들어 해결된다", 느린 리뷰가 정리 작업과 리팩터링을 위축시킨다는 지적을 인용했습니다. 2026-08-15 확인.
문서 유형 네 가지의 비교표, 다섯 가지 판별 질문, 3단 리뷰 절차, 코멘트 라벨링, 재검토 조건을 대시보드에 연결하는 방법, 여덟 가지 실패 모드는 위 자료에 그대로 나오는 것이 아니라 이 글에서 정리한 절차입니다.

이어서 읽기

이 블로그의 관련 글: 글로 설득하기 — 디자인 문서와 RFC가 통과되는 구조
이 블로그의 관련 글: 엔지니어의 쓰는 능력
이 블로그의 관련 글: 코드 리뷰의 대화법
이 블로그의 관련 글: 기술 부채를 비즈니스 언어로
관련 도구: 협업 RPG

완전 가이드 시리즈

다음 글: API 설계 완전 가이드: 되돌릴 수 없는 결정부터 정하기