해커톤 우승자가 밝히는 Claude Code의 진짜 비밀

10개월간 매일 Claude Code를 사용하며 앤스로픽 해커톤을 우승한 21세 개발자 Affaan Mustafa가 공개한 실전 설정과 워크플로우의 핵심을 정리합니다.

---

프롤로그: 900만 뷰를 기록한 가이드의 주인공

2026년 1월, X(구 트위터)에 한 게시물이 등장했습니다. 제목은 “The Shorthand Guide to Everything Claude Code”였습니다. 이 게시물은 며칠 만에 90만 뷰를 기록했고, 1만 명 이상이 북마크했습니다. 단순한 홍보나 과장이 아니었습니다. 이것은 실전에서 검증된 지식의 결정체였습니다.

작성자는 Affaan Mustafa(X에서 @affaanmustafa, 별칭 cogsec)입니다. 그는 21세의 젊은 개발자지만, 이미 상당한 경력을 쌓았습니다. 18세에 마이크로소프트의 지원을 받는 AI 스타트업 DCUBE를 창업했고, 솔라나(Solana) 블록체인에서 자율 거래 에이전트를 개발했습니다. 그가 만든 프로젝트 중 하나는 시가총액 3,800만 달러에 도달했고, 7만 명의 동시 시청자가 그가 라이브 코딩하는 모습을 지켜봤습니다. 그는 1만 7천 개 이상의 스타를 받은 elizaOS 프레임워크에 기여했으며, 워싱턴 대학교 박사 과정을 중퇴하고 계속 프로덕트를 만드는 길을 선택했습니다.

가장 중요한 이력은 2025년 9월 뉴욕에서 열린 Anthropic x Forum Ventures 해커톤에서의 우승입니다. 그는 동료 개발자 David Rodriguez와 함께 AI 기반 고객 발견 플랫폼인 Zenith를 전적으로 Claude Code만을 사용해 구축했습니다. 우승 상금에는 1만 5천 달러 상당의 Anthropic 크레딧이 포함되었습니다. (그의 말에 따르면 “그 정도 두뇌를 가진 사람이라면 일주일도 안 돼서 다 쓸 수 있는” 양이었습니다.)

그러므로 그가 “10개월간 매일 사용한 후의 완전한 설정”을 공유할 때, 이것은 이론이 아닙니다. 해커톤의 압박과 수개월간의 실전 작업에서 살아남은 것들을 문서화한 것입니다.

---

첫 번째 핵심: 자동화를 계층으로 재정의하다

도구의 나열에서 계층의 조합으로

우리는 자동화를 떠올릴 때 흔히 특정 도구들을 연상합니다. ESLint가 코드 스타일을 검사하고, Prettier가 자동으로 포맷팅하며, GitHub Actions가 테스트를 실행합니다. 각 도구는 명확한 역할이 있고, 설치하면 그 역할을 수행합니다. 이것이 전통적인 개발 도구의 패러다임입니다.

그러나 Affaan이 10개월간 Claude Code를 사용하며 구축한 설정을 보면, 완전히 다른 관점이 드러납니다. 이것은 도구들의 단순한 나열이 아닙니다. 서로 다른 시점과 범위에서 작동하는 세 개의 계층이 유기적으로 결합된 시스템입니다. 마치 오케스트라처럼, 각 섹션은 서로 다른 역할을 하지만 하나의 교향곡을 만들어냅니다.

이 시스템은 세 개의 레이어로 구성됩니다:

1. 첫 번째 레이어 (Skills & Commands): “무엇을” 할 것인가를 정의
2. 두 번째 레이어 (Hooks): “언제” 할 것인가를 결정
3. 세 번째 레이어 (Subagents): “누가” 할 것인가를 분리

각 레이어를 자세히 살펴보겠습니다.

1층: Skills와 Commands - 지식과 실행의 분리

Skills: 광범위한 지침의 저장소

Skills는 ~/.claude/skills/ 디렉토리에 마크다운 형태로 저장되는 워크플로우 정의 파일들입니다. 이것들은 Claude에게 특정 영역의 전문 지식을 제공하는 일종의 “교과서”입니다.

Affaan의 실제 설정을 보면:

~/.claude/skills/
├── coding-standards.md        # 프로그래밍 언어별 베스트 프랙티스
├── backend-patterns.md         # API, 데이터베이스, 캐싱 패턴
├── frontend-patterns.md        # React, Next.js 패턴
├── tdd-workflow/              # 테스트 주도 개발 방법론
├── security-review/           # 보안 체크리스트
└── clickhouse-io.md           # ClickHouse 분석 패턴

