끈끈한 아키텍처 정원: 작은 종이 다이어그램으로 거대 시스템 키우기

소개: 거대한 시스템일수록 작은 그림이 필요하다

대부분의 대규모 소프트웨어 시스템은 코드가 나빠서 무너지는 게 아닙니다. 사실은, 아무도 전체가 어떻게 맞물려 있는지 볼 수 없게 되면서 무너집니다.

Confluence 페이지는 금방 낡습니다. 형식적인 아키텍처 문서는 서가에 꽂힌 채 방치됩니다. 프레젠테이션용으로 한 번 그리고 버려지는 다이어그램도 많습니다. 시스템은 계속 진화하지만, 그 시스템을 시각적으로 이해하는 관점은 그대로 멈춰 있습니다.

이에 대한 의외로 간단한 해법이 있습니다: 작고, 일회용처럼 보이는 종이 다이어그램을 만들되, 실제로는 절대 일회용처럼 다루지 않는 것입니다.

아키텍처를 하나의 정원이라고 생각해 보세요. 프로젝트 킥오프 때 한 번만 조경해 두고 다시 손대지 않으면 잡초만 무성해집니다. 반대로, 작고 쉽게 고칠 수 있는 스케치를 몇 장 항상 곁에 두면, 시스템이 성장할 때마다 적절히 가지치기하고, 다시 심고, 재배치할 수 있습니다.

이 글에서는 “끈끈한(sticky) 아키텍처 정원”이 실제로 어떻게 작동하는지 살펴봅니다.

손으로 그린 종이 다이어그램에서 시작하기
그 스케치를 살아 있는, 추적 가능한 아티팩트로 키우기
다이어그램, 의사결정, 코드를 연결해 더 나은 리뷰 만들기
표준 모델링 언어(예: UML)를 공유된 시각 언어로 사용하기
가벼운 시각 도구를 리팩터링, 패턴, SOLID와 결합하기
정기적인 **시각적 가드닝(visual gardening)**으로 다이어그램을 현실과 맞춰 두기

작은 종이 다이어그램: 마찰을 최소화하는 시작점

화이트보드 세션이 생산적으로 느껴지는 이유는 빠르고, 함께 하며, 부담이 적기 때문입니다. 종이 다이어그램도 마찬가지지만, 여기에 휴대성과 지속성이 더해집니다.

왜 종이로 시작할까요?

마찰이 작다: 도구 설치도, 권한 요청도, 포맷 고민도 필요 없습니다. 그냥 그리면 됩니다.
심리적 허들이 낮다: “UML 싫어해요” 하는 사람도 네모와 화살표 정도는 기꺼이 그립니다.
신호 대 잡음비가 높다: 공간이 제한되어 있으니 정말 중요한 것만 담게 됩니다.

작은 다이어그램에 잘 어울리는 몇 가지 패턴이 있습니다.

컨텍스트 스케치 (한 페이지): 누가 이 시스템을 쓰는가? 외부 시스템은 무엇인가? 주요 경계는 어디인가?
핵심 컴포넌트 (1–2 페이지): 주요 서비스, 데이터베이스, 그 사이의 주요 흐름들
기능 하나, 다이어그램 하나: 새로운 기능을 구현하는 데 필요한 최소한의 구조

이 단계에서 다이어그램은 문서가 아니라 사고 도구로 다루세요. 진짜 가치는 이런 대화를 끌어내는 데 있습니다. “잠깐, 이 서비스는 요청을 어디서 검증하지?” 혹은 “왜 프런트엔드가 저 데이터베이스랑 직접 통신하죠?” 같은 질문 말입니다.

그리고 여기서 반전이 있습니다. 이 다이어그램들을 버리지 않는 것이 핵심입니다.

스케치에서 살아 있는 아키텍처 아티팩트로

대부분의 다이어그램이 수명을 다하는 이유는, 그것들이 정적인 산출물로 취급되기 때문입니다. 기능이 배포되면, 그림도 “끝난” 것으로 취급됩니다.

대신, 각 다이어그램을 살아 있는 아티팩트로 보세요.

명확한 목적이 있습니다. (어떤 질문에 답하기 위한 그림인지)
주인이 있습니다. (무언가 바뀌면 누가 업데이트할지)
쉽게 수정 가능해야 합니다. (무거운 도구나 포맷에 갇혀 있지 않게)

시간이 지나면, 이런 다이어그램은 **아키텍처 지식의 빵부스러기(단서)**가 됩니다.

우리는 어떻게 단순 모놀리식에서 여러 서비스로 나눠 왔는가?
다른 건 다 이벤트 기반으로 바꿨는데, 이 모듈만 남아 있는 이유는 무엇인가?
당시 우리가 그 이상해 보이는 결정을 내릴 때 어떤 제약을 따르고 있었나?

다이어그램이 작고 포커스가 명확하니, 업데이트도 충분히 할 만합니다.

새 엔드포인트를 추가했다면? 그 기능 수준 스케치를 업데이트하세요.
새 서비스 경계가 생겼다면? 컨텍스트 다이어그램에서 그 부분을 다시 그리세요.

