구조 위에서 도메인 학습하기

들어가며

최근 나는 물류 풀필먼트 스타트업 콜로세움코퍼레이션의 엔지니어링팀에 합류했다.

새로운 회사에 들어가면 자연스럽게 코드부터 보게 된다. 프로젝트 구조를 살피고, 어떤 아키텍처를 쓰는지 보고, 화면과 API가 어떻게 연결되는지 따라가며 시스템의 윤곽을 잡는다. 이번에도 같은 방식으로 코드를 보 기 시작했지만, 코드만으로는 시스템이 잘 읽히지 않았다.

물류 시스템은 입고, 보관, 출고, 반품처럼 프로세스가 길고, 각 단계마다 상태와 데이터가 복잡하게 얽혀 있었다. 기술적으로는 API 호출이나 상태 전이를 따라갈 수 있었지만, "왜 이런 구조로 설계됐는가?"는 코드만으로는 잘 보이지 않았다. 이 시스템을 제대로 이해하려면 기술보다 먼저 도메인 자체를 이해해야 했다.

첫 주는 공식 온보딩 전이라 비교적 자유롭게 시간을 쓸 수 있었다. 하지만 문서를 읽으면 용어가 낯설고, 코드를 읽으면 맥락이 비어 있었다. 팀 분위기를 아직 잘 모르는 상태에서 질문부터 쏟아내는 것도 조심스러웠다.

그래서 기다리기보다, 먼저 혼자서 파악할 수 있는 만큼 파악해보기로 했다. 이때 정리한 방식이 5L Framework (Learn, Language, Logic, Lab, Loop)다.

이 글은 내가 첫 일주일 동안 낯선 물류 도메인과 WMS/OMS 시스템을 이해하기 위해 5L Framework를 만들고 적용한 기록이다.

5L Framework

5L Framework는 복잡한 도메인을 짧은 시간 안에 파악하기 위해 정리한 다섯 단계 학습 방식이다.

• Learn: 이 서비스가 어떤 문제를 해결하는지 이해한다.
• Language: 도메인 용어를 개별 단어가 아니라 프로세스 안의 구조로 익힌다.
• Logic: 데이터와 상태가 시스템 안에서 어떻게 흐르는지 파악한다.
• Lab: 실제 환경에서 시나리오를 실행하며 이해를 검증한다.
• Loop: 이 과정을 반복하면서 지식을 체화한다.

많이 보는 것보다 순서가 중요했다. 나는 맥락 → 용어 → 흐름 → 검증 → 반복의 순서로 도메인을 익혀보기로 했다.

1. Learn: 비즈니스 모델 이해

코드를 더 보기 전에, 먼저 우리 서비스가 어떤 문제를 해결하는지부터 정리했다.

콜로세움은 복잡한 물류 환경에서 셀러, 창고, 운송업체 사이의 단절을 줄이는 문제를 풀고 있었다. 중소 셀러는 재고 관리와 배송을 직접 감당하기 어렵고, 창고나 운송업체는 유휴 자산 문제를 겪는다. 콜로세움은 자체 물류센터나 차량을 직접 보유하기보다, 기존 창고와 운송 자원을 디지털 네트워크로 연결해 하나의 통합된 물류 허브처럼 작동하게 만든다.

이 관점을 먼저 잡고 나니, 이후에 보게 되는 입고/출고/재고 관리 기능들도 단순한 운영 화면이 아니라 물류 네트워크를 운영하기 위한 시스템 인터페이스에 가깝게 보이기 시작했다.

기능을 이해하기 전에 비즈니스가 어떻게 굴러가는지부터 알아야 했다. 그래야 코드에서 마주치는 구조도 조금씩 납득되기 시작했다.

2. Language: 도메인 언어 구조화

비즈니스 맥락을 잡고 나니, 그다음에는 낯선 용어들이 눈에 들어왔다. 처음에는 용어 사전처럼 하나씩 정리해볼까 했지만 금방 한계를 느꼈다. 단어만 따로 외워서는 실제 화면이나 코드에서 다시 연결되지 않았다.

