지도가 없으면 길을 잃는다
컴포넌트가 16개가 됐을 때, 처음으로 그 느낌이 왔다.
"내가 만든 건데, 내가 모른다."
프로젝트가 커지면 생기는 문제
EP 04에서 context.md 얘기를 했다. 생각이 바뀌면 문서가 먼저 바뀌고, 문서가 바뀐 다음에 Claude Code를 부른다고.
근데 그게 다가 아니었다.
context.md는 무엇을 만들지에 대한 문서다. 근데 프로젝트가 커지면 다른 질문이 생긴다. 어디를 고쳐야 하는지.
채팅방 UI에 버그가 났다고 치자. 그 버그가 모바일 앱에 있는 건지, API 서버에 있는 건지, Pepper Core에 있는 건지 — 모르면 Claude Code한테 뭘 시켜야 할지도 모른다. 맥락 없이 "버그 고쳐줘"라고 하면 Claude Code가 엉뚱한 파일을 열기 시작한다.
그래서 PEPPER_MAP을 만들었다.
PEPPER_MAP — 신경계 지도
C01부터 C16까지. 컴포넌트 16개 각각에 이름, 핵심 파일 경로, 의존 관계를 정리했다.
| C01 | LLM Router | packages/llm/src/router.ts | | C05 | Pepper Core | apps/core/src/index.ts | | C06 | Triage Engine | apps/core/src/triage.ts | | C13 | Realtime Layer | apps/mobile/src/components/... |
새 세션을 시작할 때 이 지도를 주면 Claude Code가 바로 어디를 봐야 하는지 안다. "Realtime 메시지 안 오는 버그"라고 하면 C13을 먼저 연다. "페퍼 응답 속도 느리다"고 하면 C01과 C05를 본다.
가장 중요한 규칙은 하나다. 컴포넌트를 수정할 때 PEPPER_MAP도 같이 업데이트한다. 지도가 코드보다 늦으면 의미가 없다.
UI Spec — 화면의 context.md
같은 맥락에서 UI spec도 만들었다.
이유는 단순하다. Claude Code한테 화면을 만들어달라고 할 때마다 조금씩 달랐다. 버튼 색이 다르고, 폰트 크기가 다르고, 여백이 달랐다. 내가 매번 "버튼은 burgundy로, 배경은 cream으로" 라고 설명할 수 없었다.
UI spec에 디자인 시스템 전체를 박아뒀다.
--cream: #F5F0E8 앱 배경 --burgundy: #7A1E2E 버튼, 액티브 상태 --warm-black: #1A1714 본문 텍스트
색상 토큰부터 말풍선 border-radius, 탭바 구조, 아바타 사이즈까지. 이걸 Claude Code에 주면 매번 같은 디자인이 나온다. context drift가 UI에도 생긴다는 걸, 만들면서 처음 알았다.
문서가 코드보다 먼저라는 원칙은 EP 04에서 세웠다. EP 05에서 그 원칙이 두 개의 문서로 더 확장됐다. 시스템 지도, 그리고 화면의 설계도.
다음은 진짜 고생한 이야기다.