내부 공유용 정의서, 거짓말하지 않는 문서 만들기 - 두 개의 아키텍처 정의서 ep.06

문서가 거짓말을 하는 것은 게을러서가 아니다. 거짓말하기 쉽게 만들어졌기 때문이다.

여기까지 드라이버, 뷰, 결정, 횡단 관심사를 모았습니다. 이제 첫 번째 결과물, 내부 공유용 정의서를 완성합니다. 과제는 하나입니다. 두 번째 죽음, 거짓말을 막는 것. 의지가 아니라 구조로 막아야 합니다.

거짓말은 어디서 자라는가

내부 문서가 거짓말이 되는 과정은 단순합니다. 코드는 매일 바뀌는데, 문서는 가끔 손으로 갱신됩니다. 그 주기의 차이만큼 간격이 벌어지고, 그 간격이 거짓말입니다.

코드와 문서의 갱신 주기 차이로 거짓말의 간격이 자라는 그림. 가로축은 시간, 세로축은 실제 시스템과의 거리다. 검은 실선인 코드는 계단처럼 꾸준히 올라간다. 틸색 점선인 문서는 수동 갱신 시점에만 코드 높이로 올라서고 그 사이에는 평평하게 멈춘다. 첫 수동 갱신과 두 번째 수동 갱신 사이에는 작은 간격이, 두 번째 갱신 이후 갱신이 멈춘 구간에는 앰버색으로 크게 칠해진 거짓말의 간격이 자란다. 캡션은 갱신 주기가 코드를 못 따라가는 순간 간격이 자라며, 손으로 동기화하는 항목이 많을수록 거짓말이 빨리 자란다고 설명한다.

여기서 핵심 통찰이 나옵니다. 거짓말의 크기는 손으로 동기화해야 하는 항목의 수에 비례합니다. 그러니 거짓말을 막는 길은 의지를 다지는 것이 아니라, 손으로 동기화할 표면 자체를 줄이는 것입니다.

거짓말을 막는 네 가지 원칙

표면을 줄이는 방법은 네 가지입니다.

첫째, 천천히 변하는 것만 문서에 직접 씁니다. 드라이버, 결정, 시스템 경계처럼 자주 바뀌지 않는 것만 손으로 적습니다. 자주 바뀌는 것을 손으로 적는 순간 거짓말 후보가 됩니다.

둘째, 다이어그램은 코드로 그립니다. 그림 도구로 그린 다이어그램은 코드가 바뀌면 손으로 다시 그려야 합니다. 다이어그램을 코드로 그리기(diagrams-as-code) 를 쓰면 텍스트로 정의하고 빌드 시 렌더되므로, 적어도 버전 관리와 리뷰의 대상이 됩니다.

셋째, 결정은 지우지 말고 쌓습니다. ADR을 append-only로 운영하면, 과거 결정을 덮어쓰지 않고 상태만 바꿉니다. 덮어쓰지 않으니 “지금 문서가 과거와 다르다”는 거짓말이 생기지 않습니다.

넷째, 검증을 자동화합니다. 링크가 깨졌는지, 다이어그램이 빌드되는지, ADR 형식이 맞는지를 CI에서 검사합니다. 문서가 조용히 썩는 것을 기계가 막습니다.

무엇을 쓰고 무엇을 가리킬까

첫 번째 원칙을 실제 항목에 적용하면 이렇게 갈립니다. 천천히 변하는 것은 직접 쓰고, 빨리 변하는 것은 생성하거나 원본을 가리킵니다.

API 엔드포인트 목록을 문서에 직접 적으면, 엔드포인트가 추가될 때마다 거짓말이 시작됩니다. 대신 OpenAPI 명세를 가리키면, 명세는 코드에서 생성되므로 항상 최신입니다. 문서는 “엔드포인트 전체 목록은 여기를 보라”고만 말합니다. 가리키기만 하면 거짓말할 거리가 없습니다.

거짓말할 수 없는 구조

네 원칙을 적용하면 내부용 정의서는 이런 구조가 됩니다. 각 항목이 손으로 쓰는 것인지, 코드로 그리는 것인지, 생성·링크하는 것인지가 정해져 있고, CI가 전체를 지킵니다.