그래서 나는 용어를 프로세스 중심으로 구조화했다.

예를 들면 이런 식으로 묶었다.

• 입고(Inbound): ASN, Receiving, Putaway
• 출고(Outbound): Picking, Packing, Shipment

이 방식은 용어를 "단어"로 외우기보다, 이 개념이 전체 흐름의 어느 단계에서 어떤 역할을 하는가로 이해하는 데 가까웠다.

예를 들어 Receiving은 단순히 입고를 받는 행위가 아니라, 실제 수량과 상태가 시스템에 반영되기 시작하는 구간으로 보였다. Putaway 역시 단어 하나가 아니라, 재고가 물리적 위치와 연결되는 단계로 이해됐다.

용어를 흐름 안에 배치하니, 낯선 단어들이 조금씩 서비스 구조 안에서 자리를 잡기 시작했다.

3. Logic: 데이터 흐름 추적

용어를 익힌 다음에는, 그 개념들이 시스템 안에서 실제로 어떻게 동작하는지를 봐야 했다. 이때는 UI보다 데이터 흐름과 상태 전이를 주로 봤다.

확인하고 싶었던 내용은 대략 이런 것들이었다.

• 어떤 이벤트가 발생하면 상태가 어떻게 바뀌는가
• 어떤 API를 통해 데이터가 이동하는가
• 서버의 상태가 클라이언트에서 어떻게 반영되는가
• 화면은 어떤 데이터와 조건에 의해 달라지는가

혼자 코드만 따라가면 시간이 오래 걸릴 것 같아, AI 에이전트를 활용한 코드베이스 문서화도 같이 진행했다.

먼저 Analyst를 통해 WMS와 OMS의 페이지 구조와 모듈 구성을 파악했다. 입고, 출고, 로케이션 관리, 재고 관리 같은 화면들이 어떤 엔티티와 상태를 중심으로 구성되는지 큰 지도를 잡는 데 도움이 됐다.

그다음 tech-writer를 통해 전체 아키텍처와 페이지별 세부 흐름을 정리했다. 여기서는 주문 생성부터 배송 완료까지 이어지는 상태 전이 흐름과 WMS/OMS 간 이벤트 기반 통신 구조를 시각적으로 볼 수 있었다.

예를 들어 창고주의 입고 처리 흐름을 보면, 입고 요청이 생성된 뒤 inboundBarcodeNo를 기준으로 실제 입고 작업이 진행되고, 이후 검수, 라벨 발급, 위치 지정, 적재 완료까지가 API 호출과 상태 전이 형태로 정리되어 있었다. 각 상태가 어떤 조건에서 바뀌는지까지 함께 보이니, 코드 조각으로는 흩어져 있던 흐름이 하나의 프로세스로 묶여 이해되기 시작했다.

마지막으로 UX Expert를 활용해 사용자 시나리오 단위로 문서를 정리했다. "사용자가 어떤 화면에서 무엇을 하고, 그때 시스템은 어떤 동작을 하며, 데이터는 어떻게 변하는가"를 중심으로 흐름을 따라갔다.

예를 들어 입고 담당자의 주요 시나리오는 아래처럼 이어졌다.

입고 목록 조회 -> WRO 스캔 -> 검수 -> 수량 입력 -> 위치 지정 -> 라벨 발급 -> 입고 완료

문서가 많이 생긴 것보다 더 좋았던 건, 이제 시스템의 흐름을 어느 정도 내 말로 설명할 수 있게 됐다는 점이었다.

4. Lab: 시나리오 기반 검증

문서를 읽고 흐름을 정리하는 것만으로는 부족했다. 이해했다고 생각한 것도 실제 환경에서 직접 보면 다르게 느껴질 수 있었다.

그래서 직접 프로젝트를 셋업하고 주요 시나리오를 하나씩 실행해봤다. API 요청과 응답을 확인하고, 상태 전이 시점에 디버깅 포인트를 걸고, 콘솔 로그를 보면서 데이터가 어떻게 이동하는지 추적했다.