각 업데이트는 작은 가드닝 액션입니다. 잡초를 뽑고, 가지를 다듬고, 새 묘목을 심는 일처럼요. 유지보수가 가볍고 지속적이기 때문에, 정원은 건강하게 유지됩니다.

아키텍처를 추적 가능하게: 다이어그램, 결정, 코드

아키텍처가 진짜 유용해지려면, 세 가지를 연결할 수 있어야 합니다.

시스템이 어떻게 생겼는지 (다이어그램)
왜 그렇게 생겼는지 (결정/의사결정 기록)
실제로 어디에 존재하는지 (코드)

이 추적 가능성(traceability)이 아키텍처를 “끈끈하게(sticky)” 만들어 줍니다. 개발자들이 실제 질문에 답을 얻기 위해 계속 다이어그램을 찾아보게 되는 상태입니다.

실천하기 쉬우면서 강력한 방법이 있습니다.

아키텍처 수준의 변경이 있을 때마다, 짧은 ADR(Architecture Decision Record, 아키텍처 결정 기록) 같은 의사결정 문서를 하나씩 남깁니다.
- Context: 어떤 문제를 해결하려는지
- Decision: 무엇을 선택했는지
- Consequences: 트레이드오프, 리스크, 영향
각 결정은 영향을 받는 구체적인 다이어그램을 참조합니다.
각 다이어그램은 관련되는 구체적인 코드 아티팩트(모듈, 서비스, 레포지토리)를 참조합니다.

링크 예시는 다음과 같습니다.

ADR 안에서: “새 서비스 경계는 service-split-v2.png 다이어그램을 참고하세요.”
다이어그램 위에: “ADR-017 구현: 빌링을 주문 관리에서 분리.”
코드(예: README나 주석)에서: “이 모듈은 다이어그램 system-context-2025-01의 ‘Billing Context’를 반영합니다.”

이렇게 되면, 다음과 같은 일이 가능합니다.

영향도 분석: “이 서비스 API를 바꾸면, 어떤 다이어그램과 결정들이 영향을 받나요?”
설계 리뷰: “이 새 이벤트 버스에 대한 다이어그램과 ADR을 보여 주세요.”
감사 및 점검: “이 레이어에서 관심사 분리를 어떻게 보장했나요?”

이제 각각의 산출물은 고립된 문서가 아니라, 시각 자료, 의사결정, 구현이 서로 엮인 직물 같은 구조가 됩니다.

공유된 시각 언어: 낙서에서 (가볍게) UML로

손으로 그린 네모와 화살표는 훌륭합니다. 하지만, 사람마다 다르게 해석하기 시작하는 순간 문제가 됩니다.

여기서 UML(또는 C4, SysML, ArchiMate 등) 같은 표준 모델링 언어가 유용해집니다. 무거운 모델링을 하자는 게 아니라, 공유된 시각 어휘로 쓰자는 뜻입니다.

UML 전체 스펙이 필요하지는 않습니다. 딱 필요한 만큼만 쓰면 충분합니다.

구조 표현에는 간단한 클래스 다이어그램 또는 컴포넌트 다이어그램
주요 상호작용에는 시퀀스 다이어그램
필요하다면, 어디서 무엇이 돌아가는지 나타내는 배포 다이어그램 정도

이 정도의 가벼운 표준화를 하면 이런 장점이 있습니다.

새 팀원이 합류해도, 예전 다이어그램을 별다른 설명 없이 읽을 수 있습니다.
서로의 다이어그램을 이어서 다듬고 확장해도 혼선이 줄어듭니다.
필요할 때 도구 간에 시각 자료를 옮기기도 수월해집니다.

실무적으로는 이렇게 하면 됩니다.

종이 위에 스케치를 할 때부터 UML 느낌이 나는 기호를 사용합니다. 컴포넌트는 박스, 호출은 화살표, 액터는 막대 인형 등.
시간이 지나도 가치가 있는, “살아남은” 다이어그램은 가벼운 도구로 디지털화합니다.
한 페이지짜리 **“비주얼 스타일 가이드”**를 만듭니다. 심볼의 의미, 이름 짓기 규칙, 디테일 레벨 기준 같은 것들입니다.

목표는 형식미가 아니라, 공유된 의미입니다.

코드 변경을 아키텍처 의도와 연결하기

아키텍처 정원은 익숙한 코드 레벨 개념과 연결될 때 훨씬 강력해집니다.

리팩터링: 모듈을 리팩터링(예: 클래스 추출, 인터페이스 도입)할 때, 해당 구조를 나타내는 다이어그램도 함께 갱신합니다.
디자인 패턴: 패턴(예: Strategy, Adapter, CQRS)을 적용할 때, 다이어그램에 그 패턴을 명시적으로 표시합니다.
SOLID 원칙: 다이어그램으로 책임의 위치, 의존성 방향, 추상화 계층을 눈에 보이게 만듭니다.

예를 들어:

