아날로그 리팩터 디오라마: 코드를 건드리기 전에 종이로 만드는 3D 코드베이스 지형

소프트웨어 팀은 대형 리팩터를 할 때 보통 화이트보드에 그린 다이어그램 몇 개와 막연한 불안감만을 가지고 시작하곤 합니다. 반면 건축가와 도시 계획가는 물리적이든 디지털이든 3D 모델 없이 도시 한 블록을 설계 변경하는 일을 거의 하지 않습니다. 매스(덩어리), 충돌, 시야를 미리 검토한 뒤에야 콘크리트를 붓기 시작합니다.

그들의 습관을 우리 쪽으로 가져오면 어떨까요?

이 글에서는 **아날로그 리팩터 디오라마(analog refactor diorama)**라는 아이디어를 소개합니다. 코드를 건드리기 전에 미리 만들어 보는, 코드베이스의 저해상도 물리적 3D 종이 지형입니다. 이 도구는 복잡성을 눈에 보이게 만들고, 설계 논의를 자연스럽게 유도하며, 대규모 리팩터의 리스크를 줄이는 데 놀랍도록 강력합니다.

왜 굳이 코드를 3D로 모델링할까?

건축에서 물리 모델이 널리 쓰이는 이유는 명확합니다.

공간 관계를 한눈에 드러내 준다.
시스템끼리 부딪히는 문제(예: 같은 공간을 차지하려는 설비)를 초기에 발견하게 해 준다.
이해관계자가 손으로 만지고 가리키고 질문하고 개선할 수 있는 공유된 실물 객체를 제공한다.

코드베이스도 사실 비슷한 속성을 가지고 있지만, 단지 눈에 잘 안 보일 뿐입니다.

큰 시스템은 이런 요소들로 구성됩니다.

모듈과 서비스: 도시의 건물과 비슷합니다.
인터페이스와 API: 도로와 다리입니다.
데이터 흐름과 의존성: 상하수도, 전력망 같은 인프라입니다.

이걸 머릿속이나 평면 다이어그램만으로 리팩터하려는 건, 스프레드시트만 가지고 도시를 설계하는 것과 비슷합니다. 물리 모델은 시스템의 형태를 마주하게 만듭니다. 어디가 크고 위험한지, 어디가 조밀하고 엉켜 있는지, 어디가 평평하고 비교적 안전한지 말이죠.

이 지점에서 아날로그 리팩터 디오라마가 등장합니다.

AEC 워크플로를 소프트웨어 리팩터에 대응시키기

건축·엔지니어링·시공(Architecture, Engineering, Construction, AEC) 분야에서 3D 모델링 워크플로는 단지 보기 좋은 비주얼을 만드는 용도가 아닙니다. 소프트웨어 작업에도 놀라운 정도로 잘 대응되는, 매우 실질적인 목적을 가지고 있습니다.

1. 매스 스터디(Massing Study) → 상위 아키텍처

건축가는 먼저 **매스 스터디(massing study)**로 시작합니다. 건물의 부피와 배치를 나타내는 단순한 블록들이죠. 세부 디테일은 없고, 큰 덩어리만 존재합니다.

소프트웨어에서 이에 해당하는 것은 고수준 시스템 뷰입니다.

서비스, 도메인, 바운디드 컨텍스트는 큰 블록이 됩니다.
이들 사이의 관계(호출, 데이터 흐름)는 단순한 연결선으로 표현합니다.

이게 디오라마의 첫 번째 버전입니다. 서비스나 서브시스템 이름이 적힌 종이 박스를 크게 만들어 보드 위에 배치합니다.

2. 클래시 디텍션(Clash Detection) → 의존성·충돌 탐지

AEC 팀은 3D 모델을 통해 **클래시 디텍션(clash detection)**을 수행합니다. 파이프, 덕트, 보(beam)가 물리적으로 불가능한 방식으로 서로 교차하는 지점을 찾는 작업입니다.

코드베이스에서 이런 ‘충돌’은 다음과 같습니다.

순환 의존
서로를 동시에 의존·오케스트레이션하는 서비스
팀 간 경계를 가로지르는 공유 가변 상태나 강한 결합

디오라마에서 이런 관계를 교차하거나 겹쳐지는 연결선으로 표현하면, 문제가 되는 관계가 불편할 정도로 눈에 띄게 됩니다.

3. 시각화 → 영향도 분석 & 리스크 맵핑

3D 시각화는 건축가와 이해관계자가 건물이 지어지기 전에 그 공간이 어떻게 느껴질지 이해하게 도와줍니다.

소프트웨어에서 디오라마를 사용하면 다음을 시각화할 수 있습니다.