각 Skill은 특정 도메인의 지식을 캡슐화합니다. 예를 들어, coding-standards.md는 변수 네이밍 규칙, 함수 길이 제한, 에러 처리 패턴 등을 정의합니다. tdd-workflow/는 테스트 우선 개발의 단계별 프로세스를 담고 있습니다.

Skills의 특별한 점은 자동 활성화입니다. Claude는 대화의 맥락을 분석해, 관련된 Skill을 자동으로 로드합니다. 개발자가 “TDD로 개발해줘”라고 명시적으로 요청하지 않아도, 테스트 관련 대화가 시작되면 tdd-workflow Skill이 활성화됩니다.

Commands: 즉시 실행 가능한 워크플로우

Commands는 ~/.claude/commands/에 저장되며, 슬래시(/)로 시작하는 명령어로 즉시 실행할 수 있습니다. Skills가 “무엇을 알아야 하는가”라면, Commands는 “무엇을 해야 하는가”입니다.

Affaan의 실제 Commands:

~/.claude/commands/
├── tdd.md                     # /tdd - 테스트 주도 개발 시작
├── refactor-clean.md          # /refactor-clean - 죽은 코드 정리
├── security-review.md         # /security-review - 보안 점검
└── e2e.md                     # /e2e - E2E 테스트 실행

/refactor-clean을 입력하면 Claude는:

1. 사용되지 않는 코드 탐지
2. 불필요한 마크다운 파일 제거
3. import 문 정리
4. console.log 제거

이 모든 것이 하나의 명령으로 실행됩니다.

Skills와 Commands의 핵심적 차이

• 범위: Skills는 광범위한 지침, Commands는 구체적인 실행 진입점
• 호출: Skills는 자동 활성화, Commands는 수동 실행
• 목적: Skills는 “어떻게 하는지 아는 것”, Commands는 “지금 당장 하는 것”

체이닝: 복합 워크플로우의 구성

여기서 진짜 마법이 시작됩니다. Skills와 Commands는 체이닝될 수 있습니다. 하나의 프롬프트에서 여러 Commands를 연결해 복합적인 워크플로우를 구성할 수 있습니다:

/tdd /e2e /test-coverage

새로운 결제 기능을 구현해주세요.

Claude는 이 명령을 받고:

1. TDD Skill을 활성화하여 테스트 우선 개발 원칙 적용
2. E2E 테스트 Skill을 참조하여 엔드투엔드 시나리오 작성
3. 테스트 커버리지 Skill로 80% 이상 커버리지 확보

모두 자동으로, 일관되게 수행됩니다.

2층: Hooks - 자동 반응 시스템

Skills와 Commands가 명시적 호출을 기다리는 반면, Hooks는 특정 이벤트에 자동으로 반응합니다. 이것이 두 번째 레이어의 핵심입니다.

Hooks는 크게 세 가지 타입이 있습니다:

1. PreToolUse: 도구 실행 전 개입

Claude가 도구를 사용하기 직전에 실행됩니다. Affaan의 실제 설정 예시:

{
  "matcher": "tool == 'Bash' && (tool_input.command matches 'npm|yarn|pytest')",
  "hooks": [{
    "type": "prompt",
    "message": "⚠️  장시간 실행될 수 있는 명령입니다. tmux 세션 사용을 권장합니다."
  }]
}

npm install이나 pytest 같은 명령이 감지되면, Claude는 자동으로 tmux 세션 사용을 권고합니다. 개발자가 매번 “tmux에서 실행해줘”라고 요청할 필요가 없습니다.

2. PostToolUse: 도구 실행 후 자동화

도구가 실행된 직후에 작동합니다. 이것이 진짜 생산성의 비밀입니다:

{
  "matcher": "tool == 'Edit' && tool_input.file_path matches '\\.(ts|tsx)$'",
  "hooks": [
    {
      "type": "command",
      "command": "prettier --write \"$file_path\"",
      "description": "자동 포맷팅"
    },
    {
      "type": "command",
      "command": "tsc --noEmit",
      "description": "타입 체크"
    },
    {
      "type": "command",
      "command": "if grep -q 'console\\.log' \"$file_path\"; then echo '⚠️ console.log 추가됨'; fi",
      "description": "디버그 로그 경고"
    }
  ]
}

TypeScript 파일이 편집될 때마다:

1. Prettier로 자동 포맷팅
2. TypeScript 컴파일러로 타입 체크
3. console.log 추가 시 경고

