Claude Code 내부 소스로 본 실전 활용 가이드 2026

지난 글에서 Claude Code 소스 유출의 경위와 KAIROS, 안티 디스틸레이션 같은 미공개 기능을 다뤘다. 이번에는 관점을 바꾼다. 유출된 512,000줄의 TypeScript 소스와 공식 문서를 교차 분석해서, 지금 당장 실전에서 쓸 수 있는 확장 전략을 정리한다.

Claude Code는 터미널에서 실행되는 AI 에이전트다. 하지만 기본 설치 상태로 쓰면 전체 기능의 30%도 활용하지 못한다. 내부 소스를 들여다보면, 이 도구가 얼마나 정교한 확장 포인트를 갖고 있는지 분명해진다.

CLAUDE.md와 Hooks — 에이전트의 행동을 코드로 정의하기

Claude Code가 프로젝트를 이해하는 방식은 계층적(hierarchical)이다. 프로젝트 루트의 CLAUDE.md가 최우선이고, 하위 디렉토리의 CLAUDE.md가 해당 범위에서 오버라이드한다. ~/.claude/CLAUDE.md는 전역 설정이다. Claude Directory의 가이드에 따르면, 이 파일에 빌드 명령어, 테스트 실행 방법, 아키텍처 제약 조건을 명시하면 에이전트가 매번 코드베이스를 탐색하는 낭비를 줄일 수 있다.

유출 소스에서 확인한 더 강력한 기능은 .claude/rules/ 디렉토리의 YAML 조건부 규칙이다. 파일 확장자, 디렉토리 경로, 심지어 변경 패턴에 따라 다른 규칙을 적용할 수 있다. 예를 들어 .tsx 파일을 수정할 때는 접근성 체크리스트를 주입하고, api/ 디렉토리에서는 에러 핸들링 패턴을 강제하는 식이다.

Hooks 시스템은 CLAUDE.md보다 한 단계 더 깊은 제어를 제공한다. 공식 문서에 따르면 PreToolUse, PostToolUse, SessionStart 세 가지 훅 타입이 있다. 핵심은 이 훅이 LLM이 아니라 클라이언트가 실행한다는 점이다. 즉, 훅 스크립트는 모델의 판단과 무관하게 확정적으로(deterministically) 실행된다.

settings.json에서 정의하는 훅 설정은 이런 형태다:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "command": "python3 ~/.claude/hooks/block-dangerous.py"
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write",
        "command": "npm test -- --bail 2>/dev/null"
      }
    ]
  }
}

PreToolUse 훅으로 rm -rf, git push --force 같은 위험 명령을 차단하고, PostToolUse 훅으로 파일 작성 후 테스트를 자동 실행하는 패턴이 실전에서 가장 효과적이다. SessionStart 훅은 세션 시작 시 프로젝트 컨텍스트를 미리 로드하는 데 쓴다. 이 세 가지를 조합하면 Claude Code의 행동을 사실상 프로그래밍할 수 있다.

MCP 서버와 서브에이전트 — 외부 세계와 연결하기

MCP(Model Context Protocol, 모델 컨텍스트 프로토콜)는 Claude Code를 외부 서비스와 연결하는 표준 인터페이스다. 공식 MCP 문서에 따르면, HTTP/SSE와 STDIO 두 가지 전송 방식을 지원하며, GitHub, Notion, 데이터베이스 등을 도구(tool)로 노출시킬 수 있다.

유출 소스에서 발견한 핵심 최적화는 Tool Search 메커니즘이다. MCP 서버가 수십 개의 도구를 노출할 때, Claude Code는 모든 도구 정의를 컨텍스트에 로드하지 않는다. 먼저 도구 이름과 설명만 로드하고(메타데이터, 약 100 토큰), 실제로 필요한 도구만 전체 스키마를 동적으로 가져온다. Alex Kim의 분석에 따르면 이 방식으로 72,000 토큰이 8,700 토큰으로 줄었다. 87.9%의 컨텍스트 절감이다.

서브에이전트(sub-agent, 하위 에이전트)는 메인 에이전트가 복잡한 작업을 분해해 위임하는 패턴이다. 공식 서브에이전트 문서가 강조하는 두 가지 원칙이 있다. 첫째, 단일 목표 부여. 서브에이전트 하나에 하나의 구체적 목표만 준다. 둘째, 최소 권한 스코핑. 서브에이전트가 접근할 수 있는 파일과 도구를 명시적으로 제한한다.

비용 최적화 관점에서 중요한 포인트는 모델 분리다. 메인 에이전트는 Opus(추론 집약적 작업)를 쓰고, 서브에이전트는 Sonnet(비용 효율적 실행)을 쓴다. 유출 소스의 에이전트 디스패치 로직에서 이 패턴이 명확하게 구현되어 있었다.

Agent Teams과 Worktree — 병렬 작업의 실체