특정 모듈 변경의 영향 반경
많은 의존성이 몰려 있는 위험 지형
점진적으로 지형을 옮겨 가는 마이그레이션 경로

추상적인 의존성 그래프 대신, 리팩터의 흐름을 손으로 짚어가며 설명할 수 있는 물리적 지형을 얻게 됩니다.

LOD(Level of Detail): 코드 지형을 확대·축소하는 법

AEC 모델에는 LOD(Level of Detail, 상세 수준) 표준이 있습니다.

낮은 LOD – 단순한 형상, 대략적인 매스
중간 LOD – 방, 주요 구성요소, 핵심 시스템
높은 LOD – 부품, 설비, 시공 디테일까지 세밀한 표현

코드 디오라마에도 같은 개념을 적용할 수 있습니다.

LOD 1: 시스템과 도메인

가장 거친 수준에서는 다음을 표현합니다.

주요 서비스 (예: Billing Service, User Service, Search Service)
핵심 데이터 저장소 (예: CustomerDB, Event Log)
주요 통신 경로 (예: REST, 메시지 버스, 직접 DB 접근)

각 구성요소를 두꺼운 종이나 골판지 큰 블록으로 만들고, 표현은 최대한 단순하게 유지합니다.

LOD 2: 모듈과 서브시스템

전체 지형을 잡았다면, 예를 들어 Billing처럼 중요한 영역을 확대합니다.

그 서비스를 여러 모듈로 나눕니다. (예: Invoice Generation, Payment Gateway, Tax Calculation)
부모 블록 위나 안에 더 작은 블록을 쌓아 올립니다.

이렇게 하면 수직 계층 구조가 생기고, 복잡성이 어떻게 조직되어 있는지 드러납니다.

LOD 3: 컴포넌트와 핫스팟

심층 리팩터를 계획하고 있는 영역이라면 한 단계 더 들어갑니다.

핵심 클래스, 어댑터, 함수형 컴포넌트를 모델링합니다.
공용 라이브러리, 횡단 관심사, 까다로운 오케스트레이션을 표현합니다.

이 상세 수준이 전체에 다 필요하진 않습니다. 실제 변경이 클 영역에만 적용하면 됩니다. LOD 개념 덕분에 디오라마가 과도하게 비대해지는 것을 막을 수 있습니다.

메트릭을 물리적 형태로 바꾸기

디오라마가 단순한 장난감에 그치지 않으려면, 실제 코드 메트릭을 직접 연결해야 합니다.

실용적인 매핑 예시는 다음과 같습니다.

높이: 사이클로매틱 복잡도

각 블록의 높이를 **사이클로매틱 복잡도(cyclomatic complexity)**나 유사한 복잡도 메트릭에 대응시킵니다.
더 높은 건물 = 분기·의사결정 경로가 많은 함수, 클래스, 모듈입니다.

결과:

핫스팟이 지형의 마천루처럼 솟아오릅니다.
어디에 신중한 리팩터나 추가 테스트가 필요한지 바로 눈에 들어옵니다.

바닥 면적: 크기 또는 범위

블록의 바닥 면적을 코드 라인 수(LOC), 함수 개수, 엔드포인트 개수 등에 대응시킬 수 있습니다.
낮고 넓은 건물 = 범위는 넓지만 로직은 단순한 모듈입니다.

결과:

완만한 구릉 지형과, 거대하고 퍼져 있는 ‘메가블록’을 쉽게 구분할 수 있습니다.

색·질감: 리스크와 소유권

색, 패턴, 질감을 활용해 다음을 표현합니다.

리스크 수준: 빨강 = 취약하거나 테스트가 거의 없음, 초록 = 테스트가 잘 되어 있음, 노랑 = 상태 불명
소유 팀: 각 팀·비즈니스 도메인마다 다른 패턴
기술 스택: 언어, 프레임워크, 런타임 별로 다른 색·재질

한 걸음 물러서서 보면 다음이 한눈에 들어옵니다.

어떤 팀이 가장 높은 ‘리스크 타워’를 소유하고 있는지
크로스팀 의존성이 어디에 몰려 있는지

아날로그 리팩터 디오라마 만드는 법 (Step by Step)

디자인 전공도, 화려한 도구도 필요 없습니다. 기본 준비물은 이 정도면 충분합니다.

색상·두께가 다양한 카드지나 두꺼운 종이
가위 또는 커팅 칼
테이프나 풀
마커 펜 또는 라벨 스티커
큰 보드(폼 보드나 도면용 보드 등)

1단계: 범위와 목표 정하기

구체적인 리팩터 목표를 정합니다. 예: “Billing을 User Service에서 디커플링하기”, “Search를 별도 바운디드 컨텍스트로 분리하기”.
실제로 수정되거나 영향을 받을 시스템 부분으로 범위를 제한합니다.

