글로 일하는 개발자 — 디자인 독, ADR, 그리고 설득하는 테크니컬 라이팅

들어가며 — 스펙이 곧 코드가 된 시대
글쓰기가 시니어의 레버리지인 이유
- 1. 비동기 조직의 대역폭
- 2. 사고의 품질 검증
- 3. AI 시대의 증폭
문서 유형 맵 — 언제 무엇을 쓰나
디자인 독 템플릿 — 섹션별 작성 요령
ADR 작성법 — 컨텍스트, 결정, 결과
리뷰 받는 문서의 기술 — 읽는 사람의 10분을 설계하라
나쁜 문서 고치기 — 비포/애프터
반대 의견 다루기 — 대안 비교 테이블 의무화
문서 문화 도입 가이드 — 가볍게 시작하기
AI를 글쓰기에 활용하는 법과 한계
글쓰기 훈련 루틴
포스트모템과 런북 — 미니 템플릿
리뷰 코멘트에 답하는 기술
사례 — 문서 하나가 회의 다섯 개를 줄인 이야기
문장 수준의 규칙 — 빠른 교정 가이드
부수 효과 — 문서는 온보딩 자산이다
함정과 반론
체크리스트
마치며
참고 자료

들어가며 — 스펙이 곧 코드가 된 시대

"시니어 엔지니어의 주력 언어는 영어(자연어)다"라는 농담이 있습니다. 2026년에 이 농담은 더 이상 농담이 아닙니다. Google의 디자인 독 문화를 정리한 Malte Ubl의 "Design Docs at Google" 글은 여전히 GeekNews와 Hacker News에서 주기적으로 재소환되는데, 최근 재조명의 맥락이 달라졌습니다. AI 코딩 에이전트가 보편화되면서, 잘 쓰인 스펙과 설계 문서가 거의 그대로 동작하는 코드로 변환되는 시대가 왔기 때문입니다.

Claude Code나 Codex 같은 에이전트에게 일을 시켜본 분이라면 체감하실 겁니다. 모호한 설계를 주면 모호한 코드가 나오고, 명확한 디자인 독을 주면 며칠치 작업이 몇 시간 만에 나옵니다. CLAUDE.md나 AGENTS.md를 작성하는 것이 새로운 엔지니어링 관행으로 자리 잡은 것도 같은 흐름입니다. 글쓰기는 이제 "소프트 스킬"이 아니라, 사람과 AI 양쪽을 움직이는 실행 인터페이스입니다.

이 글은 뜬구름 잡는 "글쓰기의 중요성" 설교가 아닙니다. 디자인 독과 ADR의 구체적 템플릿, 섹션별 작성 요령, 리뷰를 통과하는 문서의 기술, 나쁜 문서를 고치는 비포/애프터, 그리고 AI를 글쓰기에 활용하는 실전 프롬프트까지 — 내일부터 쓸 수 있는 것들만 담았습니다.

글쓰기가 시니어의 레버리지인 이유

코드는 한 번에 한 시스템을 움직이지만, 글은 한 번에 여러 사람의 머리를 움직입니다. 구체적으로 세 가지 레버리지가 있습니다.

1. 비동기 조직의 대역폭

회의는 참석자 수만큼 시간을 소비하지만, 문서는 한 번 쓰면 무한히 읽힙니다. 10명이 참여하는 1시간 설계 회의는 10인시(person-hour)를 소비합니다. 같은 내용을 2시간 들여 문서로 쓰고 각자 10분씩 읽게 하면 약 3.7인시입니다. 그리고 문서는 6개월 뒤에 합류한 신규 입사자에게도, 새벽에 장애를 만난 온콜 엔지니어에게도 다시 작동합니다. 회의는 그렇지 않습니다.

2. 사고의 품질 검증

Amazon이 파워포인트를 금지하고 6페이지 내러티브를 강제하는 이유는 유명합니다. 글은 어물쩍 넘어가는 것을 허용하지 않기 때문입니다. 머릿속에서는 완벽해 보이던 설계가 글로 쓰는 순간 구멍을 드러냅니다. "여기서 캐시를 무효화하면 되겠지"라고 생각하는 것과, 무효화 시점과 경쟁 조건을 문장으로 쓰는 것은 완전히 다른 수준의 사고를 요구합니다.

3. AI 시대의 증폭

