대부분의 사람들은 Claude Code를 열고, 프롬프트를 입력하고, 응답을 기다리고, 또 다른 프롬프트를 입력합니다.
그건 페라리를 사놓고 1단 기어로만 운전하는 것과 같아요.
저는 왜 어떤 사람들은 Claude Code에서 다른 사람들보다 10배 더 많은 걸 얻어내는지 이해하고 싶었습니다. 그래서 합리적인 사람이라면 누구나 할 일을 했죠: 전체 소스 코드를 읽었습니다 (제가 읽었다고 말할 때는, 물론 Claude Code가 읽었다는 뜻입니다).
11개의 아키텍처 레이어. 수천 줄의 코드. 터미널 채팅으로 위장한 에이전트 오케스트레이션 플랫폼.
소스 코드가 이 도구를 실제로 사용하는 방법에 대해 알려주는 내용입니다.
1. CLAUDE.md 는 매 턴마다 로드됩니다. 매. 턴. 마다.
이것이 여러분이 할 수 있는 가장 영향력 큰 일인데, 거의 아무도 제대로 하고 있지 않습니다.
대부분의 사람들은 CLAUDE.md 파일에 아무것도 없거나, 아니면 성경 전체를 써넣었습니다.
소스 코드를 보면 Claude Code가 모든 쿼리 반복(iteration)마다 여러분의 CLAUDE.md 파일을 읽는다는 것을 알 수 있습니다. 세션 시작 시가 아닙니다. 매 턴마다요. 즉, 메시지를 보낼 때마다 여러분의 지침을 다시 읽는다는 뜻입니다.
전체 계층 구조가 있습니다:
- ~/.claude/CLAUDE.md — 전역 (여러분의 코딩 스타일, 선호도)
- ./CLAUDE.md — 프로젝트 레벨 (아키텍처 결정, 규칙)
- .claude/rules/*.md — 모듈식 규칙
- CLAUDE.local.md — 개인 노트 (gitignore 처리됨)
40,000자를 사용할 수 있습니다. 엄청난 양이죠. 대부분의 사람들은 200자 정도만 사용합니다.
아키텍처 결정 사항을 거기에 넣으세요. 파일 규칙, 테스트 패턴, "절대 하지 말 것" 규칙을 넣으세요. 모델이 매 턴마다 이를 읽습니다. 이것이 Claude Code가 일반적인 어시스턴트인 것과 여러분의 코드베이스를 아는 여러분만의 어시스턴트가 되는 것의 차이입니다.
이 글을 읽고 한 가지만 한다면, 이것만 하세요.
2. 서브 에이전트는 프롬프트 캐시를 공유합니다 (병렬 처리는 거의 공짜입니다)
이게 제가 정말 깜짝 놀란 부분입니다.
Claude Code가 서브 에이전트를 포크(fork)할 때, 부모 컨텍스트의 바이트 단위 동일 복사본을 만듭니다. API가 이를 캐시합니다. 따라서 코드베이스의 다른 부분에서 작업할 5개의 에이전트를 생성하는 비용이 1개의 에이전트가 순차적으로 작업하는 것보다 거의 더 들지 않습니다.
다시 읽어보세요.
5개의 에이전트. 1개와 같은 비용. 모두 프롬프트 캐시를 활용하기 때문입니다.
대부분의 사람들은 Claude Code를 단일 워커처럼 사용합니다. 한 번에 하나의 작업. 끝날 때까지 기다립니다. 다음 작업을 줍니다.
소스 코드에는 서브 에이전트를 위한 세 가지 실행 모델이 있습니다:
- fork — 부모 컨텍스트를 상속, 캐시 최적화됨
- teammate — tmux 또는 iterm에서 별도 창, 파일 기반 메일박스로 통신
- worktree — 자체 git worktree 를 얻음, 에이전트당 격리된 브랜치
Claude Code에 5개의 에이전트를 실행하라고 지시할 수 있습니다: 하나는 보안 감사, 하나는 인증 모듈 리팩토링, 하나는 테스트 작성, 하나는 문서 업데이트, 하나는 버그 수정. 모두 동시에. 모두 캐시를 공유합니다.
아키텍처가 이를 위해 BUILT 되어 있습니다. 단일 스레드로 사용하는 건 거의 범죄 수준입니다.
3. 권한 시스템은 클릭해서 지나가라고 만들어진 게 아니라, 설정하라고 만들어진 것입니다
Claude Code가 "이 작업을 허용할까요?"라고 물을 때마다 여러분이 예를 클릭하는 것은, 기능이 아니라 설정의 실패입니다.
소스 코드는 5단계 설정 계층 구조를 보여줍니다:
1policy > flag > local > project > user
~/.claude/settings.json 에서 항상 허용할 전역 패턴을 설정할 수 있습니다:
1{2 "permissions": {3 "allow": [4 "Bash(npm *)",5 "Bash(git *)",6 "Edit(src/**)",7 "Write(src/**)"8 ]9 }10}
세 가지 권한 모드가 있습니다:
- bypass — 권한 확인 없음 (위험하지만 빠름)
- allowEdits — 작업 디렉토리 내 파일 편집 자동 허용
- auto (새로운 기능) — 각 작업에 대해 LLM 분류기 실행. 이것이 가장 좋은 지점입니다.
auto 모드는 자체 허용/거부 목록이 있으며 이를 설정할 수 있습니다. 소스 코드는 여러 리졸버를 병렬로 실행합니다: 사용자 클릭, 후크 분류기, 브리지 중 가장 먼저 응답하는 것이 승리합니다.
"허용"을 클릭하기 위해 멈출 때마다 낭비되는 시간입니다. 한 번 설정하고, 다시는 클릭하지 마세요.
4. 5가지 압축 전략이 있습니다. 컨텍스트 압박은 진짜 문제입니다
소스 코드에는 대화가 너무 길어질 때 이를 압축하는 FIVE 가지 방법이 있습니다:
- microcompact — 시간 기반의 오래된 도구 결과 제거
- context collapse — 대화 구간 요약
- session memory — 주요 컨텍스트를 파일로 추출
- full compact — 전체 기록 요약
- PTL truncation — 가장 오래된 메시지 그룹 삭제
이는 중요한 것을 알려줍니다: 컨텍스트 오버플로는 엔지니어들이 많은 시간을 들인 핵심 문제라는 것입니다.
여러분에게 의미하는 바:
- \
/compact\를 사전에 사용하세요. 시스템이 자동 압축해서 중요한 컨텍스트를 잃을 때까지 기다리지 마세요.
- 기본 창은 200K 토큰입니다. 하지만 \
[1m]\모델 접미사를 사용하면 1M 토큰을 선택할 수 있습니다. 여러 파일에 걸친 대규모 리팩토링에 중요합니다.
- 긴 세션은 "세션 메모리"를 축적합니다 — 작업 사양, 파일 목록, 워크플로 상태, 오류, 학습 내용의 구조화된 요약입니다. 이것이 새로 시작하는 것보다 세션을 재개하는 것이 더 나은 이유입니다.
- 큰 도구 결과는 디스크에 저장되고 8KB 미리보기만 모델로 전송됩니다. 거대한 파일을 붙여넣으면 모델이 극히 일부만 볼 수 있습니다. 입력을 집중적으로 유지하세요.
Claude Code에서 가장 많은 것을 얻는 사람들은 \/compact\ 를 비디오 게임의 수동 저장 지점처럼 사용합니다. 중요한 것은 보존하고, 불필요한 것은 지우고, 계속 나아가세요.
5. 후크 시스템이 진정한 확장 API입니다 (25개 이상의 라이프사이클 이벤트)
이것은 거의 아무도 모르는 파워 유저 기능입니다.
소스 코드는 여러분이 연결할 수 있는 25개 이상의 라이프사이클 이벤트를 보여줍니다:
- PreToolUse — 모든 도구 실행 전에 실행
- PostToolUse — 모든 도구 실행 후에 실행
- UserPromptSubmit — 메시지를 보낼 때 실행
- SessionStart / SessionEnd — 세션 라이프사이클
- 그리고 20개 이상 더
5가지 유형의 후크가 있습니다:
- command — 셸 명령 실행
- prompt — LLM을 통해 컨텍스트 주입
- agent — 전체 에이전트 검증 루프 실행
- HTTP — 웹훅 호출
- function — JS 실행
실제로 할 수 있는 예시:
- 모든 파일 쓰기 전에 자동으로 린팅 실행
- 모든 편집 후에 테스트 실행
- 모든 프롬프트에 관련 문서를 자동으로 주입
- 작업 완료 시 슬랙 알림 전송
- 코드 출시 전에 보안 패턴이 준수되는지 검증
\UserPromptSubmit\ 후크는 특히 놀랍습니다. 보내는 모든 메시지에 \additionalContext\ 를 주입할 수 있습니다. 입력하지 않고도 테스트 출력, 최근 git diff, 또는 프로젝트 상태를 모든 프롬프트에 자동으로 첨부하는 것을 상상해보세요.
이것이 Claude Code 위에 사용자 정의 개발 환경을 구축하는 방법입니다. 더 잘 프롬프팅하는 것이 아니라 시스템 자체에 연결하는 것입니다.
6. 세션은 지속적이며 재개 가능합니다 (계속 새로 시작하지 마세요)
모든 대화는 JSONL로 저장됩니다:
1~/.claude/projects/{hash}/{sessionId}.jsonl
소스 코드는 다음을 지원합니다:
- --continue — 마지막 세션 재개
- --resume — 특정 과거 세션 선택
- --fork-session — 과거 대화에서 분기 (개인적으로 이걸 가장 좋아합니다)
세션 메모리 추출은 압축 과정에서 주요 컨텍스트(작업 사양, 파일 목록, 워크플로 상태, 오류, 학습 내용)를 보존합니다.
대부분의 사람들은 Claude Code를 열 때마다 새 세션을 시작합니다. 이는 IDE를 닫고 매시간 처음부터 다시 여는 것과 같습니다. 무엇을 하고 있었는지, 무엇이 실패했는지, 무엇을 배웠는지에 대한 모든 컨텍스트가 사라집니다.
\--continue\ 를 사용하세요. 항상. 컨텍스트가 축적되게 하세요. 세션 메모리가 시간이 지남에 따라 학습 내용을 쌓아가게 하세요. 소스 코드에는 문자 그대로 이를 위한 인프라가 있습니다. 활용하세요.
7. 도구 시스템은 스마트 배치로 60개 이상의 도구를 실행합니다
Claude Code에는 60개 이상의 내장 도구가 있습니다. 하지만 흥미로운 부분은 이를 HOW 실행하는지입니다.
소스 코드는 도구 호출을 두 가지 범주로 나눕니다:
- 동시(concurrent) — 읽기 전용 작업 (파일 읽기, 검색, globbing)은 병렬로 실행
- 직렬(serial) — 변경 작업 (편집, 쓰기, bash 명령)은 한 번에 하나씩 실행
즉, Claude Code가 코드베이스를 이해하기 위해 10개의 파일을 읽어야 할 때, 10개를 모두 동시에 읽습니다. 하지만 3개의 파일을 편집해야 할 때는 충돌을 피하기 위해 하나씩 처리합니다.
내장 도구 위에 더 많은 도구를 추가하는 MCP 서버를 연결할 수 있습니다. 소스 코드는 지연 로딩을 사용합니다. MCP 도구는 필요할 때만 로드되므로, 5개의 MCP 서버를 연결해도 모든 요청이 느려지지 않습니다.
그리고 에이전트가 아직 모르는 도구의 지연 발견을 위한 ToolSearch도 있습니다.
실용적인 요점: 워크플로에 외부 시스템(데이터베이스, 클라우드 제공자, CI/CD)이 포함된다면, 이들을 위한 MCP 서버를 연결하세요. 아키텍처가 복잡성을 처리합니다. 여러분은 더 많은 기능을 얻을 뿐입니다.
8. 스트리밍 아키텍처는 중단이 저렴함을 의미합니다
전체 파이프라인은 개별 이벤트를 생성하는 비동기 생성기(async generators)를 사용합니다. Escape를 누르면 이전 컨텍스트를 잃지 않고 현재 스트림을 깔끔하게 중단합니다.
작아 보이지만, 이것은 Claude Code를 사용하는 방식을 바꿔야 합니다.
잘못 가고 있다는 것을 아는 응답을 기다리지 마세요. 즉시 중단하고 방향을 바꾸세요. 소스 코드는 이를 위해 설계되었습니다. 이전 컨텍스트는 보존됩니다. 중단된 응답은 깔끔하게 폐기됩니다. 패널티가 전혀 없습니다.
페어 프로그래밍처럼 생각하세요. 짝이 잘못된 길로 가기 시작하면, 끝날 때까지 기다리지 않습니다. "아니, 이쪽으로 가보자"라고 말하죠. 같은 느낌입니다.
9. 재시도 시스템은 생각보다 훨씬 정교합니다
소스 코드가 보여주는 것:
- 지수 백오프와 지터가 있는 10회 재시도 (500ms 기준)
- 401/403 발생 시 자동 OAuth 토큰 갱신
- 모델 폴백: Opus가 529 오류로 3번 실패하면 자동으로 Sonnet으로 폴백
- 스트림에서 90초 유휴 감시 — 스트리밍이 중단되면 비스트리밍으로 폴백
- 영구 모드는 최대 5분 백오프로 무한 재시도
이는 Claude Code가 계속 실행되도록 설계되었음을 의미합니다. API 문제, 속도 제한, 중단을 우아하게 처리합니다. 계속 지켜볼 필요가 없습니다. 백그라운드에서 실행되게 두고 결과를 확인하세요.
소스 코드가 알려주는 최고의 영향력 행동들:
• 실제 CLAUDE.md 작성하기 → 매 턴마다 로드됨. 40K 문자. 가장 영향력 큰 설정.
• 서브 에이전트로 병렬화하기 → fork 모델이 프롬프트 캐시를 공유함. 5개 에이전트 ≈ 1개 비용.
• settings.json 에서 권한 설정하기 → 클릭 피로를 영원히 없앰.
• /compact 를 사전에 사용하기 → 5가지 압축 전략이 존재하는 이유는 컨텍스트 압박이 현실이기 때문.
• 후크 설정하기 → 25개 이상의 이벤트, 5가지 유형. 이것이 진정한 확장 API.
• 항상 --continue 로 세션 이어가기 → JSONL 지속성 + 세션 메모리 = 축적된 컨텍스트.
• MCP 서버 연결하기 → 지연 로딩으로 사용될 때까지 비용 제로.
• 자유롭게 중단하기 → 비동기 생성기로 방향 전환에 패널티 제로.
결론:
Claude Code는 터미널 UI를 입은 에이전트 오케스트레이션 플랫폼입니다.
10배 더 많은 결과를 얻는 사람들은 더 나은 프롬프터가 아닙니다. 그들은 설정했습니다. 병렬화했습니다. 연결했습니다. 세션 전체에 걸쳐 컨텍스트를 축적하게 했습니다.
소스 코드가 이를 명백하게 보여줍니다. 이제 내부에서 실제로 무엇을 하는지 알게 되었습니다.
도움이 되었다면 리트윗(rt) 부탁드립니다 🫶
