Google의 디자인 문서 (Design Docs at Google) 번역

Google의 디자인 문서 (Design Docs at Google)

• 원본: https://www.industrialempathy.com/posts/design-docs-at-google/
• 디자인 문서를 작성할 때 참고하면 도움이 될 만한 글을 공유받았다.
• 자세히 읽어보니 실제로 실무에 적용하기에도 충분히 깊이 있는 내용이었고, 앞으로 디자인 문서를 작성할 때 여러모로 큰 도움이 될 것 같았다.
• 다만 개인적으로 이해를 돕기 위해 보충이 필요한 부분이 몇 가지 있었고, 기록의 목적도 겸해 해당 내용을 정리하고 일부 설명을 덧붙여 이 글로 남긴다.

Google의 소프트웨어 엔지니어링 문화에서 디자인 문서

Google의 소프트웨어 엔지니어링 문화의 핵심 요소 중 하나는 소프트웨어 설계를 정의하는 데 디자인 문서(design docs)의 사용이다.
이 문서들은 비교적 비공식적인 문서로서, 소프트웨어 시스템 또는 애플리케이션의 주요 저자 또는 저자들이 코딩 프로젝트를 시작하기 전에 작성한다.
디자인 문서는 고수준 구현 전략과 주요 설계 결정 사항들을 문서화하며, 특히 그러한 결정들에서 고려된 트레이드오프(trade-offs)에 중점을 둔다.

소프트웨어 엔지니어의 역할

소프트웨어 엔지니어로서 우리의 일은 단순히 코드를 생산하는 것이 아니라 문제를 해결하는 것이다.
구조화되지 않은 텍스트, 즉 디자인 문서의 형태는 프로젝트 수명 주기 초기에 문제를 해결하는 데 있어 더 간결하고 이해하기 쉬우며, 코드보다 높은 수준에서 문제와 해결책을 전달할 수 있다.

디자인 문서의 기능

디자인 문서는 단순한 초기 설계 설명을 넘어서, 소프트웨어 개발 수명 주기에서 다음과 같은 기능을 한다:

• 변경 시 설계 문제를 조기에 식별한다 (문제가 아직 저렴할 때)
• 조직 내 설계에 대한 합의를 달성한다
• 크로스 커팅(cross-cutting) 문제들을 고려하도록 보장한다
• 고급 엔지니어들의 지식을 조직으로 확장한다
• 설계 결정에 관한 조직적 기억을 구축한다
• 소프트웨어 설계자의 기술 포트폴리오에서 요약 아티팩트 역할을 한다

디자인 문서의 구성 (Anatomy of a design doc)

디자인 문서는 비공식적인 문서이므로 내용에 대한 엄격한 가이드라인은 없다.
규칙 #1은 해당 프로젝트에 가장 적합한 형태로 작성하라는 것이다.
그럼에도 불구하고 다음과 같은 구조가 매우 유용하게 자리 잡았다.

Context and scope (맥락과 범위)

이 섹션은 독자에게 새 시스템이 구축되는 환경과 실제로 어떤 것을 구축하는지에 대한 매우 대략적인 개관을 제공한다.
이것은 요구사항 문서가 아니다. 간결하게 유지하라!
목표는 독자들이 속도를 따라잡도록 하는 것이며, 일부 이전 지식은 가정할 수 있고 상세 정보는 링크로 제공할 수 있다.
이 섹션은 객관적인 배경 사실에 완전히 집중해야 한다.

Goals and non-goals (목표와 비목표)

Google의 Design Doc에서 Goals and Non-goals는 단순한 요구사항 목록이 아니라,
설계 문서 전체의 방향을 결정하는 핵심 섹션이다.
이 부분을 명확히 적어두면, 나중에 설계를 다시 보거나 수정할 때
"왜 이렇게 만들었는지"를 빠르게 복기할 수 있다.

Goals (목표)

Goals는 이 설계를 통해 반드시 달성하려는 핵심 결과를 의미한다.
즉, 이 시스템이 성공했는지를 판단하는 기준이다.

중요한 점은 Goals(목표)가

• 구현 항목의 나열이 아니라
• 설계 판단의 기준점이어야 한다는 것이다.

좋은 Goals는 다음 특징을 가진다.

• 설계가 해결하려는 본질적인 문제를 직접적으로 드러낸다.
• 추상적인 표현보다는 판단 가능한 형태로 작성한다.
• "있으면 좋은 기능"이 아니라, 없으면 실패한 설계가 되는 조건이다.
• 보통 3~5개 이내로 제한하는 것이 적절하다.