2026년의 새 변수입니다. 잘 쓰인 디자인 독은 AI 에이전트에게 그대로 입력 가능한 실행 계획입니다. "컨텍스트 엔지니어링"이 프롬프트 엔지니어링을 대체하는 키워드가 된 지금, 좋은 문서를 쓰는 능력과 AI에게 좋은 컨텍스트를 주는 능력은 사실상 같은 능력입니다. 문서를 못 쓰는 엔지니어는 AI 레버리지에서도 뒤처집니다.

문서 유형 맵 — 언제 무엇을 쓰나

문서마다 목적과 수명이 다릅니다. 잘못된 유형을 고르면 노력이 낭비됩니다.

문서 유형	핵심 질문	쓰는 시점	수명	분량 기준
디자인 독	어떻게 만들 것인가	구현 착수 전	프로젝트 기간	3~10페이지
ADR	왜 이렇게 결정했나	되돌리기 어려운 결정 직후	영구	1~2페이지
RFC	다 함께 동의하는가	여러 팀에 영향이 갈 때	결정 시까지	2~6페이지
포스트모템	무엇을 배웠나	장애 해소 후 48시간 내	영구	2~4페이지
런북	새벽 3시에 뭘 누르나	운영 절차 확정 시	시스템 수명	절차 길이만큼

선택 기준을 한 줄로 요약하면 이렇습니다. 앞으로 할 일의 설계는 디자인 독, 이미 내린 결정의 기록은 ADR, 합의가 필요한 제안은 RFC, 사고의 교훈은 포스트모템, 반복 절차는 런북. 가장 흔한 실수는 ADR을 써야 할 자리에 아무것도 안 쓰는 것과, 디자인 독이면 충분한 자리에 RFC 프로세스를 돌려 모두를 지치게 하는 것입니다.

디자인 독 템플릿 — 섹션별 작성 요령

Google 스타일 디자인 독을 기반으로, 실무에서 다듬은 골격입니다. 그대로 복사해서 쓰셔도 됩니다.

# 디자인 독: 주문 이벤트 파이프라인 v2

상태: 리뷰 중 | 작성자: 김영주 | 리뷰어: A, B | 최종 수정: 2026-06-12

## 1. 요약 (3문장 이내)
주문 이벤트 처리를 단일 컨슈머에서 파티션 기반 병렬 처리로
전환한다. 목표는 p99 처리 지연을 8초에서 500ms 이하로 줄이는 것.
마이그레이션은 듀얼 라이트로 4주간 점진 전환한다.

## 2. 배경과 문제
- 현재 구조와 무엇이 왜 아픈지 (지표 포함)
- 이 문서를 읽는 데 필요한 최소 맥락

## 3. 목표 / 비목표
목표:
- p99 지연 500ms 이하
- 컨슈머 장애 시 자동 재처리
비목표:
- 이벤트 스키마 변경 (별도 프로젝트)
- 실시간 분석 지원

## 4. 제안하는 설계
- 아키텍처 개요 (다이어그램)
- 데이터 모델, API, 장애 처리, 보안
- 핵심 트레이드오프와 그 근거

## 5. 검토한 대안
- 대안 A: 현 구조 + 수직 확장 (기각 사유)
- 대안 B: 완전 신규 시스템 (기각 사유)
- 비교 테이블 필수

## 6. 우려 사항과 열린 질문
- 아직 답이 없는 것들을 솔직하게

## 7. 마이그레이션과 롤백 계획

## 8. 측정 계획
- 성공을 어떤 지표로 언제 판정하는가

섹션별 요령은 다음과 같습니다.

