LabHub

블로그

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

2026-08-15 · 42 분 읽기 · #설계문서#adr#rfc#design-doc#기술문서#의사결정#아키텍처

한국어English日本語

들어가며

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

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

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

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

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

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

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

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

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

1-3. 자주 틀리는 지점

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

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

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

2-1. 1-pager — 문제가 진짜인지 합의하는 문서

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

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

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

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

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

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

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

두 형식을 함께 쓰는 조직도 많습니다. 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   보안 / 프라이버시 / 관측 / 운영

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

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

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

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

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

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

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

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

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

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

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

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

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

5. 리뷰를 운영하는 법

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

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

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

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

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

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

5-3. 3단 리뷰

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

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

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

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

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

5-5. 결정 마감일

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

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

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

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

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-3. 스트로맨 대안

8-4. 범위 무한 확장

8-5. 결정 없는 문서

8-6. 리뷰 정체

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

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는 본문을 고치지 않고 상태 전이로 관리합니다. 설계 문서를 살아 있는 문서로 만들면 결정 시점의 제약이 지워지고, 결국 왜 그렇게 만들었는지를 답할 수 없는 문서가 됩니다.

마치며

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

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

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

참고 자료

이어서 읽기

완전 가이드 시리즈

원문 보기: https://www.youngju.dev/blog/architecture/2026-08-15-guide-design-docs

댓글

아직 댓글이 없습니다.

로그인하면 댓글을 쓸 수 있습니다