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

들어가며

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

첫 일주일은 회사와 시스템, 사람을 이해하는 적응기였다.

업무 프로세스는 어떻게 돌아가는지, 어떤 프로젝트가 진행 중인지, 배포 환경은 어떤 구조인지, 팀 커뮤니케이션은 어떤 리듬으로 이루어지는지 하나씩 살폈다.

코드를 들여다보니, 물류 도메인의 특성상 입고–보관–출고–반품으로 이어지는 복잡한 데이터 흐름이 얽혀 있었다. 기술적으로는 파악이 가능했지만, “왜 이렇게 설계됐는지” 이해하려면 비즈니스 맥락이 필요했다.

즉, 도메인을 모르면 코드를 온전히 이해할 수 없었다.

공식 온보딩은 다음 주 예정이었기에 첫 주는 자유롭게 시간을 쓸 수 있었다.

하지만 문서를 읽으면 용어가 낯설고, 코드를 보면 맥락이 비어 있었다.

팀 분위기를 파악하지 못한 상태에서 무작정 질문하기도 조심스러웠다.

그래서 ‘기다리는 대신, 스스로 배우자’는 결론을 내렸다.

그 결과, 나는 도메인을 빠르고 체계적으로 학습하기 위한 나만의 방법론 5L Framework (Learn–Language–Logic–Lab–Loop)를 만들었다.

이 프레임워크는 복잡한 도메인을 단기간에 핵심만 파악하기 위한 다섯 단계 접근법이다.

각 단계는 다음과 같이 구성되어 있다.

• Learn: 비즈니스 모델과 도메인의 전체 맥락을 파악한다.
• Language: 도메인에서 사용하는 주요 용어와 데이터 구조를 익힌다.
• Logic: 데이터와 프로세스가 시스템 안에서 어떻게 흐르는지 이해한다.
• Lab: 실제 환경에서 시나리오 기반으로 직접 실험하며 체득한다.
• Loop: 반복 학습을 통해 지식을 체화하고 온보딩을 자동화한다.

1. Learn – 비즈니스 모델과 문제 구조 이해

도메인을 학습하기 전 가장 먼저 던진 질문은 “우리 서비스는 어떤 문제를 해결하고 있는가?”였다.

콜로세움은 복잡한 물류 환경에서 셀러·창고·운송업체 간 단절이라는 문제를 해결한다.

중소 셀러는 재고 관리와 배송을 직접 감당하기 어렵고, 반대로 창고나 운송업체는 유휴 자산 문제를 겪는다.

이를 해결하기 위해 콜로세움은 비자산형(Asset-Light) 풀필먼트 네트워크 모델을 구축했다.

자체 물류센터나 차량 없이, 기존 창고와 운송업체를 디지털 네트워크로 연결해 하나의 통합 허브처럼 작동시킨다.

또한 자체 개발한 AI 물류 SaaS ‘COLO AI’를 통해 창고 자동화, 경로 최적화, 생산성 분석을 지원하며 솔루션 사용료 및 컨설팅 수익을 창출한다. 단순한 물류 대행이 아니라 데이터 중심의 물류 플랫폼이라는 생각이 들었다.

이 단계에서 느낀 핵심은, 도메인을 이해하려면 먼저 ‘비즈니스의 논리’를 이해해야 한다는 것이다.

2. Language – 도메인 언어를 구조로 이해하기

단순히 도메인 용어를 나열한 '용어 사전'을 만드는 것보다, 도메인 프로세스 내부의 구조를 이해하는 방식으로 학습하는 게 더 효과적이라고 생각했다.

그래서 입고(Inbound) – 보관(Storage) – 출고(Outbound) – 반품(Return)으로 이어지는 물류 서비스의 주요 프로세스를 중심에 두고, 각 프로세스 안에서 반복적으로 등장하는 하위 개념들을 계층적 구조(레이어)로 정리했다.

예를들어

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

이 방식의 핵심은 용어를 '단어' 위주로 외우는 게 아니라 "이 용어가 어느 단계에서 어떤 역할을 하는지"를 시각적으로 구조화해서 학습하는 것이다.

아래는 입고 프로세스 내부의 하위 프로세스 용어를 시각화해서 플로우로 만든 예시이다.\

이 과정을 통해 단어 하나하나의 의미보다 그 단어가 서비스의 어느 흐름에 속하는지를 감각적으로 이해해볼 수 있었다.

3. Logic – 데이터와 프로세스의 흐름 이해하기

Language 단계를 통해 용어를 익힌 다음 단계에서 가장 중요한 건 이 데이터들이 서비스 안에서 실제로 어떻게 흐르는지(Logic)를 이해하는 것이었다.