요약: 문서에서 가장 중요한 3문장입니다. 바쁜 리뷰어는 이것만 읽습니다. "무엇을, 왜, 어떻게"가 다 들어가야 합니다. 본문을 다 쓴 뒤 마지막에 다시 쓰십시오.
배경과 문제: 신규 입사자가 읽어도 이해되는 수준이 기준입니다. 단, 길면 안 됩니다. 링크로 치환할 수 있는 배경은 링크로 치환합니다. 핵심은 "아픔의 정량화"입니다 — "느리다"가 아니라 "p99가 8초라서 CS 티켓이 주 40건 발생한다".
목표/비목표: 비목표가 진짜 알맹이입니다. 비목표를 명시하지 않으면 리뷰가 스코프 논쟁으로 새고, 구현 중에 범위가 부풉니다. "이번에 안 하는 것"을 못 박는 게 문서가 주는 가장 큰 평화입니다.
제안하는 설계: 다이어그램 하나가 열 문단을 이깁니다. 트레이드오프를 숨기지 마십시오. 리뷰어가 어차피 찾아냅니다. 먼저 말하면 신뢰가 쌓이고, 들키면 신뢰가 깎입니다.
검토한 대안: 이 섹션이 없는 디자인 독은 디자인 독이 아니라 통보문입니다. 뒤에서 자세히 다룹니다.
열린 질문: "모른다"고 쓸 수 있는 문서가 좋은 문서입니다. 리뷰어의 에너지를 정확히 이 지점으로 유도하는 효과도 있습니다.

ADR 작성법 — 컨텍스트, 결정, 결과

ADR(Architecture Decision Record)은 "왜"를 기록하는 가장 가벼운 형식입니다. Michael Nygard의 원형 그대로, 세 부분이면 충분합니다: 컨텍스트(결정 당시의 상황과 제약), 결정(무엇을 하기로 했나), 결과(이 결정으로 얻는 것과 감수하는 것).

실제 예시 두 개를 보겠습니다.

# ADR-014: 메시지 큐로 Kafka 대신 SQS를 사용한다

상태: 승인됨 (2026-05-20)

## 컨텍스트
주문 이벤트 파이프라인에 메시지 큐가 필요하다. 일 이벤트 약
200만 건, 피크 초당 300건. 팀에 Kafka 운영 경험자가 없고,
인프라 전담 인력은 0.5명이다. 이벤트 순서 보장은 주문 ID
단위로만 필요하다.

## 결정
SQS FIFO 큐를 사용한다. 주문 ID를 메시지 그룹 ID로 사용해
부분 순서를 보장한다.

## 결과
- (+) 운영 부담 제로, 기존 AWS IAM 체계 재사용
- (+) 피크 트래픽의 10배까지 별도 작업 없이 흡수
- (-) 처리량 상한 존재. 초당 3,000건 초과 시 재설계 필요
- (-) 리플레이가 Kafka 대비 불편. 별도 아카이브 버킷 운영
- 재검토 트리거: 일 이벤트 2,000만 건 도달 시

# ADR-021: 프론트엔드 상태 관리를 추가 라이브러리 없이 한다

상태: 승인됨 (2026-06-02)

## 컨텍스트
관리자 대시보드 신규 개발. 서버 상태가 데이터의 95퍼센트이고
클라이언트 전용 상태는 모달 열림, 필터 정도다. 팀은 React
Query를 이미 사용 중이다. 과거 프로젝트에서 Redux 보일러
플레이트 유지보수에 분기당 약 2주를 쓴 전적이 있다.

## 결정
전역 상태 라이브러리를 추가하지 않는다. 서버 상태는 React
Query, 클라이언트 상태는 URL 쿼리 파라미터와 컴포넌트
로컬 상태로 처리한다.

## 결과
- (+) 의존성과 학습 비용 제로, 상태 출처가 명확
- (-) 복잡한 클라이언트 상태가 늘어나면 prop drilling 위험
- 재검토 트리거: 3단계 이상 prop 전달이 5곳 이상 발생 시

ADR에서 지킬 세 가지 원칙입니다.

결정 직후에 쓴다. 2주만 지나도 "왜 그랬는지"의 절반은 증발합니다. ADR은 기억이 아니라 현장 기록입니다.
기각된 미래의 나를 위해 쓴다. ADR의 독자는 6개월 뒤 "도대체 왜 SQS를 썼지?"라며 git blame을 따라온 사람입니다. 그 사람이 같은 논쟁을 반복하지 않게 하는 게 목적입니다.
재검토 트리거를 명시한다. "이 조건이 되면 이 결정은 다시 논의한다"를 적어두면, ADR이 교조가 되는 것을 막을 수 있습니다.

리뷰 받는 문서의 기술 — 읽는 사람의 10분을 설계하라

문서는 쓰는 게 절반, 읽히는 게 절반입니다. 리뷰어의 10분을 설계하는 기술입니다.

