설계 문서는 아이디어를 명확하게 소통할 수 있는 확장 가능한 방법입니다. 문서를 작성하는 과정에서 생각을 정리할 수 있고 약점도 드러날 수 있습니다. 아이디어를 문서화하는 작업이 항상 수월하지만은 않습니다. 유용한 설계 문서를 작성하려면 가장 중대한 변경사항에 집중하고 목표와 대상을 유념하면서 글쓰기를 연습하고 문서를 계속 업데이트해야 합니다.
표면적으로 설계 문서는 소프트웨어 컴포넌트의 동작 방식을 설명하는 정도로만 보일 수 있습니다. 그러나 설계 문서는 우리 개발자에게 생각할 시간을 주고 피드백을 받게 해주며 팀에 새로운 정보를 계속 제공하고 신입 엔지니어의 적응을 도우며 프로젝트 계획을 추진하는 데 도움이 되는 도구입니다. 설계 문서를 작성해야 하는 이유는 다음과 같습니다.
이유1: 우리가 모르는 것을 드러내는 방법
문제 영역을 탐구하면서 우리가 생각하는 바를 더 명확하게 정리할 수 있습니다. 또 다른 대안을 마주할 수도 있고, 본인이 생각한 문제와 실제 문제 사이의 차이점 역시 파악해볼 수 있습니다. 이 과정은 험난하지만 이를 통해 자신이 설계한 사항과 그 설계를 밀어붙였을 때의 트레이드 오프에 대해 더 명확하게 파악할 수 있습니다.
이유2: 설계를 문서화하면 피드백을 요청하기도 쉬워집니다.
문서는 많은 사람에게 공유할 수 있으며, 사람들도 각자 자신의 시간에 맞춰서 문서를 읽고 대응할 수 있습니다. 설계에 대한 지식을 공유하면 사람들이 시스템 동작에 대한 정확한 모델을 유지하는 데도 도움이 됩니다. 팀은 더 나은 설계를 만들고 향후 구현 방향을 설계할 수 있습니다. 긴급대응 온콜 엔지니어도 시스템이 어떻게 동작하는지를 정확하게 이해할 수 있습니다. 엔지니어들 또한 설계 문서를 통해 팀원들로부터 배울 수 있습니다.
이유3: 새로 합류한 엔지니어에게 기술적으로 명확한 온보딩 가이드를 제시할 수 있습니다.
설계 문서가 없다면 엔지니어는 코드를 읽거나 박스 다이어그램을 그리거나 현 상황을 이해하기 위해 시니어 엔지니어의 가르침을 얻으려 애써야 할 것입니다. 그보다는 설계 문서를 찾아 읽는 편이 훨씬 효율적일 수 있습니다.
이유4: 엔지니어링 관리자와 기술 리드는 설계 문서를 이용해 프로젝트에 대한 계획을 세울 수 있습니다.
많은 설계 문서에는 프로젝트를 완성하는 데 필요한 마일스톤이나 구현 단계가 실려 있습니다. 설계가 구체적으로 문서화돼 있으면 프로젝트에 여러 팀이 필요할 경우 다른 팀과의 조율도 수월해집니다.
당연한 이야기지만 설계 문서를 잘 작성하는 방법은 꾸준한 연습뿐입니다.
모든 설계 문서에 최적화된 하나의 템플릿은 존재하지 않습니다. 하지만 오픈 소스 설계 문서를 참고하면 주요 변경사항을 어떻게 문서화하는지를 엿볼 수 있습니다. 대표적으로 파이썬 개선 제안(PEP, Python Enhancement Proposals), 카프카 개선 제안(Kafka Improvement Proposals), 러스트 검토 요청(RFCs, Rust Request for Comments) 등이 있습니다.
만약 사용 중인 문서화 템플릿이 없다면 아래와 같은 구조를 활용해보도록 합시다.
- 개요
- 현재의 상태와 컨텍스트
- 변경(추가)해야 하는 이유
- 요구사항
- 고려할 수 있는 해결책
- 채택하려는 해결책
- 설계와 아키텍처
- 시스템 다이어그램
- UI/UX 변경
- 코드 변경
- API 변경
- 영속(persistence) 계층 변경
- 테스트 계획
- 롤아웃 계획
- 미결 사항
- 부록
해결하고자 하는 문제와 해결해야 하는 이유를 설명합니다. 변경에 대한 한문단 정도의 요약 내용과 함께, 다양한 분야의 독자가 참고할 수 있는 가이드를 제공합니다.
아키텍처를 기술하고 용어를 정의합니다. 만약 생소한 용어로 설명해야하는 부분이 있다면 간단하게라도 공용어로 한 번 풀어서 설명을 해주시길 바랍니다. 물론 가장 좋은 방향은 애초에 공용어를 활용하여 최대한 단순하게 서술하는 것입니다.
그리고 현재의 이슈 처리 방법에 대해서도 설명해봅시다. 우회책이 적용된 부분은 있는지? 그 방법의 단점은 무엇인지?
일반적으로 개발팀은 한 번에 감당할 수 있는 것보다 더 많은 프로젝트를 수행하는 경향이 있습니다. 따라서 특정 문제를 해결할 때는 꼭, 문제 해결 시 얻을 수 있는 가치는 무엇이고 왜 지금 해결해야하는지, 그리고 팀이 들이는 노력에 비해 얻는 이점이 무엇인지 서술해야 합니다. 그리고 이 이점은 비즈니스의 요구사항과 연관지어야 합니다. "메모리 사용량을 50%까지 줄일 수 있습니다." 라는 표현 보다는 "메모리 사용량을 50% 감소시킨다면 우리 소프트웨어 설치에 가장 걸림돌이었던 요소가 해결되어 더 많은 사용자를 모을 수 있습니다."가 훨씬 더 강력합니다. 다만 블러핑은 지양하시길 바랍니다.
해결책의 채택 여부를 결정하기 위해 반드시 필요한 조건을 나열합니다. 이 부분은 다음과 같이 하위 절로 나눌 수 있습니다.
- 사용자 요구사항: 이 절에는 대체로 요구사항이 많은 편입니다. 사용자 관점에서 바라보는 변경사항의 본질을 정의해봅시다.
- 기술 요구사항: 이 절에는 해결책이 반드시 만족해야 하는 요구사항을 나열합니다. 기술 요구사항은 주로 상호운용성 문제 또는 "반드시 MySQL을 스토리지 계층으로 지원해야 한다."거나 "애플리케이션 게이트웨이를 위해 반드시 오픈API 스펙을 제공해야 한다."와 같은 내부적인 가이드라인으로 인해 발생합니다. 서비스 수준 목표(SLO)도 여기에 정의할 수 있습니다.
- 보안 및 규제 요구사항: 이 절은 사용자 요구사항이나 기술 요구사항으로 여겨질 수도 있지만, 보안 관련 내용을 명확하게 논의하기 위해 별도 절로 분리해 제시하는 편이 좋습니다.
- 기타: 중요한 마감일, 예산, 기타 중요한 고려사항 등을 다룹니다.
문제를 해결하는 데는 일반적으로 여러 가지 방법이 있습니다. 이 절을 작성하는 것은 작성자 스스로가 독자의 입장에서 활용할 수 있는 도구로서의 기능을 가집니다. 즉 처음 떠오른 아이디어 외에 다른 대안이나 그 트레이드 오프에 대해 생각해보는 기회가 됩니다. 만약 잘못된 이유로 여러분이 특정 해결방안을 채택하지 않았다면 의견 제시자가 여러분의 오해를 바로잡아줄 수 있습니다. 이는 미처 여러분이 고려하지 않았던 다른 대안을 찾아줄 수도 있습니다.
여러분이 채택한 해결책을 서술하는 절입니다. 여기에는 개요 절보다 훨씬 상세한 내용이 들어가며 변경사항을 강조하는 다이어그램을 넣기도 합니다. 이 절과 뒤따르는 절에는 제안 사항이 여러 단계로 구성되는 경우 각 단계별로 해결책이 어떻게 개선돼 나가는지를 설명합시다.
문서의 대부분은 설계와 아키텍처에 대한 내용으로 채워집니다. 모든 기술 세부사항은 이 절에서 논의하게 됩니다. 활용할 핵심 라이브러리와 프레임워크, 구현 패턴, 자사의 관행에서 벗어난 내용 등 구현과 관련된 주요 상세 내용을 여기서 설명한다. 설계와 아키텍처에는 컴포넌트의 블록 다이어그램, 호출 및 데이터 흐름, UI, 코드, API, 스키마 목업 등이 포함돼야 한다.
시스템 다이어그램
주요 컴포넌트와 그 컴포넌트의 상호작용을 보여주는 다이어그램을 첨부하여 독자가 변경사항을 확인할 수 있도록 합시다. 물론 설명을 덧붙여야 합니다.
UI/UX 변경
만약 프로젝트가 사용자 인터페이스 변경에 대한 내용이라면 목업을 만들어서 첨부합시다. 목업을 이용하면 사용자 동작의 흐름을 서술할 수 있습니다. 만약 UI 컴포넌트에 대한 변경사항이 없다면 이 절에는 여러분이 생성할 라이브러리에 대한 개발자 경험을 설명하거나 여러분이 개발한 명령 줄 도구를 사용자가 이용하는 방안 등으로 채울 수 있습니다. 이 절의 목표는 변경된 부분에 대한 사용자 경험을 설명하는 것입니다.
코드 변경
구현 계획을 설명합니다. 어떤 기존 코드가 언제 어떻게 변경되는지를 집중적으로 설명하면 좋습니다. 새로 도입해야 할 추상화가 있다면 설명합시다.
API 변경
기존 API의 변경사항 및 새로이 제안된 API에 대해 문서화하는 부분입니다. 상/하위 호환성 및 버저닝에 대해서도 설명해야 합니다. API 제안에는 에러 처리에 대한 내용도 포함돼야 함을 명심합시다. API는 잘못된 입력, 제약 위반, 예기치 못한 내부 에러나 예외가 발생했을 경우, 유용한 정보를 제공해야 합니다.
영속 계층 변경
새로 추가하거나 수정할 스토리지 기술에 대해 설명합니다. 새로운 데이터베이스, 파일 및 파일시스템 레이아웃, 검색 인덱스, 데이터 변형 파이프라인 등에 대해 기술하면 됩니다. 모든 스키마 변경과 하위 호환성도 포함됩니다.
모든 테스트를 미리 정의할 필요는 없습니다. 그보다는 변경사항을 어떻게 검증할 것인지를 설명합시다. 테스트 데이터를 확보할 방법을 설명하고, 테스트해야 할 사용 사례를 짚어주며, 활용할 라이브러리 및 테스트 전략을 논의하고, 보안 요구사항이 충족됐는지 검증할 방법을 설명합시다.
복잡한 배포 순서 요구사항에 얽매이지 않을 전략을 서술합니다. 롤아웃을 제어하기 위해 사용할 기능 플래그를 문서화하고 8장에서 설명한 배포 패턴을 사용하지 여부에 대해서도 언급합시다. 변경사항이 제대로 동작하지 않는 경우 어떻게 감지해낼지, 그리고 문제가 발견됐을 때 어떻게 롤백을 수행할지 생각해보기 바랍니다.
설계에서 아직 해결하지 못한 질문의 목록을 명시적으로 기록합시다. 이는 독자들의 의견을 구하고 '알려진 미지(known unknowns)', 즉 지금까지 파악하지 못한 것이라고 알려진 사항들을 정리할 수 있는 좋은 방법입니다.
추가로 설명해야 할 내용을 부록에 기록합니다. 관련 업무나 더 읽을거리에 대한 추가 자료를 덧붙여도 좋습니다.
팀과 건설적으로 협업하면 더 나은 설계를 구현할 수 있습니다. 개발자는 완고한 성향이 강하기에 협업이 항상 쉽지는 않을 겁니다. 개발자의 피드백을 해석하고 압축해서 의미 있는 설계에 녹여내는 것은 결코 쉽지 않습니다. 따라서 팀의 설계 절차를 따르고, 일찍 자주 소통해서 혼선을 줄이며, 설계 논의를 통해 브레인스토밍을 진행하는 등의 방법으로 협업하면서 설계를 완성해야 합니다.
설계 리뷰 방식은 매우 다양하지만 그중에서도 가장 보편적인 패턴 두 가지는 아키텍처 리뷰 위원회와 의사 결정 요청 절차 입니다.
아키텍처 리뷰(architectural review)
좀 더 공식적이며 중요한 절차입니다. 설계는 반드시 운영이나 보안 팀 같은 다른 이해관계자에 의해 승인을 받아야 합니다. 설계 문서도 작성해야 하며 회의나 발표가 여러 번 진행될 수도 있습니다.
최종 승인을 받기까지 코딩을 미뤄선 안됩니다. 프로토타입과 개념증명 '스파이크'를 구현하는 데 시간을 들이면, 설계에 대한 확신을 높일 수 있으며 프로덕션으로 배포하기까지의 시간을 줄일 수 있습니다. 하지만 개념 증명을 넘어서는 수준까지 코딩하는 것 또한 금물입니다.
의사결정 요청(RFD, request for decision)
인터넷 협회에서 사용하는 **RFC(request for comment)**와 헷갈리지 않길 바랍니다. RFD라는 용어는 흔히 쓰이지 않지만 그 패턴은 상당히 널리 사용되고 있습니다. 이러한 절차는 의사 결정을 빠르게 내려야 할 때 팀 내에서 신속하게 수행하는 리뷰 절차입니다. 의사결정이 필요한 엔지니어는 간단한 버전의 설계 문서를 작성해서, 결정해야 할 사항을 서술합니다. 그러면 팀원들이 화이트보드에 그려가며 각자의 선택사항을 논의하고 서로 피드백을 제공하고 의사결정을 내립니다.
사람들에게 설계를 제안할 때는 정중하게 그리고 점진적으로 시도합시다. 정식 설계 문서를 다른 팀이나 기술 리드에게 처음 선보일 때는 실패할 수도 있음을 염두에 둡시다. 사람들마다 각자 시각이나 관심 분야가 다른데다 사전에 미리 언급된 적 없는 설계 문서를 갑자기 들이밀면 거부 반응을 보일 수도 있습니다.
그보다 처음 조사를 시작할 시점에 다른 팀과 기술 리드로부터 일찍이 피드백을 받아봅시다. 그러면 설계도 더 향상될 뿐 아니라, 다른 사람도 여러분이 하는 일을 인지해 설계에 참여할 수 있습니다. 또한 상황에 따라 이 사람들은 여러분이 하는 작업의 적극적인 지지자가 될 것입니다.
작업의 진행 상황을 사람들에게 계속 공유합시다. 업무 보고 회의와 스탠드업 회의에서 계속 업데이트 사항을 제공해야 합니다. 그리고 향후 변동사항으로 인해 영향을 받을 팀에 대해 미리 알려줍시다. 특히 지원, QA, 운영 팀이 영향을 받을 확률이 높습니다.
공유하기 위해서 꼭 공식적으로 일정을 잡아 진행할 필요는 없습니다. 점심 시간, 복도에서 또는 회의를 시작하기 전 가벼운 대화로도 충분하며 오히려 이런 방법이 더 나을수도 있습니다.
설계에 대한 논의는 문제 영역에 대한 이해, 지식 공유, 트레이드오프에 대한 고민, 더 견고한 설계 등에 도움이 됩니다. 이와 같은 브레인스토밍 세션은 비공식적이며 화이트보드를 이용해 자유로운 형태로 대화하는 시간입니다.
브레인스토밍 세션을 시작하기 전에는 문제, 범위, 설계 제안과 더불어 잠재적인 트레이드오프와 아직 해결되지 않은 질문 등 간략하게 회의 안건을 만들어보면 좋습니다. 안건의 목적은 자유로운 토론을 시작하기에 충분한 정보를 제공하는 것입니다.
브레인스토밍 세션 중에 회의 내용을 기록하는 것은 오히려 방해가 될 수 있습니다.
어떤 팀에서는 회의록을 작성하는 사람을 공식적으로 지정하기도 합니다.
자신의 설계 뿐만 아니라 팀의 설계 업무에도 참여해야 합니다. 마치 코드 리뷰처럼 설계에 참여하는 상황이 편치는 않을 수 있습니다. 본인보다 더 경험많은 개발자가 설계를 주도한다면 비교적 기여도가 낮을 수 있다고 생각할 수도 있습니다. 설계 문서를 읽고 브레인스토밍 회의에 참여하는 것이 불필요하게 여겨질 수도 있다. 그래도 참여해봅시다.
설계에 합류하게 되면 의견은 제안하고 궁금한 것은 물어봅시다. 코드 리뷰와 동일한 가이드라인을 따르면 됩니다. 물론 상대를 존중하는 태도로 소통해야 합니다.