SERIES설계문서 공부 노트 읽는 순서
구조 설계 문서: SDD와 Architecture Doc은 박스 그림이 아니다
·6 min read·116 views
SDDTechnical Design DocArchitecture DocC4arc42SEIGoogle Design Docs공부 노트설계문서
구조와 설계 문서는 “무엇을 만족해야 하는가”에서 “어떤 구조로 풀 것인가”로 내려간다. SDD, Technical Design Doc, Architecture Doc, HLD, LLD, C4, arc42, UML이 여기에 들어간다. 숫자로 포장하기보다, 재현 조건과 운영에서 고정한 규칙을 중심으로 적었다.
SDD가 커진 문제
md ## 처음에는 박스 그림이면 충분할 줄 알았다 SDD는 구현 상세를 모두 적는 문서가 아니다. 다음 질문에 답해야 한다. 이걸 한 장짜리 박스 그림에 모두 넣으면 아무것도 선명하지 않다. 더 좋은 방식은 view를 나누는 것이다. 이 문서가 실패하는 흔한 방식은 박스 그림 하나로 끝나는 것이다. 박스와 화살표는 도움이 된다. 하지만 왜 그 박스가 있어야 하는지, 어떤 책임을 맡는지, 어떤 대안을 버렸는지 없으면 그림은 오래가지 않는다. 특히 구조에서는 재현 조건을 같이 적어야 의미가 있었다. ```md - Context view: 사용자, 상담자, public desk, session room - Runtime view: 요청 생성부터 승인/보류/거절까지의 상태 전이 - Data view: 요청, 상태, 권한, 만료 시간 - Deployment view: Next.  ## 그림만으로 부족함이 선명해진 순간 ```md - Redis pub/sub는 구현이 단순하지만 메시지 영속성이 약하다. - PostgreSQL polling은 새 인프라가 필요 없지만 지연과 부하가 생긴다. - 이번 버전은 상태 변경 빈도가 낮고 운영 단순성이 더 중요하므로 PostgreSQL outbox와 짧은 polling을 선택한다. - 실시간성이 제품 핵심 지표가 되면 queue 또는 pub/sub로 전환한다. ``` IEEE 1016-2009는 SDD를 software design information을 기록하고 핵심 이해관계자에게 전달하기 위한 표현으로 설명한다. 이 표준은 현재 inactive-reserved 상태라 그대로 따라야 할 최신 표준처럼 말하면 안 된다. 그래도 SDD가 특정 다이어그램이 아니라 설계 정보를 기록하고 전달하는 그릇이라는 점을 이해하는 데는 유용하다. 예를 들어 PonsLink를 설명한다고 하자. 사용자가 보는 흐름은 request-first session desk다. 서버가 보는 흐름은 session state와 권한이다. 운영자가 보는 흐름은 요청 카드, 승인/보류/거절, 장애 대응이다. 보안 관점에서는 public desk, session token, 관리자 경계가 보인다. 이 문서에는 미래의 변경자가 읽을 수 있는 정보가 있다. 왜 지금은 단순한 구조를 골랐는지, 언제 바꿔야 하는지가 남아 있다. 설계문서는 예쁜 그림이 아니라 선택의 압축이다. 어떤 view가 필요한지 정하는 것부터 설계다. 참고: Google Design Docs — https://www.industrialempathy.com/posts/design-docs-at-google/ 구조를 설명할 때 서버/클라이언트/사용자 중 누구 문장으로 말하는지 먼저 고르면 논쟁이 줄었다. ## 구조 문서 경계 나누기 여기서 중요한 것은 alternatives considered다. 설계문서의 가치는 “무엇을 만들겠다”보다 “왜 이 구조를 골랐고 무엇을 포기했는가”에 있다. Google의 Design Docs 글은 Technical Design Doc을 더 실무적으로 설명한다. 좋은 design doc은 context and scope, goals and non-goals, actual design, alternatives considered, cross-cutting concerns를 담는다. 참고: SEI Views and Beyond — https://www.sei.cmu. ```md - Redis를 사용한다. - WebSocket으로 실시간 알림을 보낸다. - PostgreSQL에 저장한다. ## 책임 흐름이 바뀐 지점 arc42도 비슷하다. Introduction & Goals, Constraints, Context & Scope, Solution Strategy, Building Block View, Runtime View, Deployment View, Crosscutting Concepts, Architectural Decisions, Quality Requirements, Risks & Technical Debt, Glossary로 나눈다. C4 model은 System Context, Container, Component, Code라는 계층으로 소프트웨어 구조를 시각화한다. 처음부터 code level까지 내려갈 필요는 없다. 오히려 초반에는 context와 container만 제대로 그려도 팀의 오해가 많이 줄어든다. 아키텍처 문서는 여기서 더 넓어진다. SEI의 Views and Beyond는 architecture documentation을 views, styles, interfaces, behavior, rationale로 본다. 하나의 그림이 아니라 여러 관점이 필요하다는 뜻이다. SDD는 구현 상세를 모두 적는 문서가 아니다. 다음 질문에 답해야 한다. ```md - 어떤 요구사항을 풀기 위한 설계인가? - 주요 컴포넌트는 무엇이고 각자 어떤 책임을 맡는가? - 데이터는 어디서 생성되고 어디로 이동하는가? - 실패하면 어떤 경로로 복구하거나 중단하는가? - 어떤 대안을 비교했고 왜 지금 구조를 골랐는가? ``` 특히 구조에서는 재현 조건을 같이 적어야 의미가 있었다. '구조 설계 문서: SDD와 Architecture Doc은 박스 그림이 아니다'을 관통하는 질문은 이 섹션에서도 같았고, 답만 더 구체적이 됐다. 이걸 한 장짜리 박스 그림에 모두 넣으면 아무것도 선명하지 않다. 더 좋은 방식은 view를 나누는 것이다. 이 문서가 실패하는 흔한 방식은 박스 그림 하나로 끝나는 것이다. 박스와 화살표는 도움이 된다. 하지만 왜 그 박스가 있어야 하는지, 어떤 책임을 맡는지, 어떤 대안을 버렸는지 없으면 그림은 오래가지 않는다. ```md - Context view: 사용자, 상담자, public desk, session room - Runtime view: 요청 생성부터 승인/보류/거절까지의 상태 전이 - Data view: 요청, 상태, 권한, 만료 시간 - Deployment view: Next.js app, SQLite DB, reverse proxy, backup - Risk view: 공개 URL, 민감 정보, 관리자 접근, 로그 보존 ``` ```md - Redis pub/sub는 구현이 단순하지만 메시지 영속성이 약하다. - PostgreSQL polling은 새 인프라가 필요 없지만 지연과 부하가 생긴다. - 이번 버전은 상태 변경 빈도가 낮고 운영 단순성이 더 중요하므로 PostgreSQL outbox와 짧은 polling을 선택한다. - 실시간성이 제품 핵심 지표가 되면 queue 또는 pub/sub로 전환한다. ``` IEEE 1016-2009는 SDD를 software design information을 기록하고 핵심 이해관계자에게 전달하기 위한 표현으로 설명한다. 이 표준은 현재 inactive-reserved 상태라 그대로 따라야 할 최신 표준처럼 말하면 안 된다. 그래도 SDD가 특정 다이어그램이 아니라 설계 정보를 기록하고 전달하는 그릇이라는 점을 이해하는 데는 유용하다. 예를 들어 PonsLink를 설명한다고 하자. 사용자가 보는 흐름은 request-first session desk다. 서버가 보는 흐름은 session state와 권한이다. 운영자가 보는 흐름은 요청 카드, 승인/보류/거절, 장애 대응이다. 보안 관점에서는 public desk, session token, 관리자 경계가 보인다. 이 문서에는 미래의 변경자가 읽을 수 있는 정보가 있다. 왜 지금은 단순한 구조를 골랐는지, 언제 바꿔야 하는지가 남아 있다. 설계문서는 예쁜 그림이 아니라 선택의 압축이다. 어떤 view가 필요한지 정하는 것부터 설계다. 참고: Google Design Docs — https://www.industrialempathy. 여기서 중요한 것은 alternatives considered다. 설계문서의 가치는 “무엇을 만들겠다”보다 “왜 이 구조를 골랐고 무엇을 포기했는가”에 있다. ## 마치며 이 글에서 확인한 경계는 다음 변경의 기준으로 남겼다.