2단계: 코드베이스에서 데이터 수집

이미 쓰고 있는 도구에서 메트릭과 구조 정보를 가져옵니다.

의존성 그래프
사이클로매틱 복잡도 리포트
테스트 커버리지 리포트
아키텍처 문서에 정의된 모듈·서비스 경계

이 정량 데이터를 정성적인 물리 형태로 옮기는 작업입니다.

3단계: 고수준 지형 배치

주요 서비스와 데이터 저장소를 큰 블록으로 만듭니다.
실제 관계가 드러나도록 배치합니다. (예: 코어 도메인은 중앙, 서포팅 서비스는 주변부)
서비스 간 통신 경로는 실이나 얇은 종이 스트립으로 연결합니다.

4단계: 필요한 곳에만 상세 수준 추가

이번 리팩터에 포함되는 영역을 확대합니다.
부모 블록 위에 모듈·컴포넌트용 작은 블록을 더 쌓습니다.
복잡도에 따라 높이를 조절하고, 크기에 따라 바닥 면적을 조정합니다.

5단계: 리스크·소유권·제약 조건 인코딩

리스크가 큰 컴포넌트나 테스트 커버리지가 낮은 부분을 색으로 표시합니다.
팀 소유권과 기술 스택 경계를 마킹합니다.
변경할 수 없는 3rd-party 시스템 등은 가장자리에 **‘접근 불가 존(no-go zone)’**으로 표시합니다.

6단계: 3D로 리팩터 워크스루 하기

이제 팀을 한 자리에 모읍니다.

디오라마를 보면서 현재 상태를 설명합니다.
목표 상태를 제안합니다. 블록을 옮기거나, 높이를 낮추거나, 붙어 있는 구조를 떼어내 보세요.
마이그레이션 단계를 계획합니다. 오늘의 지형에서 목표 지형까지, 어떻게 안전한 단계로 나눌지 논의합니다.

필요하다면 중간 단계별 디오라마를 추가로 만들어, 점진적 마이그레이션 경로를 시각화할 수도 있습니다.

왜 또 다른 다이어그램이 아니라, 아날로그여야 할까?

“그냥 디지털 3D 툴이나 더 고급 다이어그램 앱 쓰면 되지 않나?”라는 질문이 나올 수 있습니다.

아날로그에는 의외의 장점이 있습니다.

촉감이 대화를 바꾼다. 사람들이 블록을 직접 옮기고 공간을 협상하며, 실험을 해 봅니다. 키보드를 잡은 한 사람이 설명하는 시간이 아니라, 모두가 참여하는 공동 설계 세션이 됩니다.
적절한 마찰이 집중을 돕는다. 자르고 붙이는 데 손이 많이 가기 때문에, 진짜 중요한 부분만 모델링하게 됩니다. 이 제약 덕분에 모델이 더 명료해집니다.
툴 장벽이 없다. 가위와 종이는 PM, 디자이너, 엔지니어 누구에게나 익숙합니다.
공유된 멘탈 모델을 유지해 준다. 작업 공간 어딘가에 실제로 놓여 있는 물리 아티팩트는, 리팩터를 계속 눈에 보이게 하고 현실감 있게 유지해 줍니다. 금방 잊히는 Confluence 페이지와는 다릅니다.

목표는 정밀한 모델링이 아니라, 공유된 이해와 더 나은 의사결정입니다.

결론: 땅을 파기 전에 지형부터 보라

분명한 머릿속 지도 없이 거대한 코드베이스를 리팩터하는 건, 최신 도면도 없이 도시 지하에 터널을 뚫는 것과 비슷합니다. 운 좋게 끝낼 수도 있지만, 중간에 치명적인 뭔가를 건드릴 가능성도 매우 큽니다.

건축에서 차용한 아이디어—물리 모델, LOD, 클래시 디텍션—와 소프트웨어 메트릭을 결합하면, 아날로그 리팩터 디오라마는 여러분에게 다음을 제공합니다.

복잡성이 실제로 솟아 보이는 3D 지형
리팩터를 계획하고 커뮤니케이션하는 협업 도구
코드를 건드리기 전에 다양한 옵션을 안전하게 탐색해 보는 방법

다음에 팀이 거대한 리팩터를 앞두고 있다면, 바로 브랜치를 파고 IDE를 여는 충동을 조금만 참아 보세요. 카드지를 챙기고, 메트릭을 출력해서, 먼저 코드베이스를 하나의 지형으로 만들어 보세요.

지형이 눈에 선명해지는 순간, 깔끔한 리팩터로 가는 경로는 의외로 자연스럽게 드러질지도 모릅니다.