두괄식의 강제: 모든 섹션의 첫 문장이 그 섹션의 결론이어야 합니다. 리뷰어가 첫 문장만 읽고 넘어가도 전체 논지가 잡히는 문서가 좋은 문서입니다.
리뷰 요청의 스코프 지정: "전체적으로 봐주세요"는 최악의 요청입니다. "섹션 4의 장애 처리 방식과 섹션 5의 대안 B 기각 사유, 이 두 가지에 대한 의견이 필요합니다"처럼 리뷰어의 에너지를 배분해 주십시오.
읽기 시간 명시: 문서 상단에 "예상 읽기 시간 8분"을 적습니다. 사소해 보이지만 "나중에 읽어야지" 큐에서 문서를 꺼내오는 효과가 큽니다.
코멘트 마감 설정: "6월 19일까지 코멘트가 없으면 승인으로 간주하고 진행합니다"는 무례한 게 아니라 배려입니다. 마감 없는 리뷰 요청은 영원히 끝나지 않습니다.
질문을 심어두기: 의견이 필요한 지점에 "열린 질문: X와 Y 중 어느 쪽이 나을까요?"를 인라인으로 심으면, 리뷰어는 백지에서 비평을 시작하는 것보다 훨씬 쉽게 참여합니다.

나쁜 문서 고치기 — 비포/애프터

추상적인 조언보다 실제 교정이 빠릅니다. 흔한 나쁜 문단을 고쳐보겠습니다.

비포:

현재 시스템은 여러 가지 문제가 있어서 개선이 필요하다.
성능도 좋지 않고 유지보수도 어렵다. 따라서 새로운 아키텍처를
도입하면 여러 측면에서 많은 이점이 있을 것으로 기대된다.

문제점: 정량화 없음("좋지 않고"), 주체 없음("기대된다"), 근거 없는 결론("따라서"), 모든 단어가 모호함("여러 가지", "여러 측면").

애프터:

주문 조회 API의 p99 지연이 3.2초다(목표 500ms). 원인은
주문-결제-배송 테이블의 3중 조인이다(부록 A의 실행 계획 참조).
읽기 모델을 분리하면 조인이 제거되어 p99를 400ms 이하로
낮출 수 있다. 비용은 이벤트 동기화 코드 약 2주 분량과
최대 1초의 결과 지연이며, 주문 조회 화면은 이를 허용한다
(PM 확인 완료, 링크).

바뀐 것: 모든 주장에 숫자, 모든 인과에 근거, 모든 트레이드오프에 수용 가능성 확인. 문장 수는 비슷하지만 정보 밀도는 다섯 배입니다. 좋은 테크니컬 라이팅은 화려한 문장이 아니라 검증 가능한 문장을 쓰는 일입니다.

반대 의견 다루기 — 대안 비교 테이블 의무화

설득력 있는 문서의 비밀 하나를 꼽으라면 이것입니다. 반대자가 할 말을 먼저 해버리는 것. 검토한 대안 섹션에 비교 테이블을 의무화하면 자연스럽게 그렇게 됩니다.

기준 (가중치)	제안: 읽기 모델 분리	대안 A: 캐시 강화	대안 B: DB 수직 확장
p99 목표 달성 (높음)	달성 가능	캐시 미스 시 미달	일시적 달성
구현 비용 (높음)	2주	1주	2일
운영 복잡도 (중간)	동기화 모니터링 추가	무효화 버그 리스크	변화 없음
1년 뒤 확장성 (중간)	수평 확장 가능	한계 동일	비용 급증
데이터 일관성 (높음)	최대 1초 지연	무효화 실패 시 불일치	강한 일관성

테이블이 강제하는 것은 두 가지입니다. 첫째, 기각된 대안에도 장점이 있음을 인정하게 됩니다(대안 B의 구현 비용 2일은 진짜 매력적입니다 — 이걸 숨기면 리뷰어가 찾아내서 문서 전체의 신뢰가 무너집니다). 둘째, 판단 기준과 가중치를 명시하게 되어, 논쟁이 "취향 싸움"에서 "기준 합의"로 옮겨갑니다. 리뷰어가 결론에 반대하더라도 "가중치를 다르게 보는 것"으로 논점이 좁혀지면, 그 논쟁은 생산적입니다.

문서 문화 도입 가이드 — 가볍게 시작하기

문서 문화가 없는 팀에 풀세트 프로세스를 들이밀면 반드시 실패합니다. 단계적 도입 경로입니다.

