0. TL;DR
이 글은 6개월 동안 Claude Code를 집중적으로 사용하고, 두 개의 계정으로 월 40달러를 지출하며 얻은 교훈을 바탕으로 작성되었습니다. 모든 분들께 유용한 인사이트를 제공할 수 있기를 바랍니다.
처음에는 ChatBot으로 사용했지만, 곧 문제가 있다는 것을 곧 깨달았습니다: 컨텍스트가 지저분해지고, 도구는 늘어났지만 효율성은 떨어졌으며, 규칙은 길어짐에도 불구하고 무시되었습니다. Claude Code 자체를 연구한 후, 이것이 프롬프트 문제가 아니라 시스템 설계 문제라는 것을 알게 되었습니다.
다음에 대해 논의하고자 합니다: Claude Code가 내부적으로 어떻게 작동하는지, 컨텍스트가 왜 지저분해지고 어떻게 관리해야 하는지, Skills와 Hooks를 설계하는 방법, Subagents의 올바른 사용법, Prompt Caching의 아키텍처적 영향, 그리고 진정으로 유용한 CLAUDE.md를 작성하는 방법입니다.
가장 직관적인 이해 방법은 Claude Code를 6개의 레이어로 나누는 것입니다:
하나의 레이어만 강화하면 불균형이 발생합니다. CLAUDE.md가 너무 길면 컨텍스트를 오염시키고, 도구가 너무 많아지면 혼란을 야기하며, Subagents가 많아지면 상태 표류가 발생합니다. 검증을 건너뛰면 문제 발생 지점을 찾을 수 없게 됩니다.
1. 내부 작동 방식
Claude Code의 핵심은 "답변"이 아니라 반복적인 에이전트 루프입니다:
1컨텍스트 수집 → 실행 → 결과 확인 → [종료 또는 반복]2 ↑ ↓3 CLAUDE.md Hooks / 권한 / 샌드박스4 Skills Tools / MCP5 메모리
병목 현상은 대개 모델이 충분히 똑똑하지 않아서가 아니라, 잘못된 컨텍스트를 제공하거나 출력이 올바른지 판단할 방법이 없거나 롤백할 수 없기 때문에 발생한다는 것을 깨달았습니다.
집중해야 할 5개 레이어:
이 레이어들을 살펴보면 문제 해결이 더 쉬워집니다. 결과가 불안정한가요? 컨텍스트 로딩 순서를 확인하세요. 자동화가 통제 불능인가요? 제어 레이어를 확인하세요. 긴 세션에서 품질이 저하되나요? 중간 결과물이 컨텍스트를 오염시킨 것입니다; 프롬프트를 수정하는 것보다 새 세션을 시작하는 것이 좋습니다.
2. 개념적 경계: MCP / Plugin / Tools / Skills / Hooks / Subagents
간단한 규칙: 새로운 작업에는 Tools/MCP, 워크플로우에는 Skills, 격리된 환경에는 Subagents, 필수 제약/감사에는 Hooks, 프로젝트 간 배포에는 Plugins를 사용하세요.
3. 컨텍스트 엔지니어링: 가장 중요한 시스템 제약 조건
많은 사람이 컨텍스트를 "용량 문제"로 취급하지만, 병목 현상은 보통 노이즈입니다. 유용한 정보가 관련 없는 내용에 묻혀버립니다.
실제 컨텍스트 비용 구성
Claude Code의 200K 컨텍스트가 전부 사용 가능한 것은 아닙니다:
1200K 전체 컨텍스트2├── 고정 오버헤드 (~15-20K)3│ ├── 시스템 지침: ~2K4│ ├── Skill 설명자: ~1-5K5│ ├── MCP 서버 도구 정의: ~10-20K ← 가장 큰 숨은 위험 요소6│ └── LSP 상태: ~2-5K7│8├── 반고정 (~5-10K)9│ ├── CLAUDE.md: ~2-5K10│ └── 메모리: ~1-2K11│12└── 동적 사용 가능 (~160-180K)13 ├── 채팅 기록14 ├── 파일 내용15 └── 도구 결과
일반적인 MCP 서버(GitHub 등)에는 20-30개의 도구 정의가 포함되어 있고, 각각 약 200 토큰이므로 총 4,000-6,000 토큰입니다. 서버 5개를 연결하면 25,000 토큰(12.5%) 을 소모합니다. 대량의 코드를 읽을 때 이것은 중요합니다.
권장 컨텍스트 계층화
1항상 상주 → CLAUDE.md: 프로젝트 계약 / 빌드 명령 / 금지 사항2경로 기반 → rules: 언어 / 디렉토리 / 파일 유형별 규칙3주문형 → Skills: 워크플로우 / 도메인 지식4격리형 → Subagents: 대규모 탐색 / 병렬 연구5컨텍스트 외부 → Hooks: 결정적 스크립트 / 감사 / 차단
가끔만 사용하는 것은 로드하지 마세요.
컨텍스트 모범 사례
- CLAUDE.md는 짧고, 명확하며, 실행 가능하게 유지하세요. Anthropic 자체 CLAUDE.md는 약 2.5K 토큰입니다.
- 큰 참고 문서는 Skills의 지원 파일로 옮기세요.
- 경로/언어 규칙에는 .claude/rules/를 사용하세요.
- /context를 사용하여 소비량을 모니터링하세요.
- 작업 전환 시 /clear를 사용하고, 새 단계 시작 시 /compact를 사용하세요.
- CLAUDE.md에 간결한 지침(Compact Instructions)을 작성하여 보존할 내용을 제어하세요.
도구 출력 노이즈: 또 다른 숨은 위험 요소
동적 도구 출력(cargo test나 git log 등)은 쉽게 컨텍스트를 채웁니다. Claude가 모든 것을 볼 필요는 없습니다.
RTK (Rust Token Killer)는 좋은 접근 방식입니다: 명령 출력을 Claude에게 전달하기 전에 필터링합니다. 예를 들어, 수천 줄의 테스트 출력을 단일 성공 메시지로 압축할 수 있습니다.
압축 함정
기본 압축은 아키텍처 결정과 제약 조건을 삭제할 수 있습니다.
해결책: CLAUDE.md에 Compact Instructions를 지정하여 아키텍처 결정, 수정된 파일, 확인 상태, TODOs를 우선시하도록 하세요.
또 다른 사전 예방적 해결책: 새 세션을 시작하기 전에 Claude에게 HANDOFF.md를 작성하게 하여 진행 상황과 막힌 지점을 설명하도록 하세요.
Plan Mode의 엔지니어링 가치
Plan Mode는 탐색과 실행을 분리합니다.
복잡한 리팩토링의 경우 코드로 바로 들어가는 것보다 이 방법이 더 좋습니다. 고급 팁: 한 Claude가 계획을 작성하고 다른 Claude가 "시니어 엔지니어" 역할을 하여 검토하게 하세요.
4. Skills 설계: 주문형 로드되는 워크플로우
Skills는 주문형 지식과 워크플로우입니다.
좋은 Skill의 조건
- 설명은 "무엇을 하는지"가 아니라 "언제 사용해야 하는지"를 나타내야 합니다.
- 완전한 단계, 입력, 출력, 중단 조건이 있어야 합니다.
- 본문은 탐색과 핵심 제약 조건에 집중하고 세부 사항은 지원 파일로 옮기세요.
- 부작용이 있는 Skill의 경우 disable-model-invocation: true를 설정하세요.
점진적 공개(Progressive Disclosure)
Claude Code는 "점진적 공개"를 강조합니다: 먼저 인덱스와 탐색을 제공한 다음, 필요에 따라 세부 정보를 가져옵니다.
세 가지 일반적인 Skill 유형
- 체크리스트 (품질 게이트): 예: release-check.
- 워크플로우 (표준화된 작업): 예: 롤백 기능이 있는 config-migration.
- 도메인 전문가 (의사 결정 프레임워크): 예: runtime-diagnosis.
설명자는 짧게 유지하여 컨텍스트 공간을 절약하세요.
5. 도구 설계: Claude가 올바르게 선택하도록 돕기
에이전트를 위한 도구는 기능의 완전성보다 올바른 사용의 용이성에 초점을 맞춰야 합니다.
좋은 도구 vs 나쁜 도구
설계 원칙: 접두사( github_pr_* )를 사용하고, 간결한 형식을 지원하며, 유용한 오류 메시지를 제공하고, 너무 많은 세분화된 도구를 노출하지 마세요.
내부 도구의 진화
"AskUserQuestion" 도구의 진화는 전용 도구가 마크다운 형식이나 종료 매개변수보다 더 안정적임을 보여줍니다.
모델이 더 강력해짐에 따라 Todo 도구는 "족쇄"가 되었습니다. 검색 도구는 더 나은 유연성과 "점진적 공개"를 위해 RAG에서 Grep으로 진화했습니다.
6. Hooks: 작업 전/후의 필수 로직
Hooks는 포맷팅, 파일 보호, 알림과 같은 프로세스에 대한 결정적 제어를 되찾습니다.
Hooks에 적합한 경우
보호된 파일 차단, 편집 후 자동 포맷팅, 동적 컨텍스트(Git 브랜치) 주입, 알림.
조기 오류 감지
7. Subagents: 독립적인 Claude 인스턴스
Subagents는 격리를 제공합니다. 저장소 스캔이나 테스트 실행과 같은 작업은 대량의 출력을 생성하며, 이를 메인 스레드에 혼란스럽게 섞어서는 안 됩니다.
명시적 제약 조건
도구를 제한하고, 올바른 모델을 선택하며(탐색에는 Haiku, 검토에는 Opus), maxTurns를 설정하세요.
8. Prompt Caching: Claude Code 아키텍처의 핵심
Claude Code는 Prompt Caching을 중심으로 구축되었습니다. 높은 적중률은 비용을 절약하고 속도 제한을 늘립니다.
캐싱을 위한 프롬프트 레이아웃
접두사 일치를 위해 순서가 중요합니다: 시스템 프롬프트 → 도구 정의 → 채팅 기록 → 사용자 입력.
세션 중 모델 전환 금지
모델을 전환하면 캐시가 깨집니다. 대신 Subagents를 사용하여 전환하세요.
압축 구현
압축은 포크를 사용하여 기록을 요약하며, 캐시 적중으로 인해 비용이 1/10로 절감됩니다.
9. 검증 루프: 검증기 없이는 엔지니어링 에이전트도 없다
검증 없이 "Claude가 완료했다고 말한다"는 것은 쓸모가 없습니다. 프롬프트, Skill, CLAUDE.md에서 검증을 명시적으로 정의하세요.
10. 자주 사용되는 명령어
/context, /clear, /compact, /memory와 같은 명령어는 컨텍스트를 능동적으로 관리하는 데 도움이 됩니다.
거버넌스 및 병렬 처리
유용한 숨겨진 명령어: /simplify (코드 리뷰), /rewind (체크포인트), /btw (부수적 질문), /insight (CLAUDE.md 업데이트를 위한 세션 분석).
11. 좋은 CLAUDE.md 작성 요령
이는 계약서이지 지식 베이스가 아닙니다.
빌드/테스트 명령어, 아키텍처 경계, 코딩 규칙, 안전 장치, Compact Instructions를 포함하세요. 실수를 수정한 후 Claude에게 CLAUDE.md를 업데이트하도록 요청하세요.
12. 최근 경험
Kaku (Rust + Lua) 구축 교훈: 환경 투명성은 필수입니다('doctor' 명령 사용). Hooks는 다중 언어 프로젝트에 매우 적합합니다.
13. 안티 패턴
<payloadblock id="blk_20" type="upload" />
14. 상태 점검
npx skills add tw93/claude-health 를 사용하여 설정을 확인하세요.
15. 결론
초점은 "기능을 사용하는 방법"에서 "제약 조건 하에서 에이전트가 실행되도록 하는 방법"으로 이동합니다. "완료"를 정의할 수 없다면, 해당 작업은 에이전트에 적합하지 않습니다.