예를 들어,
"사용자 경험을 개선한다"보다는
"사용자가 핵심 작업을 3단계 이내로 완료할 수 있도록 한다"가
설계 논의에 더 직접적으로 사용된다.

Non-goals (비목표)

Non-goals는 이 설계에서 합리적으로 고려될 수 있지만, 의도적으로 제외한 것들을 의미한다.
이는 실패 조건이나 금지 사항이 아니라,
범위를 명확히 하기 위한 선언이다.

Non-goals를 명시하는 이유는 다음과 같다.

• 설계 범위가 끝없이 커지는 것을 방지한다.
• 리뷰 과정에서 나오는 "이것도 하면 좋지 않을까요?"라는 요구를 정리한다.
• 나중에 "왜 이 기능은 없나요?"라는 질문에 답할 수 있는 근거가 된다.
• 현재 설계의 한계와, 향후 확장 가능성을 분리해서 관리할 수 있다.

중요한 점은,
Non-goals는 "절대 하지 않는다"가 아니라
"이번 설계의 목표가 아니다" 라는 점이다.

Goals와 Non-goals의 관계

Goals와 Non-goals는 서로 독립적인 목록이 아니다.

• Goals는 설계의 집중 지점을 좁히고
• Non-goals는 설계의 경계를 명확히 긋는다

이 둘이 함께 있을 때, 설계 문서는 "무엇을 만들 것인가"뿐 아니라 "왜 이것만 만드는가"까지 설명할 수 있게 된다.

예시 1: 내부 문서 검색 시스템

Goals

• 사내 문서 저장소 전반을 대상으로 한 통합 검색 기능을 제공한다.
• 사용자가 검색 요청 후 2초 이내에 결과를 확인할 수 있도록 한다.
• 문서 접근 권한을 반영하여 권한 없는 문서는 검색 결과에 노출되지 않도록 한다.
• 문서 변경 후 5분 이내에 검색 인덱스가 갱신되도록 한다.

Non-goals

• 문서 품질 평가나 추천 알고리즘은 본 설계의 범위에 포함하지 않는다.
• 외부 검색 엔진과의 연동은 다루지 않는다.
• 문서 편집이나 협업 기능은 본 시스템의 목표가 아니다.
• 자연어 질문 기반의 의미 검색은 이번 설계에서 고려하지 않는다.

예시 2: 사용자 이벤트 수집 파이프라인

Goals

• 웹 및 모바일 애플리케이션에서 발생하는 사용자 이벤트를 중앙 시스템으로 안정적으로 수집한다.
• 이벤트 손실률을 0.1% 이하로 유지한다.
• 운영자가 기간 및 이벤트 유형 기준으로 집계 결과를 조회할 수 있도록 한다.
• 신규 이벤트 유형 추가 시 클라이언트 코드 변경을 최소화한다.

Non-goals

• 실시간 대시보드 제공은 본 설계의 목표가 아니다.
• 머신러닝 기반 행동 예측은 다루지 않는다.
• 이벤트 데이터의 장기 보관 정책은 본 설계에서 정의하지 않는다.
• 외부 파트너용 데이터 제공 API는 포함하지 않는다.

The actual design (실제 설계)

이 섹션은 개요로 시작한 다음 세부 사항으로 들어가야 한다.

디자인 문서는 소프트웨어를 설계하면서 내린 트레이드오프들을 적어 두는 장소이다.
즉, 맥락(사실), 목표 및 비목표(요구사항), 설계 문서는 솔루션을 제시하고, 왜 특정 솔루션이 이 목표를 가장 잘 만족시키는지 보여 주는 곳이다.
설계 문서는 형식화된 결과물을 만들기 위한 문서가 아니라, 문제를 정의하고 해결책을 탐색하는 사고 과정을 공유하기 위한 문서이다.
이 때문에 설계를 설명하는 방식은 프로젝트와 문제의 성격에 따라 달라질 수 있으며, 특정한 표현 방식이나 작성 규칙을 강제하지 않는다.

System-context diagram

많은 문서에서 시스템 컨텍스트 다이어그램이 매우 유용할 수 있다.
이러한 다이어그램은 시스템을 더 큰 기술 환경의 일부로 보여 주며, 독자들이 이미 익숙한 환경을 바탕으로 새로운 설계를 맥락화할 수 있게 한다.

APIs (API)

설계 중인 시스템이 API를 노출한다면, 해당 API 스케치를 문서에 포함하는 것이 보통 좋은 생각이다.
그러나 대부분의 경우 형식적 인터페이스나 데이터 정의 전체를 복사하여 붙여넣는 것은 피해야 한다. 이러한 정의는 종종 장황하고 빨리 구식이 되기 때문이다. 대신 설계 및 트레이드오프에 관련된 부분에 집중해야 한다.