내부 공유용 정의서의 최종 구조 다이어그램. 한 저장소 안에 코드와 함께 두는 문서로, 일곱 개의 섹션이 각각 출처 태그를 단다. 1 목표와 드라이버는 손·안정, 2 시스템 경계(C4 L1)는 손·안정, 3 컨테이너·컴포넌트 뷰는 코드로 그림, 4 런타임 뷰는 코드로 그림, 5 결정 로그(ADR·append-only)는 누적 로그, 6 횡단 정책은 손·안정, 7 휘발 자료(API·스키마·의존성)는 생성·링크다. 아래에는 점선 테두리의 CI 검증 게이트가 있어 PR마다 자동 실행되며 다이어그램 빌드 성공·끊긴 링크 0건·ADR 형식 통과를 검사해 통과해야 머지된다. 범례는 틸색이 손·안정, 연한 틸색이 코드로 그림, 앰버색이 생성·링크 또는 누적 로그임을 알려준다.

이 구조의 핵심은 문서가 코드와 같은 저장소에 살고, 같은 PR 흐름을 탄다는 점입니다. 구조를 바꾸는 PR이 관련 다이어그램과 ADR을 함께 건드리지 않으면, 리뷰에서 걸립니다. 문서 갱신이 별도 작업이 아니라 변경의 일부가 됩니다.

완성: 내부 공유용 정의서

위 구조를 실제 목차로 옮기면 이렇습니다. 이것이 첫 번째 결과물의 골격입니다.

# 스폿(Spot) 아키텍처 정의서 (내부용)

1. 목표와 드라이버
   - 품질 속성 시나리오 (가용성/성능/확장성/보안/유지보수성/비용)
2. 시스템 경계 (C4 컨텍스트)
3. 구조 뷰
   - 컨테이너 다이어그램 (diagrams-as-code)
   - 주요 컴포넌트 뷰
4. 런타임 뷰
   - 동기 검색 / 비동기 요약 시퀀스
5. 결정 로그 (ADR, append-only)
   - ADR-001부터 ADR-006까지 (+ 이후 계속 추가)
6. 횡단 정책
   - 인증·인가 / 보안 / 관측성 / 에러 처리 / 캐싱 / 트랜잭션
7. 자동 생성 자료 (링크)
   - OpenAPI 명세 / DB 스키마 / 의존성 목록

> 이 문서는 코드와 같은 저장소에 있으며, CI가 링크·다이어그램·ADR을 검증한다.

거짓말을 닫다

ep.00에서 두 번째 죽음을 거짓말이라 불렀습니다. 코드는 변하고 문서는 멈춰서, 둘 사이의 간격이 사람을 속이는 것이었습니다.

내부용 정의서는 그 간격을 구조로 닫습니다. 손으로 동기화할 표면을 최소로 줄이고, 남은 것은 코드와 한 흐름에 묶어 기계가 지킵니다. 문서를 부지런히 갱신해서가 아니라, 거짓말할 자리를 없애서 거짓말을 막습니다. 거짓말은 이렇게 문서를 살려서 닫습니다.

다음 편은 정반대 방향입니다. SI 납품용 정의서는 살릴 수 없는 문서입니다. 그 죽음을 부정하지 않고, 오히려 인정함으로써 첫 번째 죽음인 화석 문제를 닫습니다.

참고 자료

Michael Nygard. (2011). Documenting Architecture Decisions.
Simon Brown. The C4 model — Tooling and diagrams as code. https://c4model.com
arc42. arc42 Documentation Template. https://arc42.org

다음 편 예고

ep.07 - SI 납품용으로 변환하기, 화석을 인정하는 문서 만들기

내부용 정의서를 SI 납품용으로 바꿉니다. 추적성, 버전과 승인 이력, 감리 검수. 살아 있던 문서를 특정 시점에 박제하되, 인수인계를 통해 유지보수팀의 살아있는 문서로 다시 심는 법까지. 시리즈를 닫는 마지막 편입니다.