긴 문서는 AI를 느리게 만든다 — 라우터 패턴으로 문서 슬림화하기
요즘 여러 개로 나뉘어 있던 RoboTrader 관련 저장소를 kis-trading-template 하나로 정리하고 있습니다. 그 과정에서 계속 마주친 원칙이 하나 있습니다.
AI는 항상 문서를 기반으로 동작한다.
당연한 말 같지만, 실제로 겪어보면 꽤 무겁게 다가옵니다. Claude Code 같은 도구는 세션을 시작할 때마다 CLAUDE.md를 자동으로 읽고 컨텍스트를 잡습니다. 이 파일이 뭘 담고 있느냐가 곧 AI가 얼마나 정확하고 빠르게 일하는지를 결정한다는 뜻입니다. 코드를 아무리 잘 짜도, 그걸 설명하는 문서가 엉망이면 AI는 매번 헤맵니다.
이번 글은 느끼고 체감한 내용입니다.
1. 무엇이 문제였나 — CLAUDE.md 340줄
kis-trading-template은 계속 자라는 프로젝트입니다. 전략이 8개로 늘고, 모듈이 쪼개지고, 새로운 규칙이 생길 때마다 그 내용을 어딘가에 적어야 했습니다. 제일 만만한 곳이 CLAUDE.md였습니다. AI가 항상 읽는 파일이니, 새로운 규칙이 생기면 일단 여기에 추가하는 식이었죠.
그렇게 쌓이다 보니 어느새 340줄이 됐습니다. 그 안에는 이런 것들이 전부 뒤섞여 있었습니다.
- 프로젝트 구조 안내 (라우팅 정보)
- 전략 8개 각각의 진입/청산 룰, 임계값 (상세 정보)
- 모듈별 코드 위치, 테스트 구조 (상세 정보)
- 코드 컨벤션, 개발 규칙 (라우팅 정보)
문제는 이 파일이 매 세션 무조건 자동 주입된다는 점입니다. AI가 “지금 당장 어디를 봐야 하는지”만 알면 되는 순간에도, 전략 8개의 임계값 표까지 통째로 끌고 들어왔습니다. 정작 필요한 라우팅 정보는 그 사이 어딘가에 파묻혀 있었고요.
더 안 좋은 문제도 있었습니다. CLAUDE.md에 적힌 전략 임계값(예: RSI 값, 손절 %)이 실제 config.yaml이나 코드의 값과 어긋날 가능성이 늘 있었습니다. 코드는 계속 바뀌는데 문서는 그때그때 손으로 맞춰줘야 하니, 결국 둘 중 뭐가 진짜인지 알 수 없는 상태가 되기 쉬운 구조였습니다.
2. 원칙 정리 — 라우터와 상세를 분리한다
해결 방향은 단순했습니다. 자동 주입되는 파일은 “라우터”로만 쓰고, 상세 내용은 링크로 뺀다.
지금 CLAUDE.md 맨 위에는 이렇게 적혀 있습니다.
# CLAUDE.md — AI 개발 협업 가이드
> Claude(AI 개발자)가 이 프로젝트에 빠르게 컨텍스트를 잡기 위한 **라우터 문서**입니다.
> 상세는 각 링크를 따라가세요. 이 파일은 매 세션 컨텍스트에 자동 주입되므로 의도적으로 얇게 유지합니다.
역할을 이렇게 나눴습니다.
| 문서 | 역할 |
|---|---|
CLAUDE.md |
라우터 — “이 정보는 어디에 있다”만 안내 |
docs/code/MODULES.md |
모듈별 상세 (framework/api/core/bot/db/utils, main.py 흐름, 테스트 구조) |
docs/PAPER_STRATEGIES.md |
활성 전략 운영 허브 (한눈표 + 자본/regime 모델 + 데이터 SSOT) |
strategies/{전략명}/README.md |
전략 8개 각각의 상세 (의도, 진입/청산 룰, 백테스트 평판) |
그리고 임계값 문제에는 이렇게 못을 박았습니다. 각 전략 README 맨 위에 붙는 문구입니다.
> 임계값의 SSOT는 `config.yaml` + 진입/청산 룰 코드입니다.
> 이 문서는 *해설*이며, 숫자가 어긋나면 코드가 정본.
문서가 숫자를 “설명”할 뿐 “정의”하지는 않는다고 명시해버리면, 드리프트가 생겨도 뭐가 진짜인지 헷갈릴 일이 없습니다.
3. 결과 — Before / After
Before
CLAUDE.md: 340줄
├── 프로젝트 구조 + 개발 규칙 (라우팅)
├── 전략 8개 진입/청산/임계값 상세 (본문에 전부 내장)
├── 모듈별 코드 위치 상세
└── 매 세션 전체가 자동 주입됨
After
CLAUDE.md: 133줄 (-60.9%) ← 라우터만
├── docs/code/MODULES.md (신규, 216줄) ← 모듈 상세
├── docs/PAPER_STRATEGIES.md (98줄로 슬림화) ← 운영 허브
└── strategies/{8개}/README.md (신규, 각 28~34줄) ← 전략별 상세
| 지표 | Before | After |
|---|---|---|
| CLAUDE.md 줄 수 | 340 | 133 |
| 자동 주입되는 컨텍스트 | 전부 | 라우터만 |
| 전략 상세 위치 | CLAUDE.md 안에 내장 | 코드 옆 README (필요할 때만 열람) |
| 임계값 정본 | 모호 (문서 vs 코드) | 코드로 명시 |
340줄을 133줄로 줄이면서, 사라진 207줄은 없어진 게 아니라 MODULES.md와 전략별 README 8개로 흩어졌습니다. 정보량은 그대로거나 오히려 늘었는데, AI가 매 순간 강제로 읽어야 하는 양은 크게 줄었습니다.
이 작업엔 Opus 4.8(1M 컨텍스트) 모델을 썼습니다. 340줄짜리 문서와 전략 8개 코드를 동시에 붙잡고 “이 문단은 라우터에 남길지 상세로 뺄지”를 판단해야 했는데, 컨텍스트가 넉넉한 모델이 아니면 이런 재편집 자체가 힘들었을 것 같습니다.
4. 한 번 잡은 구조는 계속 복리로 돌아간다
이 라우터 패턴을 만든 게 6월 24일이었는데, 일주일 뒤인 7월 2일 연구 코드/운영 코드 경계를 정리하는 작업을 할 때 다시 써먹었습니다. “라이브 코드가 연구 코드에 의존하면 안 된다”는 새 규칙이 생겼을 때, CLAUDE.md에 통째로 설명을 늘어놓는 대신 이렇게 했습니다.
## 🧭 운영 vs 연구 코드 라우팅 (에이전트 필독)
- **운영(production)**: `core/` `bot/` `framework/` ...
- **연구/일회성(research, 라이브 아님)**: `scripts/` `multiverse/` `backtest/` ...
승격 이력·드리프트 점검 명령은 [docs/CODE_MAP.md](docs/CODE_MAP.md),
연구 파일별 태깅은 [docs/INVENTORY.md](docs/INVENTORY.md).
딱 라우팅 정보만 CLAUDE.md에 남기고, 승격 이력이나 검증 명령 같은 상세는 별도 문서(CODE_MAP.md, INVENTORY.md)로 바로 분리했습니다. 처음부터 “이건 라우터에 안 어울린다”는 감각이 생겨 있었기 때문에 고민할 필요가 없었습니다.
한 번 원칙을 세우고 나니, 이후에 문서가 또 비대해질 뻔한 순간마다 판단 기준이 명확해진 셈입니다.
5. 배운 것
AI는 문서를 기반으로 동작한다. 이건 비유가 아니라 말 그대로입니다. CLAUDE.md에 뭐가 적혀 있느냐가 AI가 어떤 판단을 내리느냐를 직접 결정합니다. 그렇다면 AI를 효율적으로 쓰는 문제는 결국 문서를 어떻게 설계하느냐의 문제로 좁혀집니다.
정리하면 이렇습니다.
- 자동 주입되는 문서는 라우터로만 쓴다. “어디에 뭐가 있다”만 안내하고, 본문은 최대한 얇게.
- 상세는 코드 가까이 둔다. 전략 상세를 전략 코드 옆 README로 옮기니, 코드를 고칠 때 문서도 같이 눈에 들어옵니다.
- 정본(SSOT)을 명시한다. 문서와 코드가 어긋날 수 있는 지점(임계값 같은)은 “숫자가 다르면 코드가 맞다”고 못박아버리면 드리프트 걱정이 줄어듭니다.
- 한 번 잡은 구조는 재사용된다. 라우터 패턴을 세워두니, 다음 리팩토링에서 “이 내용을 어디에 적을까” 고민하는 시간이 사라졌습니다.
사람이 읽는 문서는 조금 길어도 훑어보고 필요한 데로 건너뛸 수 있습니다. 하지만 AI에게 “매 세션 자동 주입”은 사람의 “훑어보기”와 다릅니다. 강제로 전부 읽고 시작하는 구조라서, 문서가 비대해질수록 AI가 진짜 필요한 정보를 찾는 비용이 그대로 늘어납니다. 문서에도 라우터와 상세를 나누는 아키텍처가 필요하다는 걸, 이번에 제대로 체감했습니다.
💬 CLAUDE.md나 비슷한 자동 주입 문서를 관리하는 분들은 어떤 기준으로 나누시나요? 댓글로 알려주시면 좋겠습니다.
댓글