Data storage (데이터 저장)

데이터를 저장하는 시스템의 경우, 시스템이 어떻게, 어떤 대략적인 형태로 데이터를 저장하는지 논의해야 한다.
API와 동일하게, 전체 스키마 정의를 그대로 복사하는 것은 피하고 설계 및 트레이드오프에 관련된 부분에 집중하라.

Code and pseudo-code (코드 및 의사 코드)

디자인 문서는 원칙적으로 코드나 의사 코드를 거의 포함하지 않는다.
이는 독창적인 알고리즘을 설명해야 하는 상황을 제외한 경우에 해당한다.
필요한 경우 설계의 구현 가능성을 보여주는 프로토타입에 링크하는 것이 적절하다.

Degree of constraint (제약의 정도)

설계 문서의 형태와 역할은,
해당 문제 공간이 얼마나 많은 제약을 가지고 있는가에 따라 크게 달라진다.

한쪽 극단에는 greenfield 소프트웨어 프로젝트가 있다.
이 경우 우리가 알고 있는 것은 오직 목표뿐이며, 어떤 솔루션을 선택할지는 비교적 자유롭다.
따라서 이러한 설계 문서는 폭넓은 가능성을 다루되, 그중에서 합리적이고 실행 가능한 해결책의 범위를 점진적으로 좁혀 가는 역할을 해야 한다.

반대편 극단에는, 사용 가능한 솔루션들이 이미 잘 정의되어 있으나 그것들을 어떻게 조합하여 목표를 달성할지는 명확하지 않은 경우가 있다.
이러한 상황에서 설계 문서는 가능한 여러 접근 방식을 나열하고, 각각의 트레이드오프를 분석하여 가장 적합한 해결책을 선택하는 데 초점을 맞춘다.

Alternatives considered (고려된 대안)

이 섹션은 유사한 결과를 합리적으로 달성할 수 있었던 대체 설계들을 나열한다.
각 설계가 만든 트레이드오프에 초점을 맞추고, 왜 최종적으로 선택된 설계가 해당 프로젝트 목표에 가장 적합했는지를 보여 주는 것이 중요하다.
선택되지 않은 솔루션에 대해 간결하게 설명하는 것은 괜찮지만, 이 섹션은 독자가 '왜 다른 옵션은 아닌가'에 대한 이유를 명확히 이해하도록 하는 데 매우 중요하다.

예시: 사용자 인증 세션 관리 방식

배경

웹 서비스 전반에서 사용자 로그인 상태를 유지하기 위한 세션 관리 방식을 새로 정의해야 하는 상황이다.
확장성과 보안, 운영 복잡도를 함께 고려해야 한다.

대안	설명	장점	단점	결론
서버 메모리 기반 세션 저장	각 애플리케이션 서버가 자신의 메모리에 사용자 세션을 저장	구현이 단순함 초기 성능이 빠름 추가 인프라 불필요	서버 재시작 시 세션 손실 확장 시 세션 공유 어려움 Sticky session 필요	확장성과 장애 대응 요구사항을 충족하지 못해 제외
중앙 집중형 세션 저장소 (Redis)	모든 서버가 중앙 Redis 인스턴스에 세션을 저장	서버 수와 무관한 세션 관리 세션 유지 및 만료 관리 용이 권한 변경 즉시 반영 가능	Redis 장애 시 영향 범위 큼 추가 운영 부담 네트워크 지연 발생 가능	고가용성 구성을 전제로 최종 선택
클라이언트 토큰 기반 방식 (JWT)	서버는 상태를 저장하지 않고 클라이언트에 서명된 토큰 전달	서버 무상태 구조 확장성 우수 마이크로서비스에 적합	토큰 폐기 어려움 권한 변경 즉시 반영 불가 유출 시 보안 위험	보안 및 즉시 무효화 요구로 제외

Cross-cutting concerns (크로스 커팅 고려사항)

이 섹션에서는 보안, 개인 정보 보호, 관찰성(observability) 등 여러 관점에서 설계가 어떤 영향을 미치는지와 어떻게 해당 문제를 다루는지 설명한다.
팀은 이러한 고려사항을 표준화해야 한다.
Google 프로젝트는 이러한 주제에 대해 전용 개인 정보 보호 설계 문서를 요구하며, 보안 및 개인 정보 보호 팀과 가능한 한 일찍 참여하는 것이 모범 사례이다.
중앙 설계 문서는 이들 전용 문서를 참조할 수 있다.