단순히 용어를 아는 것만으로는 코드나 시스템을 이해할 수 없었다. 그래서 나는 데이터가 어떻게 이동하고, 어떤 이벤트로 상태가 전이되는지”를 중심으로 WMS와 OMS내부의 코드베이스를 보면서 데이터의 흐름을 파악했다.

내부 코드베이스를 빠르게 파악하기 위해 나는 BMAD-Method를 활용해 멀티에이전트 기반으로 문서화를 진행했다.

BMAD-Method는 AI 기반 애자일 개발 프레임워크로, Analyst(분석가), Architect(아키텍트), UX Expert(UX 전문가) 등 12개의 전문 AI 에이전트가 협업하여 소프트웨어 개발의 각 단계를 지원한다. 특히 레거시 코드베이스를 자동으로 분석하고 문서화하는 Brownfield 프로젝트 지원 기능에 도움을 많이 받았다.

나는 총 3개의 에이전트를 순차적으로 활용했다.

Analyst → tech-writer → UX Expert

1단계: Analyst - 각 페이지별 구조 파악

먼저 Analyst 에이전트(*document-project)를 활용했다. Analyst는 코드베이스를 탐색하며 프로젝트의 전체 구조를 파악하고, WMS와 OMS의 각 페이지별 모듈 구조를 분석했다. 입/출고 페이지, 로케이션 관리, 재고 관리 등 각 페이지에서 사용되는 엔티티 구조와 상태 머신 패턴을 발견했다.

2단계: Tech-writer – 전체 아키텍처 및 페이지별 아키텍처 파악

그다음은 tech-writer 에이전트였다.

이 단계의 목표는 “시스템이 실제로 어떻게 작동하는가”를 구조적으로 이해하는 것이었다.

tech-writer는 먼저 전체 시스템 아키텍처를 정리하고, Analyst가 만든 자료를 기반으로 각 페이지의 세부 구조를 단계적으로 분석했다.

이 과정에서 주문 생성부터 배송 완료까지의 상태 전이 흐름 그리고 WMS와 OMS 간의 이벤트 기반 통신 구조가 시각화되었다.

페이지마다 어떤 데이터가 어떤 경로로 이동하고, 어떤 API가 호출되며, 상태가 어떻게 변하는지를 시각적으로 보여주는 문서가 자동으로 생성되었고 그 결과물은 단순한 기술 명세가 아니라 매우 꼼꼼하게 잘 작성된 기획서와 가까웠다.

예를들어 창고주의 입고 처리 페이지를 문서화 해준걸 잠깐 언급을 해보면, 입고 요청이 생성되면 inboundBarcodeNo가 발급되고, 이를 기반으로 창고주는 /inbound/process 페이지에서 실제 입고 작업을 진행한다.

이후 검수 → 라벨 발급 → 위치 지정 → 적재 완료의 흐름이 일련의 API 호출과 상태 전이로 도식화되어 있었다.

각 상태(REQR → RECV → PROC → STOW)가 어떤 조건에서 전이되는지까지 표현되어 있어 복잡한 프로세스와 상태머신을 한번에 볼 수 있었다.

또한 tech-writer는 단순히 물류 프로세스 뿐만 아니라 FE단에서 발생하는 상태전이 (Tanstack Query, MobX, localStorage 등)구조를 함께 분석해 데이터가 서버에서 클라이언트로, 그리고 화면으로 전달되는 전 과정을 한눈에 보여줬다.

“서버에서 데이터를 불러와 상태를 갱신하고, 이 데이터가 화면에 어떻게 반영되는가”를 그대로 따라가기만 해도 시스템 전체 로직이 자연스럽게 이해됐다.

이 덕분에 복잡한 물류 시스템의 데이터 흐름을 기술 명세와 기획 관점에서 동시에 이해할 수 있었다.

위 이미지는 입고 페이지에 있는 셀러의 입고 신청 단계를 시각화 해준 모습이다.

3단계: UX Expert - 사용자 시나리오 생성

그다음 단계에서는 Architect의 산출물을 기반으로 UX Expert 에이전트를 활용했다. 이 에이전트를 통해 사용자의 실제 행동 흐름을 기반으로 시스템 사용 경험을 문서화했다.

예를 들어, 입고 담당자(창고주)의 하루 작업 과정을 중심으로 어떤 화면에서 어떤 액션이 일어나고, 그때 어떤 데이터가 흐르는지를 시나리오 단위로 정리했다.

