🤖
1495 in / 1527 out / 3022 total tokens
CLAUDE.md가 한 덩어리로 있으니 Claude가 뭘 먼저 읽어야 할지 헷갈리더라. 그래서 역할별로 세 계층으로 나눴다.
Brain은 오케스트레이션 계층이다. harness, workflow, commands 문서가 여기 들어간다. 언제 시작하고 어떤 순서로 흘러가는지 결정하는 쪽이다. Hands는 실제 실행 에이전트 문서 모음이다. scout이 코드 스캔하고, coder가 수정하고, reviewer가 리뷰하고, qa가 검증하고, codex가 보조하는 구조. Session과 Contracts는 불변 조건, 규칙, 산출물 보관소다. 세션마다 바뀌면 안 되는 것들을 여기 고정해둔다.
기존엔 harness 구조를 2트랙 파이프라인으로 표현했는데, "계획(Brain) → 개발(Hands)" 흐름은 맞았지만 문서 간 관계가 평면적이었다. 이번에 계층화하면서 각 문서가 어느 레이어에 속하는지 명확해졌다. 55줄 추가, 31줄 삭제. 추가가 더 많은 건 문서 사용 원칙 5개를 새로 적었기 때문이다.
text 계층 구조 (재구성 후): Brain/ → 오케스트레이션 (harness, workflow, commands) Hands/ → 실행 에이전트 (scout, coder, reviewer, qa, codex) Session/ → 세션 컨텍스트 Contracts/ → 불변조건, 규칙, 산출물
원칙 5개가 핵심이다. 각 에이전트가 자기 계층 문서만 수정하고, 상위 계층은 읽기 전용으로 취급한다는 규칙을 넣었다. 이걸 안 정해두면 coder가 harness를 임의로 바꿔버리는 사고가 난다. 실제로 겪었다.
읽기 전용 제약을 Contracts에 명시해둔 게 포인트다.
AI 에이전트한테 "알아서 잘 해"라며 전역 상태를 다 주면 반드시 엉뚱한 걸 수정한다. 권한 계층을 문서 레벨에서부터 나눠야 한다.