이 모든 것이 자동으로, 개발자가 요청하지 않아도 실행됩니다.

3. Stop: 작업 완료 시 최종 점검

Claude가 응답을 마치고 작업을 완료할 때 실행됩니다:

{
  "matcher": "stop",
  "hooks": [{
    "type": "command",
    "command": "find . -name '*.ts' -o -name '*.tsx' | xargs grep -l 'console\\.log' | head -5",
    "description": "세션 전체에서 console.log 최종 확인"
  }]
}

세션이 끝날 때, 남아있는 모든 console.log를 최종적으로 감사합니다.

Hooks의 핵심은 타이밍입니다

개발자가 매번 “포맷팅 해줘”, “타입 체크 해줘”라고 요청할 필요가 없습니다. 시스템이 적절한 시점에 알아서 개입합니다. 이것은 단순한 편의성을 넘어, 일관성과 품질을 보장하는 가드레일입니다.

Affaan은 이렇게 말합니다:

“Hooks는 프롬프트 기반 규칙보다 결정론적 보장을 제공한다. 이것은 Claude가 ‘해야 한다고 생각하는’ 것이 아니라, ‘반드시 해야 하는’ 것이다.”

3층: Subagents - 전문가 팀의 구성

세 번째 레이어에서 자동화의 성격이 근본적으로 달라집니다. 앞선 두 레이어가 ‘무엇을’, ‘언제’ 할지를 정의했다면, Subagents는 ‘누가’ 할지를 분리합니다.

Subagent의 개념

Subagent는 특정 작업을 전담하는 독립적인 Claude 인스턴스입니다. 메인 Claude는 오케스트라의 지휘자가 되고, Subagents는 각 섹션의 연주자가 됩니다.

Affaan의 실제 Subagent 구성:

~/.claude/agents/
├── planner.md               # 기능 구현 계획 수립
├── architect.md             # 시스템 설계 결정
├── tdd-guide.md             # 테스트 주도 개발
├── code-reviewer.md         # 품질 및 보안 리뷰
├── security-reviewer.md     # 취약점 분석
├── build-error-resolver.md  # 빌드 에러 해결
├── e2e-runner.md            # Playwright E2E 테스트
├── refactor-cleaner.md      # 죽은 코드 정리
└── doc-updater.md           # 문서 동기화

Subagent의 구조 예시:

---
name: code-reviewer
description: 품질, 보안, 유지보수성 코드 리뷰
tools: Read, Grep, Glob, Bash
model: opus
---

당신은 시니어 코드 리뷰어입니다.

## 리뷰 체크리스트
1. 코드 품질 (가독성, 복잡도)
2. 보안 취약점
3. 성능 이슈
4. 테스트 커버리지
5. 문서화

핵심 설계 원칙: 제한된 권한

각 Subagent는 특정 도구와 MCP에만 접근할 수 있도록 권한이 제한됩니다:

• security-reviewer: 보안 관련 도구만 (Read, Grep, Glob)
• e2e-runner: Playwright 관련 도구만
• doc-updater: 문서 파일만 편집 가능

이렇게 권한을 제한하면:

1. 예상치 못한 변경 방지
2. 각 Subagent의 역할이 명확
3. 메인 에이전트의 작업과 충돌 없음

컨텍스트 보존: Subagents의 진짜 가치

Subagents의 가장 중요한 이점은 메인 에이전트의 컨텍스트 윈도우를 보호한다는 것입니다.

메인 Claude (200k 토큰):
├─ 프로젝트 전체 구조: 20k
├─ 대화 히스토리: 30k
├─ CLAUDE.md: 10k
└─ 여유 공간: 140k

보안 리뷰를 직접 수행하면:
├─ 보안 분석: 50k 소비
└─ 여유 공간: 90k로 감소

보안 리뷰를 Subagent에 위임하면:
├─ Subagent 진행 상황: 2k만 소비
└─ 여유 공간: 138k 유지!

메인 Claude는 전체 맥락을 유지하면서, 복잡한 세부 작업은 Subagent에게 위임합니다. Subagent는 독립적인 200k 컨텍스트에서 작업하고, 결과만 메인에게 전달합니다.

세 계층의 조화: 리팩토링 예시

이제 세 계층이 어떻게 맞물려 작동하는지 구체적인 예시로 살펴보겠습니다.

사용자 요청:

/refactor-clean

실행 과정:

1층 (Skills & Commands):