큰 리팩터링 전에, 현재 설계와 목표 설계를 나란히 스케치합니다.
디자인 패턴을 도입할 때, “여기서 가격 정책을 분리하기 위해 Strategy 패턴 사용” 같은 작은 주석을 남깁니다.
SOLID를 지키려 할 때, 다이어그램에서 위반 지점을 강조합니다. (예: 여기저기서 화살표가 몰려드는 클래스, 관계없는 책임을 한데 안고 있는 서비스 등)

이렇게 하면 피드백 루프가 만들어집니다.

상위 수준의 의도가 시각적으로 잡힙니다.
코드 변경과 리팩터링이 그 의도에 맞게 수행됩니다.
변경된 현실을 반영해 다이어그램이 다시 업데이트됩니다.

개발자들은 점점 코드만이 아니라 아키텍처 관점으로 생각하게 됩니다. 아키텍처가 가끔 모여서 회의할 때만 꺼내 보는 게 아니라, 매일 눈에 보이고 손댈 수 있는 것이 되기 때문입니다.

시각적 가드닝: 가지치기, 리팩터링, 재배치

정원 비유가 유용한 이유는, 아키텍처 작업은 결코 끝나지 않는 일이기 때문입니다. 핵심은 유지보수를 작고 반복적인 일로 만드는 것입니다.

실천 가능한 “시각적 가드닝” 습관은 다음과 같습니다.

주간 가지치기(pruning): 팀 미팅에서 15–30분 정도만 투자해 핵심 다이어그램 1–2개를 같이 봅니다.
- 더 이상 유효하지 않은 요소를 제거합니다.
- 빠져 있는 컴포넌트를 추가합니다.
- 헷갈리거나 오래된 레이블을 수정합니다.
다이어그램이 지저분해지면 리팩터링합니다.
- 한 장에 다 우겨 넣은 그림은, 포커스가 뚜렷한 둘 이상의 뷰로 쪼갭니다.
- 레이아웃을 바꿔서, 핵심 흐름이 잘 드러나고 부수적인 복잡성은 뒤로 물립니다.
- 반복되는 구조는 공통된 “패턴 스케치”로 뽑아냅니다.
가끔은 전체 다이어그램 세트를 재구성합니다.
- 정말 완전히 옛날 이야기가 된 다이어그램은, 분명히 표시된 “History/Archive” 영역으로 옮깁니다.
- 자주 쓰는 다이어그램은 “첫 화면(front page)”에 올립니다.
- 기능, 도메인, 시스템 경계 등으로 태그나 폴더를 나눕니다.

목표는 “항상 100% 최신 상태”가 되는 게 아닙니다. 충분히 가까운 상태를 유지하는 것입니다. 그래야 다이어그램이 다음 상황에서 쓸모가 있습니다.

온보딩(신규 입사자 교육)
횡단 관심사 이슈 디버깅
대규모 변경이나 마이그레이션 계획 수립

개발자들이 “이 그림은 대체로 맞고, 고치기도 쉽다”는 걸 몸으로 느끼면, 실제로 그 그림을 보고 수정하려 듭니다.

이때 비로소 아키텍처는 끈끈해집니다.

끈끈한 아키텍처 실천을 만드는 법

“끈끈한(sticky)” 아키텍처 실천이란, 사람들이 일을 더 잘하기 위해 자꾸 되돌아오게 되는 체계를 말합니다.

그 지점에 도달하려면, 다음과 같이 시작해 볼 수 있습니다.

아주 작게 시작합니다. 중요한 기능이나 서비스마다 종이 다이어그램 한 장씩.
아키텍처에 영향을 주는 변경이라면, Definition of Done(완료 정의) 안에 “관련 다이어그램 업데이트”를 포함합니다.
**의사결정 기록(ADR 등)**을 가볍게라도 남기고, 각 결정에 대응되는 다이어그램을 연결합니다.
다이어그램이 일관되고 읽기 쉬워지도록, 최소한의 공통 표기법을 정합니다.
정기적인 가드닝을 일정에 박아 넣습니다. 짧게, 작은 개선을 꾸준히.

이를 위해 거대한 모델링 리포지토리나 전담 “아키텍처 팀”이 꼭 필요한 것은 아닙니다. 필요한 것은 다음뿐입니다.

펜과 종이 또는 포스트잇 몇 장
공유 폴더나 보드 하나
다이어그램, 결정, 코드를 이어 두려는 약간의 규율

시간이 지나면, 이런 작은 습관들이 풍부하고 탐색 가능한 아키텍처 정원으로 자라납니다. 새로 합류한 개발자는 이 정원을 거닐며 길을 익히고, 오래된 개발자는 불필요한 가지를 치고 새로운 나무를 심습니다. 그리고 시스템이 당연히 바뀌어 가는 만큼, 그에 대한 시각적 이해도 함께 바뀌어 갑니다.

바로 이렇게, 거대한 시스템은 자라납니다. 작은 종이 다이어그램에서 시작해, 꾸준히 손질받으며, “이게 도대체 어떻게 돌아가는지 아무도 모른다”라는 말을 듣지 않도록 적당히 끈끈한 상태로 유지되면서 말입니다.