이 과정에서 문서와 실제 서비스 동작이 맞아떨어지는 순간들이 있었다. 반대로 문서만 봤을 때는 명확하다고 생각했던 부분이 실제로는 애매하게 느껴지는 경우도 있었다.

막연했던 궁금증도 조금씩 구체적인 질문으로 바뀌었다.

예전에는 "이 페이지가 왜 이렇게 복잡하지?" 정도였다면, 이제는 "이 상태는 왜 이 시점에 전이되는지", "이 값은 왜 여기서 localStorage를 거치는지", "이 API 응답 구조는 어떤 운영 제약을 반영하는지"처럼 훨씬 해상도 높은 질문을 만들 수 있었다.

Lab 단계에서는 문서로 이해한 내용을 실제 동작으로 확인했다. 그 과정을 거치고 나서야 머릿속에 있던 흐름이 조금 더 선명해졌다.

5. Loop: 반복 학습과 체화

입고 페이지 하나를 어느 정도 따라갔다고 해서 도메인을 이해했다고 보기는 어려웠다. 오히려 그때부터가 시작에 가까웠다.

그래서 나는 같은 방식을 반복했다. 입고에서 시작해, 익숙해지면 출고로, 다시 재고 관리로 확장해나갔다.

반복할 때는 매번 비슷한 순서로 봤다.

1. 사내 문서로 배경을 먼저 본다.
2. 정리된 문서로 데이터 흐름을 파악한다.
3. 실제 시나리오를 실행해본다.
4. 의문점을 메모하고 다음 사이클에서 다시 본다.

같은 내용을 반복해도 매번 보이는 것이 달랐다.

처음에는 "이게 무슨 말이지?"에 가까웠다면, 두 번째에는 "아, 이래서 이렇게 설계했구나"가 되었고, 세 번째에는 "여기는 개선 포인트가 있겠는데?"라는 생각까지 이어졌다.

이 과정을 거치면서 도메인은 한 번에 완전히 이해하는 대상이 아니라, 반복 속에서 점점 입체적으로 익혀가는 대상에 가깝다고 느꼈다.

마무리

일주일 동안 5L Framework를 활용해 셀프 온보딩을 진행하면서, 막연했던 물류 도메인을 조금은 구조적으로 볼 수 있게 됐다.

처음 세웠던 목표를 돌아보면, 솔직히 완벽하게 달성했다고 보긴 어렵다. "물류 도메인의 핵심 프로세스를 80% 이상 이해하기"는 욕심에 가까웠다. 실제로 물류는 시스템 안에서 흐르는 데이터만으로 파악할 수 있는 영역이 아니었다. 현장의 작업 방식과 운영 노하우가 훨씬 큰 비중을 차지했고, 내가 이해한 건 아직 일부에 불과했다.

그래도 얻은 것은 분명히 있었다.

• 이후 합류할 사람들에게 도움이 될 최소한의 문서화를 남길 수 있었다.
• 코드를 볼 때 비즈니스 맥락이 전보다 조금 더 보이기 시작했다.
• 공식 온보딩에서 더 좋은 질문을 할 준비가 되었다.

5L Framework는 단순히 물류 도메인을 익히기 위한 방법으로만 남지 않았다. 나에게는 낯선 영역을 스스로 학습하는 방법을 구조화한 첫 시도에 가까웠다.

앞으로도 새로운 도메인을 만날 때마다, 나는 아마 비슷한 순서로 배우게 될 것 같다. 먼저 이 비즈니스가 어떤 문제를 푸는지 이해하고, 그 안에서 쓰이는 언어를 구조로 익히고, 데이터와 상태의 흐름을 추적하고, 실제로 실행해보며 검증하고, 다시 반복하는 방식으로.

아직은 물류를 안다고 말할 수는 없다. 하지만 적어도 이제는 무엇을 모르는지, 어디를 더 봐야 하는지는 조금 더 분명해졌다.

새로운 팀에 합류한 첫 주에 내가 얻은 것은 완벽한 이해가 아니었다. 대신 스스로 학습할 수 있는 리듬을 조금 만들 수 있었다.