/refactor-clean 명령 감지
→ refactor-clean.md Command 실행
→ 관련 Skills 자동 로드:
  - coding-standards.md (모듈화 우선, 메가 파일 지양)
  - backend-patterns.md (죽은 코드 제거 패턴)

2층 (Hooks):

파일 수정될 때마다 PostToolUse Hook 자동 실행:
→ Prettier 포맷팅
→ TypeScript 타입 체크
→ console.log 경고

3층 (Subagents):

실제 리팩토링 작업:
→ refactor-cleaner.md Subagent에 위임
→ Subagent가 독립 컨텍스트에서:
  1. 코드베이스 스캔
  2. 미사용 함수/변수 식별
  3. 중복 코드 제거
  4. 모듈화 개선
→ 결과를 메인 Claude에 전달

메인 Claude의 역할:

전체 진행 상황 모니터링
→ Subagent 작업 조율
→ Hooks 자동 실행 확인
→ 최종 결과 사용자에게 보고

모든 것이 자동으로, 일관되게, 효율적으로 실행됩니다.

패러다임의 전환

Affaan의 설정이 보여주는 것은 단순히 “더 나은 자동화”가 아닙니다. 이것은 자동화에 대한 사고방식의 전환입니다.

전통적 자동화 사고:

"이 도구가 저 작업을 빠르게 해준다"
→ 도구 중심
→ 속도 개선

계층적 자동화 사고:

"이 작업 전체를 어떻게 구조화할 것인가"
→ 시스템 중심
→ 작업의 재정의

속도의 개선은 부수적입니다. 진짜 가치는 작업의 재정의에 있습니다. 개발자는 더 이상 “코드를 작성하는 사람”이 아니라 “시스템을 설계하고 조율하는 사람”이 됩니다.

---

두 번째 핵심: 컨텍스트 윈도우의 정치경제학

200k 토큰의 환상

Claude Code의 공식 스펙을 보면 200,000 토큰의 컨텍스트 윈도우가 명시되어 있습니다. 이 숫자는 인상적으로 보입니다. 충분해 보입니다. 긴 코드베이스도 담을 수 있고, 복잡한 대화 맥락도 유지할 수 있을 것 같습니다.

하지만 Affaan의 10개월 실전 경험은 달랐습니다. 그는 자신의 가이드에서 이렇게 경고합니다:

“여러 MCP와 플러그인을 켜는 순간, 실제 사용 가능한 컨텍스트는 70k까지 떨어질 수 있다. 이론적 용량과 실제 용량 사이에 130k의 간극이 있다.”

200k 토큰이 70k로 줄어든다. 65%가 증발합니다. 어디로 사라지는 걸까요?

도구 정의가 먹는 컨텍스트

MCP (Model Context Protocol)의 숨겨진 비용

MCP는 Claude를 외부 서비스와 연결하는 프로토콜입니다. 매우 강력합니다:

• Supabase MCP: Claude가 직접 데이터베이스에 SQL 실행
• GitHub MCP: PR 생성, 이슈 관리, 코드 리뷰
• Vercel MCP: 배포 제어 및 모니터링
• Playwright MCP: 브라우저 자동화

각 MCP는 놀라운 기능을 제공합니다. 하지만 각 MCP가 활성화될 때마다, 그 도구의 정의와 사용법이 컨텍스트 윈도우에 올라갑니다.

실제 토큰 소비량 (2.1.7 이전):

Docker MCP: 135개 도구 → 125,000 토큰!
GitHub MCP: 27개 도구 → 18,000 토큰
Playwright MCP: 21개 도구 → 13,647 토큰
Supabase MCP: 15개 도구 → 10,000 토큰

MCP 14개를 모두 활성화하면:

총 도구 정의: 약 67,000 토큰 소비
실제 작업 공간: 133,000 토큰만 남음

플러그인의 추가 부담

플러그인은 MCP와 Skills, Commands를 패키징해서 설치를 간편하게 만듭니다. 하지만 각 플러그인도 컨텍스트를 소비합니다:

• typescript-lsp 플러그인: 에디터 없이도 실시간 타입 체크
• 하지만 TypeScript 언어 서버 정의가 컨텍스트에 추가됨

플러그인 14개를 모두 활성화하면 추가로 수만 토큰이 사라집니다.

결과:

컨텍스트 윈도우: 200k tokens

시스템 프롬프트: 3k (1.5%)
시스템 도구: 14k (7%)
MCP 도구: 67k (33.5%) ← 주범!
플러그인: 16k (8%)
━━━━━━━━━━━━━━━━━━━━━━━━━
사용됨: 100k (50%)
여유: 100k (50%)