이 에이전트의 문서 구조도 인상적이었다. 각 시나리오별로 사용자 액션 → 시스템 동작 → 데이터 흐름이 단계적으로 정리되어 있었고, 클라이언트와 서버 간의 상태 변화도 정리되어 있었다.

특히 입고 담당자의 주요 시나리오인

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

이 과정이 실제 코드와 UI 화면 흐름, API 호출, 데이터 구조까지 통합된 형태로 문서화되어 있었다.

이렇게 생성된 전체 문서는 Notion MCP를 이용해 자동으로 업로드되게 구축했다.

4. Lab - 실제 환경에서 시나리오 기반으로 학습하기

이제 문서로 이해한 내용을 실제로 검증할 차례였다. 프로젝트를 셋업하고 주요 시나리오를 직접 실행하며 API 요청·응답, 상태 전이, 데이터 흐름을 눈으로 확인했다.

디버깅 포인트를 찍고 콘솔 로그를 통해 데이터를 추적하면서 문서와 실제 서비스 동작이 어떻게 맞물리는지 학습했다.

이 과정에서 생긴 의문은 즉시 메모해 팀원에게 질문할 때 구체적으로 물어볼 수 있도록 정리했다.

결국 Lab 단계는 ‘이해’를 ‘실험’으로 전환시키는 과정이다.

Lab 단계를 통해 문서화한 것들을 실제 테스트 환경에서 직접 실행하고 검증하면서 실무에 바로 적용 가능한 지식을 학습할 수 있었다.

5. Loop - 반복하기

Lab 단계까지 거치면서 한 번의 사이클을 완료했지만, 진짜 중요한 것은 이 과정을 반복하는 것이었다. 입고 페이지로 시작해서 익숙해지면 출고 페이지, 재고 관리 페이지 순으로 같은 Learn - Language - Logic - Lab 사이클을 반복했다.

각 페이지마다

1. 사내 문서를 찾아보며 배경 파악
2. 에이전트가 생성한 문서를 읽으며 데이터 흐름 이해
3. 실제 시나리오 테스트하며 직접 체험
4. 의문점 메모하고 다음 사이클에서 더 깊게 파고들기

같은 내용이라도 반복해서 보면 새로운 것이 보였다. 첫 번째에는 "이게 뭐지?"였다면, 두 번째는 "아, 이래서 이렇게 설계했구나", 세 번째는 "이 부분은 이렇게 개선할 수 있겠는데?"로 생각의 흐름이 조금씩 발전했다.

Loop 단계를 통해 한 번에 완벽하게 이해하려 하지 않고 계속 반복하며 조금씩 깊이를 더해가는 과정에서 복잡한 물류 지식이 조금씩 머리속에 들어오는걸 느꼈다.

마무리

일주일 동안 5L Framework를 활용한 셀프 온보딩을 진행하며 막연했던 물류 도메인을 아주 조금은 이해 할 수 있었다.

처음 세웠던 세 가지 목표를 돌아보면

1. 물류 도메인의 핵심 프로세스를 80% 이상 이해할 것 → 입고, 출고, 재고 관리 등 주요 프로세스의 흐름과 용어를 파악했지만, 물류 도메인의 핵심 프로세스를 80% 이상 파악하는 건 솔직히 무리였다. 희성님께서 말씀해주신 것처럼, 물류는 시스템 내에서 흐르는 데이터보다 현장에서의 실제 작업과 운영 노하우가 훨씬 중요한 영역이었다. 내가 파악한 건 아주 극히 일부에 불과했다.
2. 이후 신규 입사자의 온보딩에 활용할 수 있도록 문서화를 체계화할 것 → 앞으로 합류할 팀원들에게 조금이나마 도움이 될 수 있게 최소한의 가이드를 만들어두었다. 그리고 이 문서는 컨플루언스에 업로드 해도 된다고 말씀해주셨다.
3. 이해한 도메인 지식을 바탕으로 실제 코드에 기여해볼 것 → 이제 코드를 보면 비즈니스 맥락이 살짝은 보이기 시작했다. 다음주부터 기여해볼 수 있을 것 같다.

5L Framework는 단순히 도메인을 학습하는 방법론을 넘어 스스로 학습하는 방법을 체계화하는 과정이었다. 앞으로도 새로운 도메인을 만날 때마다 이 프레임워크를 활용할 수 있을 것 같다.

다음 주 공식 온보딩 때도 이번 주 학습이 분명 도움이 될 것 같고 좋은 질문들을 던져볼 수 있을 것 같다. 무엇보다 빠르게 프로세스를 익혀서 팀에 기여하고 싶다.