효과적인 소프트웨어 디자인 문서 작성법 — Google·Microsoft 출신 개발자의 실전 가이드

본문

Google, Microsoft, 그리고 자신이 창업한 회사에서 디자인 문서를 작성해온 Michael Lynch가 효과적인 소프트웨어 디자인 문서의 작성법을 정리한 글입니다. 저자는 좋은 디자인 문서가 잘못된 구현에 시간을 낭비하기 전에 중요한 결정을 미리 검토하게 해주며, 팀원 및 협업 팀 간의 설계 결정을 조율하는 최선의 수단이라고 주장합니다. 공개된 문서 중 만족할 만한 사례가 없다고 판단해, 실제로 개발 중인 웹 앱을 대상으로 한 예시 디자인 문서를 직접 작성해 함께 공개한 점도 특징입니다.

언제, 얼마나 써야 하는가

저자는 프로젝트가 복잡하거나 위험할수록 디자인 문서의 가치가 커진다고 설명합니다. 여러 사람이 협업하는지, 개발에 3개월 이상이 걸리는지, 수년간 프로덕션에서 운영될지, 팀 간 협업이 필요한지, 요구사항이 모호한지, 보안이나 법적 리스크처럼 설계 단계에서 막을 수 있는 치명적 위험이 있는지를 묻는 여섯 가지 질문을 제시하며, 하나라도 해당하면 작성할 가치가 있고 둘 이상이면 거의 확실히 가치가 있다고 봅니다. 문서의 분량은 한 장짜리 요약부터 다섯 팀의 승인이 필요한 50페이지 문서까지 다양하며, 코드 테스트량에 정답이 없듯 투자 규모도 팀의 목표와 리스크, 문화에 따라 달라진다고 지적합니다. 때로는 적정 투자량이 '0'일 수도 있다고 덧붙입니다.

무엇을 담아야 하는가 — '틀렸을 때의 대가'

모든 세부사항을 문서에 적으면 설계 단계에서 이미 구현을 끝낸 셈이 되어 문서의 목적이 사라진다고 경고합니다. 판단 기준은 단순합니다. '틀렸을 때의 대가가 얼마나 큰가'입니다. 예컨대 C++로 웹 애플리케이션을 만들다가 20만 라인을 작성한 뒤 Ruby on Rails가 더 나았음을 깨달으면 되돌릴 수 없지만, 기사 목록을 한 번에 100개 보여줄지 25개씩 '더 보기'로 나눌지는 몇 시간이면 고칠 수 있는 사소한 결정이므로 설계 수준의 고려사항이 아니라고 구분합니다.

디자인 문서의 구성 요소

저자는 모든 섹션이 항상 필요한 것은 아니며 필요한 부분만 선택하라는 전제 아래 구성 요소를 나열합니다. 제목은 'RecencyBank'처럼 짧고 목적이 드러나는 이름이 좋고 'Project Flying Silver Horse' 같은 장황한 이름은 나쁘다고 지적합니다. 목적(Objective)은 이해관계자 누구나 이해할 한 문장으로 첫 페이지에 배치하고, 배경(Background)은 문제와 이전 시도를 수치와 함께 설명합니다. 예시에서는 출시 당시 100ms였던 페이지 로딩이 3년 뒤 중앙값 600ms로 늘어났고, DB 조회가 로딩 시간의 80%를 차지하며 조회의 95%가 전체의 3% 행에 집중된다는 분석이 캐시 도입의 근거로 제시됩니다. 목표(Goals)는 구현 세부사항이 아니라 사용자·팀·회사에 주는 이득으로 표현하고, 비목표(Non-goals)로 범위를 명시해 오해를 방지합니다. 시나리오는 완성된 시스템의 실제 사용 장면을 그려주고, 다이어그램은 작성자의 머릿속 아키텍처를 리뷰어에게 전달하는 가장 빠른 방법이므로 Excalidraw, draw.io, Mermaid, D2처럼 수정 가능한 도구를 고르고 원본 링크를 남기라고 권합니다. 이외에도 용어집, 제약 조건, SLO, 모니터링·알림, 마일스톤별 타임라인, 인터페이스, 의존성·인프라, 보안, 프라이버시, 법적 고려사항, 로깅, 미해결 이슈(Open issues)와 해결된 이슈, 검토했지만 기각한 대안 등의 섹션을 각각 예시와 함께 소개합니다. 특히 의존성은 언어나 스토리지 백엔드처럼 바꾸기 어려운 것을 깊이 고민하고, 이메일 발송 서비스처럼 하루면 교체 가능한 것은 크게 걱정하지 말라고 조언합니다. 보안 섹션은 위협, 공격 표면, 신뢰 경계를 다루고, 미해결 이슈에는 문제와 선택지, 다음 단계를 기록하며, 해결 후에는 결정 요약과 원래 논의를 '해결된 이슈'로 옮겨 보존하라고 설명합니다.

Reddit 반응

• @u/Rain-And-Coffee (93+) — 예시 디자인 문서를 포함한 점이 좋고 읽기 쉽다는 평가입니다. 자신의 동료들은 복잡한 전문 용어에 의존하는 경향이 있는데 이 글은 그렇지 않다고 말합니다.

원문: Refactoring English / 번역·요약: Trawling