절반이 사라졌습니다. 한 줄도 입력하기 전에.

Affaan의 해법: “20-30-10-80” 규칙

10개월의 경험을 통해 Affaan이 도달한 경험적 규칙:

설정: 20-30개 MCP
활성화: 10개 미만
도구: 80개 미만

전략: 선택적 활성화

전역 설정 (~/.claude.json):

{
  "mcpServers": {
    "supabase": { ... },
    "github": { ... },
    "vercel": { ... },
    "docker": { ... },
    "playwright": { ... },
    "cloudflare": { ... },
    "railway": { ... },
    "clickhouse": { ... },
    "firecrawl": { ... },
    // ... 총 14개 등록
  }
}

프로젝트별 설정 (.claude/config.json):

{
  "disabledMcpServers": [
    "docker",
    "cloudflare",
    "railway",
    "clickhouse",
    // 이 프로젝트에서는 사용 안 함
  ]
}

실제 활성화 (웹 프로젝트):

• Supabase (데이터베이스)
• GitHub (버전 관리)
• Vercel (배포)
• Playwright (테스트)
• 총 4개만 활성화

결과:

MCP 도구: 25k tokens (12.5%)
실제 사용 가능: 175k tokens (87.5%)

절약된 42k 토큰은 엄청난 차이를 만듭니다.

게임 체인저: MCP Tool Search (2.1.7)

2026년 1월 16일, Claude Code 2.1.7이 출시되며 근본적인 해결책이 도입되었습니다: MCP Tool Search.

이전 방식 (Eager Loading):

세션 시작
→ 모든 MCP 도구 정의 로드
→ 67k 토큰 선점
→ 작업 시작

새 방식 (Lazy Loading):

세션 시작
→ 도구 인덱스만 로드 (5k 토큰)
→ 필요할 때 도구 로드
→ 작업 시작

자동 활성화 조건:

MCP 도구 정의가 컨텍스트의 10%를 초과하면 자동으로 Tool Search 모드로 전환됩니다. 대부분의 경우 개발자가 아무것도 하지 않아도 자동으로 작동합니다.

실측 결과:

이전 (Eager Loading):
MCP 도구: 67,300 tokens (33.7%)
사용 가능: 132,700 tokens (66.3%)

이후 (Lazy Loading):
MCP 도구: 8,500 tokens (4.25%)
사용 가능: 191,500 tokens (95.75%)

절약: 58,800 tokens (46.9% 감소!)

작동 방식:

1. 경량 인덱스 생성:

   docker-mcp:
     - list-containers: Docker 컨테이너 목록 조회
     - get-logs: 컨테이너 로그 조회
     (한 줄 설명만 로드)
   

2. 키워드 매칭:

   사용자: "Docker 컨테이너 목록 보여줘"
   → "docker", "container", "list" 감지
   → docker-mcp의 list-containers 도구 전체 스키마 로드
   → 도구 실행
   

3. 세션 캐싱:

   한 번 로드된 도구는 세션 동안 유지
   추가 호출 시 재로드 불필요
   

Affaan의 가이드가 공개된 후 불과 며칠 만에 이 업데이트가 나왔습니다. 커뮤니티의 요청이 즉각 반영된 것입니다.

왜 컨텍스트가 중요한가

컨텍스트는 단순한 저장 공간이 아닙니다. 이것은 Claude의 작업 기억(working memory) 입니다:

• 앞서 어떤 코드를 봤는지
• 어떤 설계 결정을 내렸는지
• 대화가 어떤 맥락에서 진행되고 있는지

컨텍스트가 부족하면 일어나는 일:

복잡한 리팩토링 시작 (09:00)
Claude: "User 클래스는 싱글턴 패턴으로 설계하겠습니다."

[여러 작업 진행, 컨텍스트 압박]

20분 후 (09:20)
Claude: "User 클래스를 일반 클래스로 만들겠습니다."

개발자: "??? 아까 싱글턴이라고 했잖아요?"
Claude: "죄송합니다. 이전 결정이 컨텍스트에서 밀려났습니다."

일관성 없는 코드베이스가 만들어집니다. 같은 질문을 반복해야 하고, 이전 결정과 모순되는 변경이 발생합니다.

도구 과다의 숨겨진 비용

활성화된 도구가 많을수록 Claude는 매 작업마다:

• 80개 도구 중 어느 걸 쓸지 판단
• 도구 조합 순서 결정
• 각 도구의 파라미터 검토