1단계 (혼자, 이번 주부터): 다음번 "되돌리기 어려운 결정"이 나왔을 때 ADR 한 장을 씁니다. 허락받지 마십시오. 그냥 쓰고 PR에 첨부합니다. ADR은 한 장짜리라 아무도 반대하지 않습니다.
2단계 (팀, 1개월): ADR 디렉터리를 레포에 만들고(docs/adr/), 템플릿을 넣어둡니다. "되돌리는 데 1주 이상 걸리는 결정은 ADR을 남기자"는 가벼운 합의만 만듭니다.
3단계 (팀, 분기): 신규 프로젝트 1개에 디자인 독을 시범 적용합니다. 효과를 측정할 것: 구현 중 방향 전환 횟수, 리뷰에서 발견된 설계 결함 수.
4단계 (조직): 디자인 독 리뷰를 정례화하되, "모든 작업에 디자인 독"은 절대 금지입니다. 기준 예시: 2인주 이상 작업, 또는 팀 경계를 넘는 변경만.

핵심 원칙은 문서가 일을 돕는다는 체감이 강제보다 먼저 와야 한다는 것입니다. 첫 ADR이 6개월 뒤 신규 입사자의 "왜 이렇게 돼 있어요?"에 링크 하나로 답하는 순간, 문화는 저절로 퍼집니다.

AI를 글쓰기에 활용하는 법과 한계

2026년에 디자인 독을 백지에서 쓰는 사람은 드뭅니다. 하지만 AI 활용에는 잘 쓰는 패턴과 망하는 패턴이 명확히 갈립니다.

잘 쓰는 패턴 세 가지입니다.

초안 생성이 아니라 구조 생성: "X에 대한 디자인 독 써줘"는 그럴듯하지만 알맹이 없는 문서를 만듭니다. 대신 자신의 생각을 쏟아낸 메모를 주고 구조화를 시키십시오.

프롬프트 예시 1 — 구조화:
아래는 내가 새 이벤트 파이프라인에 대해 쏟아낸 생각 메모다.
이걸 디자인 독 구조(요약/배경/목표/설계/대안/리스크)로
재배열하되, 내용을 지어내지 마라. 메모에 없는 부분은
[TODO: 작성자 입력 필요]로 표시하라.

[메모 붙여넣기]

비판 요청 — 가장 저평가된 활용법: AI는 초안 작성보다 적대적 리뷰에서 더 큰 가치를 냅니다.

프롬프트 예시 2 — 적대적 리뷰:
너는 이 디자인 독을 기각시키려는 깐깐한 스태프 엔지니어다.
다음 관점에서 가장 아픈 질문 5개를 만들어라:
1) 정량적 근거가 없는 주장 2) 검토되지 않은 장애 시나리오
3) 비목표에 숨겨진 스코프 리스크 4) 대안 비교의 편향
각 질문에 대해, 문서의 어느 부분을 고치면 방어되는지도 제시하라.

독자 시뮬레이션: "이 문서를 인프라 맥락이 없는 신입 백엔드 엔지니어가 읽는다고 가정하고, 이해가 막히는 지점을 순서대로 나열하라" 같은 요청은 2회차 리허설 독자를 대체해 줍니다.

한계도 분명합니다. 첫째, 결정은 위임할 수 없습니다. AI는 대안을 나열하고 트레이드오프를 정리해 주지만, 가중치를 정하는 것은 조직의 맥락(팀 역량, 정치, 예산)을 아는 사람의 몫입니다. 둘째, 그럴듯함의 함정이 있습니다. AI가 쓴 문서는 문장이 매끄러워서 검토를 통과하기 쉽지만, 매끄러움과 정확함은 무관합니다. 숫자, 링크, 시스템 이름은 반드시 사람이 검증해야 합니다. 셋째, 자기 생각이 없는 상태에서 AI 초안으로 시작하면 앵커링됩니다. 백지 사고 10분이 먼저, AI는 그다음입니다.

글쓰기 훈련 루틴

글쓰기는 근육이라 루틴이 전부입니다. 부담 없는 순서로 제안합니다.

