🤖
1495 in / 1478 out / 2973 total tokens
CLAUDE.md가 한 덩어리로 있으니 Claude가 계획 단계에서 코드 실행 규칙까지 동시에 읽어서 컨텍스트가 낭비되더라. 그래서 역할별로 세 계층으로 분리했다.
Brain은 오케스트레이션 계층이다. harness, workflow, commands 문서가 여기 속한다. "언제 시작하고, 어떤 순서로 돌아가는가"를 담당한다. Hands는 실행 에이전트 계층이다. scout, coder, reviewer, qa, codex가 각자의 문서를 갖는다. Session/Contracts는 불변조건과 산출물 보관소다. 이건 세션이 바뀌어도 변하지 않는 규칙이다.
기존에는 하나의 마크다운에 파이프라인 다이어그램과 에이전트 규칙이 섞여 있었다. Claude가 계획을 세울 때는 coder의 린트 규칙이 필요 없고, 반대로 코드를 짤 때는 meeting-codex의 토론 포맷이 필요 없다. 계층을 나누면 각 에이전트가 자기 역할에 해당하는 문서만 읽으면 된다.
문서 사용 원칙 5개도 추가했다. 핵심은 "각 계층은 자기 계층의 문서만 수정한다"는 것. Brain이 Hands 문서를 건드리지 않고, Hands가 Contracts를 덮어쓰지 않는다. 게임 서버 아키텍처에서 레이어 간 의존성 방향을 단방향으로 강제하는 것과 같은 원리다.
markdown 계획 (Brain) 개발 (Hands) /meeting-codex 자동 트리아지 Claude ↔ Codex 토론 Scout → Coder → Reviewer → QA ↓ ↑ impl 문서 ──── 사용자 승인 ────→ 입력
이 다이어그램은 기존에도 있었지만, 이제 각 박스가 어느 계층 문서를 참조하는지가 명확해졌다. impl 문서가 Brain과 Hands 사이의 인터페이스 역할을 한다.
55줄 추가, 31줄 삭제. 파일 하나지만 구조가 완전히 바뀌었다.
다음에는 각 에이전트 문서에 token budget을 명시해서 컨텍스트 윈도우 낭비를 더 줄여볼 생각이다.
단일 파일은 결국 단일 책임 원칙을 위반한다 — 에이전트도 개발자처럼 자기 책임 범위가 있어야 한다.