이 선택 자체가 인지 자원을 소모합니다. 도구가 적으면 선택이 빠르고 명확합니다. 도구가 많으면 선택에 에너지가 분산됩니다.

핵심 교훈

Affaan의 경험이 보여주는 것:

Claude Code를 잘 활용하는 건 기능을 최대한 켜는 게 아닙니다.

✗ 잘못된 접근:
"모든 MCP를 활성화해서 최대 기능 확보!"
→ 컨텍스트 고갈
→ 성능 저하
→ 일관성 상실

✓ 올바른 접근:
"이 프로젝트/작업에 필요한 도구만 활성화"
→ 컨텍스트 보존
→ 빠른 판단
→ 일관된 품질

컨텍스트는 희소 자원입니다. 경제학의 기본 원리가 여기에도 적용됩니다: 희소 자원의 관리가 시스템 성능을 결정합니다.

---

세 번째 핵심: 분리가 병렬성을 만든다

병렬 처리의 함정

효율성을 높이는 직관적인 방법은 작업을 동시에 처리하는 것입니다. 하나씩 순차적으로 하면 시간이 오래 걸리니, 여러 작업을 병렬로 돌립니다. 간단해 보입니다.

하지만 병렬 처리는 단순히 “동시에”만으로는 되지 않습니다. 서로 충돌하지 않아야 합니다.

작업 A: src/utils/helper.ts 수정
작업 B: src/utils/helper.ts 수정

동시 실행 → 충돌! 💥

결과:
- A의 변경이 B에 의해 덮어씌워짐
- B의 컨텍스트가 A의 변경으로 오염됨
- 예측 불가능한 코드베이스

Affaan이 발견한 것은 세 가지 병렬화 기법이 모두 같은 원리를 따른다는 것입니다:

“먼저 분리하고, 그 다음 동시에 실행한다”

기법 1: /fork - 대화 세션의 분리

/fork는 현재 진행 중인 Claude 대화를 복제해서 별도의 세션으로 분기시키는 명령입니다.

사용 시나리오:

프로젝트: 전자상거래 플랫폼
현재 작업: 인증 시스템 구현 중
새 요구사항: 동시에 결제 기능도 시작해야 함

전통적 접근 (순차):

1. 인증 시스템 완료 (30분)
2. 결제 기능 시작 (30분)
총: 60분

Fork 활용 (병렬):

# 원본 세션 (터미널 1)
현재: 인증 시스템 작업 중

# Fork 명령
> /fork payment-feature

# 분기된 세션 (터미널 2)
새 세션: payment-feature
결제 기능 독립적으로 시작

결과:

터미널 1: 인증 시스템 (30분)
터미널 2: 결제 기능 (30분)
병렬 실행 → 총 30분

성공의 조건: 비중첩(non-overlapping) 작업

Affaan이 강조하는 핵심 원칙:

