[레딧-클로드코드] Claude Code 6-layer 아키텍처 설계 가이드

요약

Claude Code에서 컨텍스트가 드리프트하거나 규칙이 무시되는 현상은 모델의 문제가 아니라 구조의 문제라는 관점에서, context, skills, tools/MCP, hooks, subagents, verification
6개 레이어로 제어 스택을 설계하는 튜토리얼입니다. 레딧 r/ClaudeCode에서 공유된 글이며, 댓글에서도 실전 팁이 다수 논의되었습니다.

인사이트

• 잘못된 정보가 컨텍스트에 들어가면 빠진 정보보다 피해가 큼 — 모델은 잘못된 입력에 대해 자신있게 행동하고, verification 없이는 몇 단계 뒤에야 문제를 발견
• MCP 서버 5개를 연결하면 도구 정의만으로 약 25,000 토큰이 소비됨 — 메시지를 보내기 전에 컨텍스트 윈도우가 이미 상당 부분 차 있는 상태
• 스킬 descriptor는 상시 컨텍스트에 상주하므로 길이가 토큰 비용 — 45토큰짜리 설명을 9토큰으로 줄이면 "언제 쓸지"만 전달하는 것으로 충분

해결

1. Context — CLAUDE.md 압축 규칙 + HANDOFF.md

• CLAUDE.md에 압축 우선순위를 명시 (아키텍처 결정 > 수정 파일 > 검증 상태 > TODO > 도구 출력)
• 세션 종료 전 HANDOFF.md에 시도/성공/실패/다음 할 일을 기록, 다음 세션이 이 파일에서 시작

2. Skills — descriptor 최소화 + 자동 호출 제어

• descriptor는 "무엇이 들어있는지"가 아니라 "언제 써야 하는지"를 전달
• 사이드 이펙트가 있는 스킬(배포, 마이그레이션)은 모델 자동 호출을 비활성화

3. Hooks — 파일 타입별 편집 후 자동 검증

• .rs 편집 후 cargo check, .lua 편집 후 luajit 바이트코드 검증 등 PostToolUse hook 설정
• 편집 3번째에서 컴파일 에러를 잡는 것과 40번째에서 잡는 것의 비용 차이가 큼

4. Subagents — 격리용, 병렬화가 아님

• 코드베이스 스캔, 테스트 실행 등 대량 토큰을 생성하는 작업을 서브에이전트에 위임, 메인 스레드는 요약만 수신
• 메인 스레드와 동일한 권한을 주지 않음

5. Prompt Caching — 순서가 비용을 결정

• System Prompt(고정) → Tool Definitions(고정) → Chat History(동적) → User Input(마지막) 순서로 배치
• 시스템 프롬프트에 타임스탬프를 넣으면 매 요청마다 캐시가 깨짐, 모델 전환은 서브에이전트 핸드오프로

6. Verification — "완료"의 정의를 코드로

• 올바른 결과를 시작 전에 정의하지 못하면 그 작업은 아직 준비가 안 된 것
• CLAUDE.md에 검증 규칙 명시, hook으로 강제, 스킬이 실행 방법을 정의 — 세 레이어가 함께 동작해야 빈틈이 없음

댓글 인사이트

• 20개의 canonical input/output 테스트 케이스 + 채점 스크립트가 프롬프트 튜닝보다 내구성이 높음
• HANDOFF.md 없이 다음 세션을 시작하면 10~15분을 이미 했던 작업을 재탐색하는 데 소비
• Obsidian에 설계→기술→마일스톤 3단계 문서를 작성하고, Claude가 파일시스템으로 탐색하게 하면 컨텍스트 비용이 줄어듦
• 1M 컨텍스트 윈도우는 시간이 지나면서 attention이 약해짐 — compact boundary마다 알려진 것과 모르는 것을 재주입해야 수천 회 도구 호출에서도 품질 유지 가능