주 1회, 결정 하나를 ADR로 (15분): 가장 가성비 좋은 훈련입니다. 형식이 정해져 있어 백지 공포가 없습니다.
PR 설명을 3문단 구조로 (매번 5분): 무엇을/왜/어떻게 검증했나. PR 설명은 가장 자주 쓰는 테크니컬 라이팅입니다.
남의 디자인 독에 코멘트 달기 (주 30분): 쓰기 전에 읽기. 좋은 문서를 만나면 "왜 읽기 편했는지"를 한 줄 메모하십시오.
분기 1회, 디자인 독 풀사이즈 (반나절): 실전. 위 루틴이 쌓였다면 생각보다 쉽게 써집니다.
요약 훈련 (수시): 읽은 기술 글을 3문장으로 요약해 팀 채널에 공유합니다. 압축이 테크니컬 라이팅의 핵심 근육입니다.

포스트모템과 런북 — 미니 템플릿

디자인 독과 ADR 다음으로 자주 쓰게 되는 두 형식도 골격을 갖춰두면 작성 시간이 절반으로 줄어듭니다.

포스트모템은 "비난 없는(blameless)" 원칙이 형식보다 중요하지만, 형식이 원칙을 지켜줍니다. 사람 이름 대신 역할과 시스템을 주어로 쓰게 만드는 템플릿이 그 장치입니다.

# 포스트모템: 주문 API 장애 (2026-06-08)

심각도: SEV-2 | 영향: 23분간 주문 생성 실패 약 1,200건
작성: 온콜 엔지니어 | 리뷰: 팀 전체 (6/10 회의)

## 타임라인 (모든 시각 KST)
- 14:02 배포 완료 (PR 1077)
- 14:05 에러율 알람 발화
- 14:11 온콜이 배포 연관성 확인, 롤백 시작
- 14:25 에러율 정상화

## 근본 원인
커넥션 풀 설정이 환경 변수 누락으로 기본값(5)으로 떨어짐.
스테이징은 트래픽이 낮아 재현되지 않았음.

## 잘된 것 / 아쉬운 것
- (+) 알람에서 롤백 결정까지 9분
- (-) 환경 변수 검증이 배포 파이프라인에 없었음

## 액션 아이템 (담당/기한 필수)
- 필수 환경 변수 스키마 검증 추가 — A, 6/15, INFRA-310
- 스테이징 부하 테스트 주기화 — B, 6/22, PERF-20

런북은 "새벽 3시의 나"가 독자라는 것만 기억하면 됩니다. 판단을 요구하지 말고, 복사해서 붙여넣을 수 있는 명령과 예상 출력을 적습니다.

# 런북: 주문 이벤트 컨슈머 재시작

언제 쓰나: 컨슈머 랙 알람 (지표 링크) 이 10분 이상 지속될 때

1. 현재 랙 확인 (예상: 정상 시 1,000 미만)
   kubectl exec -it consumer-0 -- ./check-lag.sh
2. 컨슈머 재시작
   kubectl rollout restart deployment/order-consumer
3. 5분 후 랙 재확인. 줄지 않으면 → 에스컬레이션: 데이터팀 온콜
주의: 절대 파티션 리셋 명령을 먼저 실행하지 말 것 (데이터 유실)

리뷰 코멘트에 답하는 기술

문서를 쓰는 기술의 절반은 코멘트에 답하는 기술입니다. 잘 쓴 문서가 코멘트 대응에서 무너지는 경우를 자주 봅니다. 원칙 다섯 가지입니다.

모든 코멘트에 답한다: 무시된 코멘트 하나가 리뷰어 전체의 참여 의욕을 꺾습니다. 반영하지 않더라도 "반영하지 않는 이유"를 적습니다.
수용은 빠르게, 반박은 정중하게: 맞는 지적은 "좋은 지적입니다, 섹션 4에 반영했습니다(diff 링크)"로 즉시 처리합니다. 동의하지 않으면 근거를 들어 답하되, 두 번 왕복해도 평행선이면 문서 밖(통화)으로 가져갑니다.
코멘트를 문서 개선으로 환원한다: 리뷰어가 헷갈렸다면 그 자체가 문서의 결함입니다. "코멘트로 설명했으니 됐다"가 아니라 본문을 고칩니다. 다음 독자는 코멘트 스레드를 읽지 않습니다.
결정 권한을 흐리지 않는다: 모든 코멘트를 다수결로 처리하면 문서가 낙타가 됩니다. "의견 감사합니다. 트레이드오프를 검토한 결과 원안을 유지합니다. 근거는 X입니다"라고 말할 수 있어야 합니다.
리뷰 종료를 선언한다: 반영이 끝나면 "코멘트 반영 완료, 상태를 승인됨으로 변경합니다"를 명시적으로 알립니다. 끝나지 않는 문서는 신뢰를 잃습니다.