The length of a design doc (문서 길이)

디자인 문서는 충분히 상세해야 하지만 바쁜 사람들이 실제로 읽을 수 있을 만큼 짧아야 한다.
더 큰 프로젝트의 경우 대략 10–20 페이지가 적절한 분량처럼 보인다.
그보다 길다면 문제를 더 관리 가능한 하위 문제로 나누는 것이 좋다.
또한 1–3 페이지의 미니 디자인 문서를 작성하는 것도 가능하다.
간결하고 제한된 문제에 대해 동일한 단계(맥락, 목표, 설계 등)를 유지한다.

언제 디자인 문서를 쓰지 않는가 (When not to write a design doc)

디자인 문서를 작성하는 일은 분명한 오버헤드가 따른다.
따라서 언제 디자인 문서를 쓰는 것이 적절한지는, 그 문서가 드는 시간과 노력에 비해 실질적인 가치를 제공하는지를 기준으로 판단해야 한다.

핵심 판단 기준은 문제와 해결책의 복잡성이다.
문제가 이미 충분히 명확하고, 해결 방법 또한 거의 분명한 경우라면 디자인 문서를 작성하는 것은 큰 가치를 가지지 않는다.

특히 디자인 문서가 설계 상의 선택이나 트레이드오프를 다루기보다는, 구현 순서나 세부 동작을 설명하는 구현 매뉴얼처럼 보이기 시작한다면, 그 문서는 더 이상 디자인 문서로서의 역할을 하지 못한다.

이러한 경우에는 디자인 문서를 작성하는 대신, 바로 코드를 작성하는 편이 더 효율적이고 적절하다.

디자인 문서 작성 수명 주기 (The design doc lifecycle)

디자인 문서는 다음 단계로 진행된다:

1. Creation and rapid iteration (작성 및 빠른 반복)

   • 문서를 작성하고, 공동 저자와 함께 빠르게 반복한다.

2. Review (리뷰)

   • 디자인 문서의 리뷰 방식에는 정해진 하나의 형태가 없다.
   • 어떤 경우에는 가까운 동료와 문서를 공유하며 비공식적으로 의견을 받는 것만으로 충분할 수 있고, 또 다른 경우에는 팀 전체나 더 넓은 독자에게 문서를 공유하여 피드백을 받기도 한다.
   • 일부 팀에서는 디자인 문서를 바탕으로 시니어 엔지니어를 포함한 공식적인 리뷰 미팅을 진행하기도 하지만, 이러한 방식이 항상 필요한 것은 아니다.
   • 리뷰는 설계 품질을 높이는 데 큰 도움이 되지만, 동시에 시간과 노력이 드는 작업이기도 하다. 따라서 모든 설계에 대해 과도하게 무거운 리뷰 절차를 적용하면 오히려 개발 속도를 저하시킬 수 있다.
   • 중요한 것은 리뷰의 형식이 아니라 적절한 수준이며, 설계의 복잡성과 영향 범위에 맞는 방식으로 리뷰를 진행하는 것이다.

3. Implementation and iteration (구현 및 반복)

   • 문서가 안정되면 구현을 시작한다.
   • 설계가 현실과 충돌하면서 부족함이 드러나면 문서를 업데이트하는 것이 권장된다.

4. Maintenance and learning (유지보수 및 학습)

   • 디자인 문서는 시간이 지난 뒤에도 중요한 가치를 가진다. Google에서는 엔지니어가 새로운 시스템을 처음 맡게 되었을 때, 가장 먼저 던지는 질문이 종종 "이 시스템의 디자인 문서는 어디에 있지?" 이다.
   • 디자인 문서는 코드보다 먼저 읽히는 자료로서, 시스템이 왜 이런 구조를 가지게 되었는지, 어떤 선택과 트레이드오프가 있었는지를 빠르게 이해할 수 있게 해 준다.
   • 시간이 지나 코드가 변경되더라도, 디자인 문서는 당시의 사고 과정과 설계 의도를 담고 있는 기록으로 남아 새로운 엔지니어가 시스템을 이해하는 데 가장 접근하기 쉬운 출발점이 된다.

결론 (Conclusions)

디자인 문서는 가장 어려운 소프트웨어 문제를 해결하는 데 명확성과 합의를 얻는 데 훌륭한 방법이다.

• 잘못된 설계로 인해 코드 작성이 실패하기 전에 문제를 조기에 발견함으로써 비용을 절약한다.
• 물론 설계 문서 작성과 리뷰에는 시간이 들기 때문에, 적합한 프로젝트에 선택적으로 적용해야 한다.