Agent Teams 공식 문서가 설명하는 병렬 작업 모델은 단순한 멀티스레딩이 아니다. 팀 리드(team lead)가 태스크 리스트를 관리하고, 각 팀원(team member)이 독립적으로 동시 작업하는 구조다. 팀 리드는 작업을 분배하고 결과를 취합하며, 팀원 간 파일 충돌이 발생하지 않도록 스코프를 분리한다.

이 병렬 작업에서 파일 충돌 문제를 근본적으로 해결하는 것이 Worktree(워크트리) 격리다. --worktree 플래그를 사용하면 브랜치별로 독립된 디렉토리가 생성되고, 각 에이전트가 서로 다른 워크트리에서 작업한다. Git의 git worktree 기능을 활용한 것인데, Claude Code는 이것을 에이전트 격리 메커니즘으로 확장했다.

실전에서 이 패턴이 효과적인 경우는 명확하다. 프론트엔드와 백엔드를 동시에 수정해야 할 때, 또는 여러 독립적인 버그 수정을 병렬로 처리할 때다. 단, 공유 파일(예: 타입 정의, 설정 파일)이 있으면 특정 에이전트에 배타적으로 할당해야 한다. 유출 소스의 충돌 감지 로직은 이 원칙을 엄격하게 적용하고 있었다.

미공개 기능과 고급 설정 — 소스에서만 보이는 것들

유출 소스에서 발견된 미공개 기능 중 실전 활용에 직접 영향을 미치는 것들이 있다.

플러그인/스킬 시스템은 프로그레시브 디스클로저(progressive disclosure, 점진적 노출) 패턴을 따른다. 스킬의 메타데이터(이름, 설명, 트리거 조건)는 약 100 토큰 수준으로 항상 로드되어 있고, 실제 실행 시에만 전체 내용(5,000 토큰 이하)을 로드한다. 이 방식으로 수십 개의 스킬을 등록해도 컨텍스트 윈도우를 낭비하지 않는다.

샌드박스 문서에서 설명하는 기본 격리에 더해, settings.json의 고급 옵션으로 더 세밀한 제어가 가능하다:

{
  "permissions": {
    "allowedDomains": ["api.github.com", "registry.npmjs.org"],
    "filesystem": {
      "allowWrite": ["./src", "./tests"],
      "denyRead": ["./secrets", "./.env"]
    }
  },
  "autoCompactWindow": 0.7,
  "effortLevel": "high"
}

allowedDomains는 에이전트가 접근할 수 있는 네트워크 도메인을 화이트리스트(whitelist) 방식으로 제한한다. filesystem의 allowWrite와 denyRead는 파일 시스템 접근을 디렉토리 단위로 통제한다. autoCompactWindow는 컨텍스트 윈도우의 70%가 차면 자동으로 압축하는 임계값이고, effortLevel은 에이전트의 추론 깊이를 조절한다.

KAIROS(24시간 자율 에이전트)와 안티 디스틸레이션(경쟁사 학습 방해 장치)은 이전 분석 글에서 상세히 다뤘다. 여기서 강조할 점은, 이 기능들이 피처 플래그 뒤에 숨어 있지만 프로덕션 번들에 포함되어 있다는 사실이다. Anthropic이 이 기능들을 언제 활성화할지 모르지만, 아키텍처적으로는 이미 준비가 끝난 상태다.

시사점 — 소스 코드가 보여주는 확장 전략

Claude Code를 효과적으로 쓰려면 세 가지 레이어를 이해해야 한다. 첫째는 선언적 레이어(CLAUDE.md, rules/)로 에이전트에게 프로젝트의 맥락을 알려주는 것이다. 둘째는 프로그래밍 레이어(Hooks, settings.json)로 에이전트의 행동을 확정적으로 제어하는 것이다. 셋째는 연결 레이어(MCP, 서브에이전트, Agent Teams)로 에이전트의 능력을 외부로 확장하는 것이다.

유출 소스가 보여주는 가장 중요한 통찰은, Claude Code가 단일 도구가 아니라 확장 가능한 플랫폼으로 설계되어 있다는 점이다. Tool Search의 동적 로딩, 스킬의 프로그레시브 디스클로저, Worktree 기반 격리 — 이 모든 설계 결정이 "더 많은 기능을 더 적은 비용으로" 제공하기 위한 것이다.

공식 문서만으로도 상당한 확장이 가능하지만, 소스 코드를 읽으면 그 확장의 한계와 내부 동작 원리까지 이해할 수 있다. 도구를 깊이 이해하는 것과 표면만 아는 것의 차이는, 결국 그 도구로 만들 수 있는 결과물의 차이로 이어진다.

참고 자료

아래 링크에서 Claude Code의 공식 문서와 유출 소스 분석 원문을 확인할 수 있다.

AI 개발 도구와 에이전트 트렌드를 매일 분석합니다. spoonai.me에서 뉴스레터를 구독하세요.