사례 — 문서 하나가 회의 다섯 개를 줄인 이야기

구체적인 그림을 위해 가상의(그러나 흔한) 시나리오 하나를 봅니다. 결제 모듈 분리를 둘러싸고 백엔드, 인프라, PM이 3주간 다섯 번의 회의를 했지만 결론이 나지 않았습니다. 매번 같은 논쟁이 반복됐는데, 참석자가 조금씩 달랐기 때문에 지난 회의의 합의가 다음 회의에서 무효가 됐기 때문입니다.

여섯 번째 회의 대신 한 명이 디자인 독을 썼습니다. 대안 3개를 비교 테이블로 정리하고, 각 팀의 우려를 "열린 질문"으로 명시하고, 코멘트 마감을 1주일로 걸었습니다. 결과: 코멘트 19개, 비동기 합의 도달, 회의는 최종 결정 30분 한 번으로 끝났습니다. 문서가 한 일은 마법이 아닙니다. 논쟁의 상태를 저장한 것입니다. 회의는 휘발성 메모리라 매번 처음부터 다시 계산했지만, 문서는 디스크라서 이어서 계산할 수 있었던 것뿐입니다.

문장 수준의 규칙 — 빠른 교정 가이드

구조가 잡혔다면 문장입니다. 테크니컬 라이팅에서 즉시 효과가 나는 문장 규칙 일곱 가지를 교정 예시와 함께 정리합니다.

수동태를 능동태로: "결정되었다" → "백엔드팀이 결정했다". 주어가 없는 문장은 책임이 없는 문장입니다.
이중 부정 금지: "불가능하지 않다" → "가능하다". 독자의 파싱 비용을 줄이십시오.
한 문장 한 주장: 접속사로 이어진 세 줄짜리 문장은 세 문장으로 자릅니다. 기술 문서의 문장은 평균 25자 이내가 읽기 좋습니다.
형용사 대신 숫자: "상당한 개선" → "p99 기준 62퍼센트 개선". 숫자가 없다면 그 주장은 아직 검증되지 않은 것입니다.
대명사 추방: "이것", "그 방식"은 두 문단만 지나면 무엇을 가리키는지 아무도 모릅니다. 귀찮아도 명사를 반복하십시오.
약어는 첫 등장에 풀어 쓴다: 팀 내부 약어는 신규 입사자와 6개월 뒤의 자신에게는 외국어입니다.
불확실성을 정직하게 표기: "아마 될 것이다" 같은 모호한 헤지 대신 "측정 전이다. 6월 20일 벤치마크 후 확정"처럼 불확실성의 해소 시점을 적습니다.

이 규칙들은 검토 단계에서 기계적으로 적용할 수 있어서, AI 리뷰 프롬프트에 "위 일곱 규칙 위반을 찾아라"로 넣으면 자가 교정 루프가 만들어집니다.

부수 효과 — 문서는 온보딩 자산이다

문서 문화의 가장 저평가된 수익은 온보딩입니다. 디자인 독과 ADR이 쌓인 팀의 신규 입사자는 "왜 이렇게 만들어졌는가"의 역사를 시간 순으로 읽을 수 있습니다. 이는 코드 투어 열 번보다 빠른 컨텍스트 전수입니다.

실천 팁 세 가지입니다.

온보딩 리딩 리스트: ADR 디렉터리에서 핵심 결정 10개를 골라 "입사 첫 주 읽기 목록"으로 만들어 둡니다. 만드는 데 10분, 신규 입사자마다 며칠을 아껴줍니다.
신규 입사자를 문서 테스터로: 입사자가 문서를 읽다 막힌 지점을 기록하게 하면, 문서의 결함 지도가 공짜로 만들어집니다. "여기서 막혔어요"는 최고의 문서 리뷰입니다.
첫 기여를 문서로: 첫 주에 코드 대신 "온보딩하며 발견한 문서 개선 PR"을 내게 하면, 심리적 부담 없이 기여 사이클을 시작할 수 있습니다.

