현대 팀에게 아키텍처 문서가 중요한 이유
제 엔지니어링 커리어에서 최악의 분기에 대해 이야기해 보겠습니다.
2019년이었습니다. 저는 핀테크 스타트업의 코어 플랫폼 팀 테크 리드였습니다. 아름다운 마이크로서비스 아키텍처를 가지고 있었습니다 — 23개의 서비스, 이벤트 기반, 적절히 격리된 구조. 시스템은 원활하게 돌아갔습니다. 모든 것이 어떻게 작동하는지 정확히 알고 있었습니다.
그런데 세 가지 일이 연달아 일어났습니다:
- 수석 엔지니어 Sarah가 FAANG 회사로 이직했습니다
- 결제 통합을 구축한 Marcus가 경쟁사에 스카우트당했습니다
- 레거시 정산 서비스를 유일하게 이해하던 Lisa가 장기 병가에 들어갔습니다
6개월 만에 아키텍처에 대한 조직 지식의 절반이 문 밖으로 나갔습니다. 그리고 우리에게는 문서가 거의 없었습니다.
그 뒤로 몇 달간 우리 자신의 시스템을 역공학하는 시간이 이어졌습니다. 일주일이면 될 기능이 한 달이 걸렸습니다. 기존 코드가 어떻게 작동하는지 먼저 파악해야 했기 때문입니다. 특정 설계 결정의 미묘한 이유를 이해하지 못해 버그를 만들어냈습니다. 존재하는 줄 잊었던 제약 조건과 충돌하는 아키텍처 변경을 했습니다.
이 경험이 저를 문서화 회의론자에서 문서화 전도사로 바꿨습니다. 갑자기 문서 작성을 좋아하게 되어서가 아니라, 문서 없이 어떤 일이 벌어지는지 직접 목격했기 때문입니다.
문서 부재의 실제 비용
빈약한 문서가 얼마나 비용이 드는지 솔직히 이야기해 봅시다. 막연한 "중요합니다" 수준이 아니라, 제가 직접 목격한 구체적인 영향으로요.
온보딩 시간
그 핀테크에서 새 엔지니어가 생산성을 갖추기까지 4~6개월이 걸렸습니다. 똑똒하지 않아서가 아닙니다 — 뛰어난 인재들이었습니다 — 하지만 시스템을 이해하려면 수년간의 부족 지식을 삼투압처럼 흡수해야 했기 때문입니다.
문서에 투자한 후, 그 기간이 6~8주로 줄었습니다. 같은 수준의 엔지니어, 같은 시스템 복잡도. 유일한 차이는 지도가 있느냐 아니면 눈을 가리고 헤매느냐였습니다.
계산은 간단합니다. 연간 5명의 엔지니어를 채용하고 각각이 적응하는 데 3개월을 낭비한다면, 연간 15인월이 손실됩니다. 시니어 엔지니어 급여로 계산하면, 매년 25만 달러의 생산성 손실입니다.
의사결정 지연
문서가 없으면 모든 아키텍처 논의가 처음부터 시작됩니다.
"왜 여기서 RabbitMQ 대신 Kafka를 쓰죠?"
아무도 모릅니다. 두 시간 동안 논의합시다.
"서비스 A에서 서비스 B로 동기 호출을 추가할 수 있을까요?"
어떤 제약 조건이 있을 수도 있습니다. 하루 동안 조사합시다.
"결제 서비스가 다운되면 어떻게 되죠?"
좋은 질문입니다. 일주일 동안 코드를 추적해 봅시다.
아키텍처 맥락이 문서화되어 있으면 이 질문들에 답이 있습니다. 항상 즉각적인 답은 아니지만, 적어도 어디를 찾아봐야 하는지 알 수 있습니다. 의사결정 주기가 몇 주에서 며칠로 줄어듭니다.
장애 대응
새벽 2시. 호출기가 울립니다. 결제 플로우가 실패하고 있습니다. 당신은 온콜 엔지니어이고, 입사한 지 겨우 두 달입니다.
문서가 없으면 코드를 미친 듯이 grep하며 시스템이 불타는 와중에 이해하려 합니다. Slack 채널에 메시지를 보내며 결제 플로우를 아는 누군가가 깨어 있기를 바랍니다.
문서가 있으면 시스템 아키텍처를 열어 결제 플로우가 어떻게 작동하는지 보고, 관련 서비스를 식별하고, 문제를 어디서 찾아야 하는지 압니다. 이 정확한 시나리오에 대한 트러블슈팅 런북을 찾을 수도 있습니다.
저는 양쪽 다 겪어봤습니다. 평균 복구 시간의 차이는 극적입니다.
기술 부채 누적
반복적으로 목격한 패턴이 있습니다:
- 팀이 잘 설계된 시스템을 구축합니다
- 문서가 없거나 오래됩니다
- 새 엔지니어가 합류하고, 아키텍처를 이해하지 못합니다
- 아키텍처 원칙을 위반하는 기능을 추가합니다
- 기술 부채가 쌓입니다
- 결국 누군가 재작성을 제안합니다
재작성이 항상 필요한 것은 아닙니다. 종종 원래 아키텍처는 괜찮았습니다 — 단지 이해되지 않았을 뿐입니다. 문서가 없으면 모든 아키텍처 원칙은 팀 교체 한 번이면 잊혀집니다.
좋은 문서는 실제로 어떻게 생겼을까
문서를 위한 문서는 무용합니다. 아무도 읽지 않는 수백 페이지의 문서를 만드는 팀을 봤습니다. 핵심은 올바른 것을 올바른 방식으로 문서화하는 것입니다.
무엇이 아닌 왜를 문서화하세요
코드는 시스템이 무엇을 하는지 보여줍니다. 문서는 왜를 설명해야 합니다.
왜 MongoDB 대신 PostgreSQL을 선택했을까? 왜 이 서비스들은 합쳐지지 않고 분리되어 있을까? 왜 이 엔드포인트는 이 특정 형식을 받을까?
이런 "왜" 질문들의 답은 코드에 없습니다. 결정을 내린 사람들의 머릿속에 있습니다. 적어두지 않으면 그 사람들이 떠날 때 함께 사라집니다.
찾기 쉽게 유지하세요
최고의 문서도 아무도 찾지 못하면 쓸모없습니다. 우리 핀테크에도 실제로 약간의 문서가 있었습니다 — 어디에서도 링크되지 않은 Confluence 공간에 묻혀 있고, 검색 기능도 겨우 작동하는 상태로요.
문서는 다음과 같아야 합니다:
- 코드에서 링크됨 (README 파일, 문서 링크가 있는 코드 주석)
- 논리적으로 정리됨 (시간순으로 그냥 쌓이는 것이 아니라)
- 검색 가능 (모든 문서에 대한 전문 검색)
결국 우리는 아키텍처 문서를 리포지토리 자체로 옮겼습니다. 이제 코드 리뷰에서 나타나고, 코드와 함께 버전 관리되며, 현실에서 크게 벗어날 수 없습니다.
유지보수하기 쉽게 만드세요
업데이트하기 고통스러운 문서는 업데이트되지 않습니다.
이것이 정교한 UML 다이어그램에 회의적인 이유입니다. 처음 만들 때는 아름답고 6개월 후에는 절망적으로 오래됩니다. 업데이트하려면 전문 도구와 기술이 필요하기 때문입니다.
간단한 형식이 더 잘 작동합니다:
- 누구나 편집할 수 있는 Markdown
- 코드와 함께 있는 텍스트 기반 다이어그램 (Mermaid, PlantUML)
- 의도적으로 유지보수가 쉬운 C4 다이어그램
유지되는 문서는 유지하기 쉬운 문서입니다.
여러 대상을 고려하세요
다른 사람들은 다른 수준의 세부 정보가 필요합니다.
새 엔지니어에게는 시스템 개요가 필요합니다. 프로덕트 매니저는 서비스 경계를 이해해야 합니다. 아키텍트는 컴포넌트 관계를 봐야 합니다. 온콜 엔지니어에게는 운영 정보가 필요합니다.
C4 모델은 명시적으로 다른 줌 레벨을 제공하기 때문에 여기서 잘 작동합니다. 임원을 위한 시스템 컨텍스트, 아키텍트를 위한 컨테이너 다이어그램, 개발자를 위한 컴포넌트 다이어그램.
문서화를 시작하는 실용적 단계
제로에서 시작하는 경우, 제가 발견한 효과적인 접근 방식은 다음과 같습니다:
1주차: 시스템 컨텍스트
몇 시간을 투자하여 다음을 보여주는 다이어그램 하나를 만드세요:
- 하나의 박스로 된 시스템
- 누가 사용하는지
- 어떤 외부 시스템과 연결되는지
이것만으로도 가치가 있습니다. 경계를 설정하고 새 팀원에게 출발점을 제공합니다.
2주차: 컨테이너 다이어그램
시스템을 배포 가능한 조각으로 분해하세요:
- 서비스, 애플리케이션, 데이터베이스
- 어떻게 통신하는지
- 어떤 기술을 사용하는지
이것은 인프라 논의와 온보딩의 참조 자료가 됩니다.
3주차: 핵심 결정
가장 중요한 아키텍처 결정 세 가지를 문서화하세요:
- 무엇이 결정되었는지
- 왜 결정되었는지
- 어떤 대안이 고려되었는지
이것은 오래된 논쟁을 다시 하는 것을 방지하고 새 팀원이 시스템 형태의 근거를 이해하도록 도와줍니다.
앞으로: 워크플로의 일부
초기 문서화는 쉬운 부분입니다. 최신 상태를 유지하는 것이 더 어렵습니다.
문서화를 완료 정의의 일부로 만드세요. PR이 아키텍처를 변경하면 관련 문서를 업데이트해야 합니다. 이것은 자동으로 일어나지 않습니다 — 리뷰 규율과 문화적 헌신이 필요합니다.
일부 팀은 자동화된 검사를 추가합니다: README 파일이 존재하는지 확인하는 CI 작업이나, "이 변경이 아키텍처를 바꾸나요? 그렇다면 문서를 업데이트했나요?"라고 묻는 PR 템플릿 같은 것입니다.
문화적 도전
솔직히 말하겠습니다: 팀에게 문서화를 시키는 것은 종종 문화적 전쟁입니다.
엔지니어들은 일반적으로 문서보다 코드 작성을 선호합니다. 문서는 결과물이 아니라 부담처럼 느껴집니다. 마감이 다가오면 문서가 가장 먼저 잘립니다.
제가 발견한 도움이 되는 것들:
개인적으로 만드세요
새 엔지니어가 합류하면 온보딩하면서 배운 것을 문서화하도록 요청하세요. 그들은 새로운 눈으로 시스템을 보고 오래된 구성원이 놓치는 공백을 발견합니다. 게다가 자신이 있었으면 좋겠다고 생각하는 문서를 직접 만드는 것이니 직접적인 혜택을 받습니다.
문서화를 축하하세요
스프린트 리뷰에서 문서 업데이트를 언급하세요. 좋은 문서를 유지하는 엔지니어를 인정하세요. 문서화가 단지 용인되는 것이 아니라 가치 있다는 것을 보여주세요.
가능한 것을 자동화하세요
수동 문서 작성이 적을수록 실제로 이루어질 가능성이 높습니다. 코드에서 문서를 생성하는 도구를 사용하세요. AI를 사용하여 초안을 만드세요. 자동으로 업데이트되는 코드형 다이어그램을 사용하세요.
이것이 제가 Archyl을 만든 이유 중 하나입니다. 아키텍처 문서를 만들고 유지하는 수동 작업이 큰 장벽입니다. AI 지원 발견과 시각적 편집이 그 장벽을 낮춥니다.
고통에 연결하세요
사람들은 고통을 느낄 때 행동을 바꿉니다. 다음에 누군가 문서가 없어서 시스템을 이해하는 데 며칠을 보내면 지적하세요. "문서가 있었으면 한 시간이면 될 작업이었습니다."
결론
문서화는 흥미진진하지 않습니다. 우리 중 누구도 소프트웨어 엔지니어링에 뛰어든 이유가 아닙니다. 하지만 창작자보다 오래 살아남는 시스템과 유지보수 불가능한 엉망이 되는 시스템의 차이입니다.
제가 언급한 핀테크요? 그 고통스러운 기간 이후 문서에 진지하게 투자했습니다. 아키텍처 다이어그램, 의사결정 기록, 런북, 전부요. 약 6개월의 집중적인 노력이 걸렸습니다.
다음에 누군가 떠났을 때 팀에 거의 지장이 없었습니다. 그들의 지식이 머릿속이 아닌 시스템에 있었기 때문입니다.
이것이 문서화의 실체입니다: 지식 손실에 대한 보험. 그리고 모든 보험처럼, 필요하기 전까지는 비싸게 느껴집니다.
문서화 여정을 계속하세요: C4 모델 소개 | Architecture Decision Records | 사용자 플로우 문서화