✓ 작동하는 경우:
세션 A: src/auth/* 수정
세션 B: src/payment/* 수정
→ 파일 범위 분리, 충돌 없음

✗ 작동하지 않는 경우:
세션 A: src/utils/helper.ts 수정
세션 B: src/utils/helper.ts 수정
→ 파일 충돌, 예측 불가능

분기의 가치는 범위가 분리된 작업에서만 발휘됩니다.

기법 2: Git Worktrees - 코드베이스 자체의 분리

/fork가 대화의 분리라면, Git Worktrees는 코드베이스 자체를 분리합니다. 이것은 한 단계 더 근본적인 분리입니다.

Git Worktrees란?

하나의 Git 저장소에서 여러 개의 독립적인 체크아웃을 생성하는 기능입니다. 각 worktree는 별도의 디렉토리에 존재하며, 서로 완전히 독립적입니다.

설정 과정:

# 메인 프로젝트
cd ~/myproject

# Feature A용 worktree 생성
git worktree add ../myproject-feature-a feature-a

# Feature B용 worktree 생성
git worktree add ../myproject-feature-b feature-b

결과 구조:

~/myproject/              # 메인 (main 브랜치)
~/myproject-feature-a/    # Feature A (독립 디렉토리)
~/myproject-feature-b/    # Feature B (독립 디렉토리)

각 worktree에서 Claude 실행:

# 터미널 1
cd ~/myproject-feature-a
claude
> "인증 시스템 구현해줘"

# 터미널 2
cd ~/myproject-feature-b
claude
> "결제 기능 구현해줘"

# 터미널 3
cd ~/myproject
# 메인 브랜치에서 다른 작업

왜 Worktrees가 더 강력한가?

/fork와 비교:

/fork:
- 분리: 대화 세션만
- 파일 시스템: 공유
- 충돌 가능성: 중간

Worktrees:
- 분리: 파일 시스템 자체
- 파일 시스템: 완전 독립
- 충돌 가능성: 구조적으로 불가능

같은 파일을 건드릴 가능성 자체가 구조적으로 제거됩니다. 충돌 회피가 아니라 충돌 불가능의 상태를 만듭니다.

실전 시나리오: 긴급 핫픽스

상황:
- 메인 브랜치: feature-payment 개발 중 (20개 파일 수정, 커밋 안 함)
- 긴급: 프로덕션 버그 발견

전통적 방식 (Git stash):
1. git stash (작업 임시 저장)
2. git checkout main
3. git checkout -b hotfix/urgent
4. 버그 수정
5. git checkout feature-payment
6. git stash pop (작업 복원)
7. 컨텍스트 재설정...

Worktrees 방식:
1. 터미널 1: feature-payment 작업 계속
2. 터미널 2: cd ~/project-hotfix && claude
3. 버그 수정
4. 상태 전환 없음!

완전히 독립적입니다. 메인 작업은 중단 없이 계속되고, 핫픽스는 별도로 처리됩니다.

Affaan의 실전 활용:

Affaan은 해커톤에서 이렇게 작업했습니다:

~/zenith-main/          # 메인 개발
~/zenith-feature-ui/    # UI 컴포넌트 (Claude 1)
~/zenith-feature-api/   # API 엔드포인트 (Claude 2)
~/zenith-hotfix/        # 버그 수정 (Claude 3)

동시에 3-4개의 Claude 인스턴스를 운영하며, 각각 독립적인 기능을 개발했습니다.

기법 3: Subagents - 역할의 분리

Subagents는 작업의 성격을 분리합니다. /fork가 세션을, Worktrees가 파일 시스템을 분리한다면, Subagents는 역할과 권한을 분리합니다.

Affaan의 Subagent 아키텍처:

security-reviewer.md:
- 역할: 보안 취약점 분석
- 도구: Read, Grep, Glob (읽기만)
- 접근: 코드 읽기만 가능, 수정 불가

code-reviewer.md:
- 역할: 코드 품질 검토
- 도구: Read, Grep, Glob (읽기만)
- 접근: 분석만 수행

e2e-runner.md:
- 역할: E2E 테스트 실행
- 도구: Bash (Playwright 전용)
- 접근: tests/ 디렉토리만

병렬 실행 패턴:

사용자: "결제 시스템 구현하고 리뷰해줘"

메인 Claude:
├─ [병렬 실행]
│   ├─ Architect Subagent → 시스템 설계
│   └─ Research Subagent → 베스트 프랙티스 조사
│
├─ [구현]
│   └─ Builder Subagent → 코드 작성
│
└─ [병렬 검증]
    ├─ Code Reviewer → 품질 검토
    ├─ Security Reviewer → 보안 분석
    └─ Test Runner → 테스트 실행

왜 충돌이 없는가?

역할의 명확한 분리:

Builder Subagent:
- 도구: Edit, Bash, Read
- 접근: src/payment/*
- 역할: 구현

Test Subagent:
- 도구: Bash (테스트 전용)
- 접근: tests/payment/*
- 역할: 테스트

Security Reviewer:
- 도구: Read, Grep (읽기만!)
- 접근: 모든 파일 (읽기)
- 역할: 분석만, 수정 불가

접근 범위가 완전히 분리되어 있습니다. 리뷰어는 코드를 수정하지 않고, 각 구현 Subagent는 자신의 영역만 건드립니다.

세 기법의 공통 원리

Affaan이 발견한 근본적 패턴:

병렬성은 속도의 문제처럼 보이지만, 본질은 분리의 문제다.

분리 없는 병렬:
작업 A + 작업 B 동시 실행
→ 충돌
→ 실패

분리 후 병렬:
작업 A (범위 X) + 작업 B (범위 Y) 동시 실행
→ 범위 분리
→ 성공

분리의 단위만 다를 뿐:

/fork      → 대화 세션 분리
Worktrees  → 파일 시스템 분리
Subagents  → 역할과 권한 분리

순서는 항상 동일:

1. 먼저 나눈다 (분리)
2. 그 다음 동시에 실행한다 (병렬)

일반화: 시스템 설계의 보편 원리

Affaan이 발견한 이 원리는 Claude Code를 넘어 일반적인 시스템 설계에도 적용됩니다:

마이크로서비스 아키텍처:

모놀리스: 모든 기능이 하나의 코드베이스
→ 확장 어려움, 충돌 많음

마이크로서비스: 각 서비스가 독립적
→ 분리 → 병렬 배포 가능

데이터베이스 샤딩:

단일 DB: 모든 데이터가 한 곳
→ 병목 발생

샤딩: 데이터를 분리
→ 분리 → 병렬 쿼리 가능

팀 조직:

기능 팀: 각 팀이 특정 기능 담당
→ 분리 → 병렬 개발 가능

모두 같은 패턴입니다: 분리가 병렬성을 만든다.

---

에필로그: 10개월의 결정체

Affaan Mustafa의 가이드가 90만 뷰를 기록하고 1만 명에게 북마크된 이유는 단순합니다. 이것은 이론이 아니라 실전에서 검증된 지혜이기 때문입니다.

핵심 교훈 요약

1. 자동화를 계층으로 재정의하라

1층 (Skills & Commands): "무엇을" 할 것인가
2층 (Hooks): "언제" 할 것인가
3층 (Subagents): "누가" 할 것인가

→ 작업의 재정의
→ 시스템 사고

2. 컨텍스트는 희소 자원이다

200k 토큰 ≠ 200k 사용 가능

"20-30-10-80" 규칙:
- 20-30개 설정
- 10개 미만 활성화
- 80개 미만 도구

→ 선택적 활성화
→ Tool Search 활용

3. 분리가 병렬성을 만든다

/fork: 대화 분리
Worktrees: 파일 시스템 분리
Subagents: 역할 분리

→ 먼저 나누고
→ 그 다음 동시에

실천 가이드

시작하는 개발자를 위한 로드맵:

1주차: 기본 설정

1. CLAUDE.md 작성
2. 자주 쓰는 Commands 2-3개 만들기
3. 기본 Hooks 설정 (포맷팅, 타입 체크)

2-4주차: 확장

1. 필수 Skills 작성 (코딩 표준, TDD)
2. MCP 선택적 활성화 연습
3. 첫 Subagent 만들기 (code-reviewer)

1-3개월: 최적화

1. 프로젝트별 설정 커스터마이징
2. Worktrees로 병렬 작업 시도
3. 컨텍스트 사용량 모니터링

3개월+: 마스터

1. 팀 설정 공유
2. 고급 Subagent 아키텍처
3. 자동화 워크플로우 완성

Affaan의 저장소

Affaan은 자신의 전체 설정을 GitHub에 공개했습니다:

저장소: github.com/affaan-m/everything-claude-code

포함 내용:

• 실전 Subagents (planner, architect, reviewer 등)
• Skills 모음 (코딩 표준, TDD, 보안)
• Commands 예시
• Hooks 설정
• MCP 구성

라이선스: MIT - 자유롭게 사용, 수정, 배포 가능

현재 2,300개 이상의 스타를 받았으며, 계속 업데이트되고 있습니다.

마지막 조언

Affaan의 가이드 마지막에 있는 문구:

“이 설정들은 내 워크플로우에 맞춰져 있다. 당신은 다음을 해야 한다:

1. 그대로 복사하지 말고, 이해하라
2. 자신의 필요에 맞게 조정하라
3. 실험하고 개선하라
4. 가능하면 다시 기여하라”

도구는 수단이지 목적이 아닙니다. Claude Code의 진짜 가치는 작업을 재정의하고, 시스템을 설계하며, 생산성을 혁신하는 능력입니다.

Affaan의 10개월은 그 가능성을 보여줍니다. 당신의 다음 10개월은 어떨까요?

---

참고 자료

원본 소스

• X 스레드: @affaanmustafa의 가이드
• GitHub: everything-claude-code
• Medium 분석: JP Caparas의 해설

공식 문서

• Claude Code 공식 문서
• Agent Skills 가이드
• Common Workflows

관련 도구

• ccswitch: Worktree 관리 자동화 도구
• Crystal: 다중 Claude 세션 관리 데스크톱 앱
• GitButler: Hooks와 통합된 버전 관리

커뮤니티

• r/ClaudeCode: Reddit 커뮤니티
• Anthropic Discord: 공식 지원 및 토론
• GitHub Issues: claude-code 저장소

---

작성일자: 2026-01-20

작성자 주: 이 문서는 Affaan Mustafa의 공개 가이드와 GitHub 저장소, 그리고 커뮤니티 분석을 종합하여 작성되었습니다. Claude Code는 빠르게 진화하는 도구이므로, 최신 정보는 공식 문서를 참고하시기 바랍니다.