함정과 반론

균형을 위해 문서 문화의 어두운 면도 다룹니다.

**"문서가 일을 대체하는 조직"**은 실재하는 병폐입니다. 디자인 독 승인에 6주가 걸려서 정작 구현할 에너지가 남지 않는 조직, 문서 작성 자체가 성과가 되어 아무도 읽지 않는 문서가 쌓이는 조직이 있습니다. 문서는 결정을 빠르게 하기 위한 도구이지, 결정을 미루는 의식이 아닙니다. "이 문서가 없으면 무엇이 잘못되는가?"에 답할 수 없다면 쓰지 마십시오.

**"코드가 곧 문서다"**라는 반론도 일리가 있습니다. 코드와 문서가 어긋나면 문서가 거짓말이 되고, 거짓말하는 문서는 없느니만 못합니다. 대응 원칙은 수명 분리입니다. "왜"를 다루는 문서(ADR, 디자인 독)는 결정 시점의 스냅샷이므로 코드와 어긋나도 가치가 유지됩니다. "어떻게"를 다루는 문서(런북, API 문서)는 코드 가까이에(가능하면 같은 레포에) 두고 코드 리뷰에서 함께 갱신해야 합니다.

마지막으로, 글쓰기 능력주의의 그늘입니다. 문서 문화가 강한 조직에서는 글이 유창한 사람의 의견이 과대 대표될 수 있습니다. 특히 비원어민이 섞인 글로벌 팀에서 실재하는 문제입니다. 문서의 화려함이 아니라 논거의 품질로 평가하는 리뷰 규범, 그리고 AI 글쓰기 보조의 적극 허용이 현실적인 보완책입니다.

체크리스트

디자인 독 발행 전:

요약 3문장만 읽고도 무엇/왜/어떻게가 잡히는가
모든 "느리다/많다/어렵다"에 숫자가 붙어 있는가
비목표 섹션이 있는가
대안 비교 테이블에 기각된 대안의 장점이 적혀 있는가
열린 질문이 솔직하게 나열되어 있는가
리뷰 요청에 스코프와 마감이 명시되어 있는가
예상 읽기 시간이 10분을 넘는다면, 줄일 수 없는가

ADR 발행 전:

컨텍스트에 당시의 제약(인력, 시간, 기술)이 담겼는가
결과에 단점(감수하는 것)이 최소 하나 있는가
재검토 트리거가 명시되어 있는가
한 페이지를 넘지 않는가

마치며

코드는 컴퓨터를 설득하고, 문서는 사람을 설득합니다. 그리고 2026년에는 문서가 AI를 통해 코드까지 만들어냅니다. 글쓰기에 들이는 시간은 코딩 시간을 빼앗는 비용이 아니라, 코딩의 방향을 정하고 재작업을 없애는 가장 수익률 높은 투자입니다.

이번 주에 내린 기술 결정이 하나 있다면, 오늘 ADR 한 장으로 남겨보십시오. 15분이면 됩니다. 6개월 뒤의 누군가가 — 어쩌면 미래의 여러분이 — 그 한 장에 감사하게 될 겁니다.

참고 자료

Design Docs at Google (Malte Ubl): https://www.industrialempathy.com/posts/design-docs-at-google/
ADR 공식 홈 — Architectural Decision Records: https://adr.github.io/
Michael Nygard — Documenting Architecture Decisions: https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions
Google Technical Writing Courses: https://developers.google.com/tech-writing
GeekNews — 디자인 독 관련 토론: https://news.hada.io/
Hacker News — Design Docs at Google 토론: https://news.ycombinator.com/
AWS — Architecture Decision Records 가이드: https://docs.aws.amazon.com/prescriptive-guidance/latest/architectural-decision-records/welcome.html
GitHub — adr/madr 템플릿 저장소: https://github.com/adr/madr
Anthropic — Claude Code 메모리(CLAUDE.md) 문서: https://docs.anthropic.com/en/docs/claude-code/memory
Write the Docs — 테크니컬 라이팅 커뮤니티와 가이드: https://www.writethedocs.org/
Diátaxis — 문서 유형 분류 프레임워크: https://diataxis.fr/
37signals — Shape Up (피치 문서 작성법): https://basecamp.com/shapeup