잘 만든 design.md는 무엇이 다를까?
나는 얼마 전에 PR 리뷰에서 "이 구조로 왜 짰어요?"라는 질문에 제대로 답을 못한 적이 있다. 분명 나름의 이유가 있었는데, 그걸 기록해두지 않았더니 나조차 애매하게 기억하고 있더라. 그때 깨달았다. 코드는 남지만 '왜 이렇게 짰는지'는 기록하지 않으면 증발한다는 걸.
그래서 design.md, 흔히 말하는 설계 문서를 제대로 조사해봤다. 결론부터 말하면, 잘 쓴 설계 문서와 못 쓴 설계 문서의 차이는 화려함이 아니라 '무엇을 남기느냐'에 있었다.
회의록이랑 뭐가 다른데?
솔직히 처음엔 "그냥 슬랙에 정리해두면 되는 거 아냐?"라고 생각했다. 근데 찾아보니 이게 완전히 다른 물건이더라. 회의록이나 슬랙 스레드는 '결정된 사실'만 남긴다. 반면 좋은 design doc은 '왜 그 결정에 도달했는지'의 과정을 남긴다.
구글의 소프트웨어 엔지니어링 문화를 다룬 글(Design Docs at Google)을 보면, design doc은 코딩을 시작하기 전에 작성하는 비교적 가벼운 문서이지만, 핵심은 트레이드오프를 정직하게 드러내는 데 있다고 한다. 즉 "이 방법이 최선이었다"가 아니라 "이런 대안도 있었는데 이런 이유로 포기했다"를 기록하는 문서라는 거다. 이게 나중에 진짜 힘을 발휘한다. 6개월 뒤 새로 들어온 팀원이 "왜 이렇게 안 하고 저렇게 했어요?"라고 물었을 때, 그 문서 하나면 30분짜리 회의를 안 해도 된다.
좋은 설계 문서의 뼈대
구글 사례를 보면 잘 만든 design doc은 대략 이런 구조를 갖고 있다.
Context and Scope: 왜 이걸 만드는지, 범위는 어디까지인지
Goals and Non-goals: 이번에 하는 것과 명시적으로 안 하는 것을 구분
The Actual Design: 실제 설계 개요와 트레이드오프
Alternatives Considered: 검토했지만 채택하지 않은 대안들
Cross-cutting Concerns: 보안, 모니터링처럼 여러 영역에 걸치는 고려사항
여기서 나는 "Alternatives Considered" 항목이 제일 중요하다고 느꼈다. 이게 없으면 나중에 다른 사람이 이미 검토했다가 버린 방법을 또 제안하고, 팀은 같은 논쟁을 반복하게 된다. 시간 낭비의 8할이 여기서 나온다.
검토했지만 채택하지 않은 대안들
ADR과의 차이
근데 여기서 헷갈리는 개념이 하나 있다. ADR(Architecture Decision Record)이다. 조사해보니 둘은 목적이 다르다.
design doc은 프로젝트 하나를 통째로 다루는 종합 설계 문서라면, ADR은 "이 결정 하나"만 짧게 기록하는 1~2페이지짜리 카드에 가깝다.
(ADR 가이드) 큰 규모 프로젝트라면 design doc 안에서 여러 개의 크고 작은 결정들이 각각 ADR로 쪼개져 쌓이는 구조가 이상적이다. 둘 다 있으면 "전체 그림"과 "개별 결정의 역사"를 모두 챙길 수 있다.
실전에서 바로 써먹는 팁 3가지
분량에 겁먹지 말 것: 큰 프로젝트가 아니면 A4 한 장이면 충분하다. 구글도 "프로젝트에 맞는 형식으로 쓰라"고 강조한다. 규모에 안 맞게 억지로 길게 쓰면 아무도 안 읽는다.
코드나 스키마 전체를 복붙하지 말 것: 설계와 직접 관련된 부분만 남기고 나머지는 링크로 대체하는 게 낫다. 문서가 최신 코드와 어긋나는 순간 신뢰를 잃는다.
"안 하는 것"을 꼭 적을 것: Non-goals를 명시하면 나중에 "왜 이 기능은 없어요?"라는 질문에 문서 링크 하나로 답할 수 있다.
정리하면, 다음에 새 기능 설계할 때 회의 먼저 잡지 말고 이 구조로 문서 초안부터 한 장 써보는 거 어떨까.
잘 만든 design.md는 정답을 자랑하는 문서가 아니라 '고민의 과정'을 정직하게 남기는 문서다.
#design.md #설계문서 #ADR #아키텍처결정레코드 #개발문서화 #소프트웨어엔지니어링 #기술문서 #RFC #개발자생산성 #팀협업