클로드 코드 마스터 가이드: 해커톤 우승자의 실전 노하우

게시 2026/01/20

By BLUEBUG

82 분읽는 시간

앤스로픽 주최 해커톤 우승자가 10개월간 매일 사용하며 깨달은 Claude Code의 핵심 개념과 활용 전략을 쉽고 상세하게 정리한 가이드입니다.

들어가며: 자동화를 바라보는 새로운 시각
기초 개념: Claude Code의 구성 요소 이해하기
첫 번째 핵심: Skills, Hooks, Subagents의 3층 구조
두 번째 핵심: 컨텍스트 윈도우 경제학
세 번째 핵심: 분리를 통한 병렬 처리
실전 활용: 프로젝트에 적용하기
최신 업데이트: Claude Code 2.1의 게임 체인저
마치며: 진짜 가치는 어디에 있는가

들어가며: 자동화를 바라보는 새로운 시각

우리가 알던 자동화

보통 우리가 “개발 자동화”라고 하면 무엇을 떠올릴까요? ESLint가 코드 스타일을 검사해주고, Prettier가 자동으로 포맷팅해주고, GitHub Actions가 테스트를 자동으로 돌려주는 것. 이런 것들이 익숙한 자동화의 모습입니다. 각 도구는 명확한 역할이 있고, 설치하면 그 역할을 수행합니다.

Claude Code가 제시하는 새로운 패러다임

그런데 앤스로픽 해커톤에서 우승한 개발자의 Claude Code 설정을 보면, 자동화에 대한 완전히 다른 관점이 드러납니다. 이건 단순히 “도구들의 모음”이 아닙니다. 서로 다른 시점과 범위에서 작동하는 계층들의 조합입니다.

마치 건물을 짓는 것과 비슷합니다. 1층에는 기본 원칙과 가이드라인이 있고, 2층에는 자동으로 작동하는 시스템이 있으며, 3층에는 전문가 팀이 각자의 역할을 수행합니다. Claude Code는 바로 이런 구조로 설계되어 있습니다.

기초 개념: Claude Code의 구성 요소 이해하기

본격적으로 들어가기 전에, Claude Code의 핵심 구성 요소들을 먼저 이해해봅시다.

1. CLAUDE.md: 프로젝트의 헌법

CLAUDE.md 파일은 프로젝트 루트에 위치하며, Claude가 이 프로젝트를 이해하는 데 필요한 모든 정보를 담고 있습니다. 프로젝트의 “헌법”이라고 생각하면 됩니다.

CLAUDE.md에 들어가는 내용:

프로젝트의 목적과 구조
사용하는 기술 스택과 아키텍처
코딩 컨벤션과 규칙
빌드 명령어와 테스트 방법
주요 디렉토리 구조

예를 들어, Vue 3 프로젝트라면 이렇게 작성할 수 있습니다:

  
# 프로젝트 개요
Vue 3 기반의 운동 트래커 PWA 앱입니다.

## 기술 스택
- Vue 3 + TypeScript (strict mode)
- Dexie.js (IndexedDB wrapper)
- Pinia (상태 관리)

## 아키텍처
- Repository 패턴: `src/db/`에 데이터베이스 추상화
- Pinia store가 repository를 사용
- 모든 데이터는 IndexedDB에 오프라인 우선 저장

## 코딩 규칙
1. Repository 패턴 준수
2. TypeScript interface로 테이블 스키마 정의
3. Vue 3 reactivity와 통합 (useLiveQuery 등)

중요한 점: CLAUDE.md는 단순한 README가 아닙니다. Claude가 코드를 작성할 때 항상 참고하는 “작동 매뉴얼”입니다. 이 파일이 잘 작성되어 있으면, Claude는 프로젝트의 규칙을 지키면서 일관성 있는 코드를 생성합니다.

2. Skills: 자동으로 활성화되는 전문 지식

Skills는 ~/.claude/skills/ 디렉토리에 저장되는 마크다운 파일입니다. 각 Skill은 특정 분야의 전문 지식이나 워크플로우를 정의합니다.

Skills의 특별한 점:

자동 활성화: 사용자가 명시적으로 호출하지 않아도, 대화 내용이 Skill의 설명과 일치하면 Claude가 자동으로 로드합니다
핫 리로드: 파일을 수정하면 즉시 반영됩니다
컨텍스트 제공: 도구 사용법뿐만 아니라 “왜” 그렇게 사용해야 하는지도 알려줍니다

예시: TDD Skill

  
---
name: tdd-workflow
description: Test-Driven Development workflow guide. Use when writing tests or implementing features with TDD approach.
---

# TDD 워크플로우

테스트 주도 개발을 위한 단계별 가이드입니다.

## 원칙
1. **RED**: 먼저 실패하는 테스트를 작성
2. **GREEN**: 테스트를 통과하는 최소한의 코드 작성
3. **REFACTOR**: 코드 개선 및 중복 제거

## 실행 단계
1. 인터페이스 정의
2. 실패 테스트 작성
3. 최소 구현
4. 리팩토링
5. 커버리지 80% 이상 확인

Skills를 언제 만들어야 할까요?

반복적으로 설명해야 하는 패턴이 있을 때
프로젝트만의 특별한 규칙이 있을 때
Claude가 잘 모르거나 잘못 알고 있는 라이브러리를 사용할 때

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

Commands는 ~/.claude/commands/에 저장되며, 슬래시(/)로 시작하는 명령어로 실행됩니다.

Commands의 특징:

명시적 실행: /test, /refactor 같이 직접 호출
빠른 시작: 복잡한 프롬프트를 타이핑하는 대신 한 줄로 실행
체이닝 가능: 여러 명령을 연결해서 사용 가능

예시:

  
---
name: refactor-clean
description: Clean up dead code and unnecessary files
---

다음 작업을 순차적으로 수행합니다:

1. 미사용 함수와 변수 찾기
2. 불필요한 마크다운 파일 정리
3. console.log 제거
4. import 정리

명령어 실행:

/refactor-clean

Skills vs Commands 차이:

Skills: 광범위한 지침, 자동 활성화
Commands: 구체적인 실행 진입점, 수동 호출

4. Hooks: 이벤트 기반 자동화

Hooks는 특정 이벤트가 발생할 때 자동으로 실행되는 스크립트나 프롬프트입니다.

Hooks의 종류:

PreToolUse: 도구 실행 전에 실행

  
{
  "matcher": "tool == 'Bash' && tool_input.command matches 'npm|yarn|pytest'",
  "hooks": [{
    "type": "prompt",
    "message": "⚠️  긴 실행 명령은 tmux 세션 사용을 권장합니다."
  }]
}

PostToolUse: 도구 실행 후에 실행

  
{
  "matcher": "tool == 'Edit' && tool_input.file_path matches '\\.ts$'",
  "hooks": [
    {
      "type": "command",
      "command": "prettier --write $file_path"
    },
    {
      "type": "command",
      "command": "tsc --noEmit"
    }
  ]
}

Stop: Claude가 응답을 완료할 때 실행

  
{
  "hooks": [{
    "type": "command",
    "command": "grep -rn 'console\\.log' --include='*.ts' ."
  }]
}

Hooks의 가치:

매번 “포맷팅 해줘”, “타입 체크 해줘” 요청할 필요 없음
시스템이 적절한 시점에 자동으로 개입
결정론적(deterministic) 동작 보장

5. Subagents: 전문가 팀 구성

Subagents는 특정 작업을 전담하는 독립적인 Claude 인스턴스입니다. ~/.claude/agents/에 저장됩니다.

Subagent의 예시:

  
---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: opus
skills: pr-review, security-check
---

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

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

Subagents의 핵심 특징:

독립적인 컨텍스트: 메인 Claude와 별도의 컨텍스트 윈도우 사용
제한된 권한: 특정 도구에만 접근 가능
병렬 실행: 여러 Subagent를 동시에 실행 가능

6. MCP (Model Context Protocol): 외부 세계와의 연결

MCP는 Claude를 외부 서비스와 연결하는 프로토콜입니다. API를 AI 모델이 사용할 수 있게 만드는 표준화된 방법입니다.

주요 MCP 서버들:

Supabase MCP: 데이터베이스 직접 접근
GitHub MCP: PR 관리, 이슈 트래킹
Vercel MCP: 배포 제어
Playwright MCP: 브라우저 자동화
Docker MCP: 컨테이너 관리

MCP 설정 예시:

  
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token"
      }
    }
  }
}

첫 번째 핵심: Skills, Hooks, Subagents의 3층 구조

이제 본격적으로 해커톤 우승자의 핵심 인사이트를 살펴봅시다. 첫 번째는 3층 구조의 자동화 시스템입니다.

1층: Skills와 Commands - 지식과 진입점

1층의 역할: “무엇을” 할 것인가

이 계층은 워크플로우의 기본 원칙과 실행 방법을 정의합니다.

Skills: 광범위한 가이드라인

Skills는 “이렇게 작업해야 한다”는 원칙을 담습니다. 예를 들어:

코딩 표준 Skill: 변수명은 camelCase, 함수는 한 가지 일만, 주석은 왜(why)를 설명
TDD Skill: 테스트 먼저, 최소 구현, 리팩토링 순서
보안 리뷰 Skill: SQL 인젝션 체크, XSS 방지, 인증 검증

실제 파일 구조:

~/.claude/skills/
├── coding-standards.md
├── tdd-workflow.md
├── security-checklist.md
└── git-best-practices.md

Commands: 구체적인 실행 버튼

Commands는 Skills를 실제로 실행하는 “버튼”입니다.

  
# 여러 Skill을 조합한 복합 워크플로우
/tdd           # TDD Skill 활성화
/e2e           # E2E 테스트 Skill 활성화  
/test-coverage # 커버리지 체크 Skill 활성화

체이닝의 힘:

하나의 프롬프트로 여러 명령을 연결할 수 있습니다:

/tdd /e2e /test-coverage

로그인 기능을 구현해주세요.

Claude는 이 명령을 보고:

TDD 원칙에 따라 테스트 먼저 작성
E2E 테스트 시나리오 포함
커버리지 80% 이상 확인

모든 걸 자동으로 수행합니다.

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

2층의 역할: “언제” 할 것인가

Skills와 Commands는 명시적으로 호출해야 하지만, Hooks는 특정 이벤트에 자동으로 반응합니다.

PreToolUse Hook의 실전 활용

상황: 개발자가 장시간 실행되는 명령어를 실행하려고 함

  
{
  "matcher": "tool == 'Bash' && (tool_input.command matches 'npm install|yarn|pytest')",
  "hooks": [{
    "type": "prompt",
    "message": "이 명령은 시간이 걸릴 수 있습니다. tmux 세션에서 실행하시겠습니까?",
    "once": true
  }]
}

작동 방식:

Claude가 npm install 실행하려 함
PreToolUse Hook이 감지
사용자에게 tmux 권장 메시지
once: true 때문에 세션당 한 번만 표시

PostToolUse Hook으로 품질 자동 유지

상황: TypeScript 파일이 편집될 때마다 자동 품질 관리

  
{
  "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": "디버그 로그 경고"
    }
  ]
}

실제 동작 시나리오:

개발자: “src/utils/helper.ts에 새 함수 추가해줘”
Claude: 파일 편집
PostToolUse Hook 자동 실행:
- Prettier로 포맷 정리 ✓
- TypeScript 컴파일러로 타입 검증 ✓
- console.log 있으면 경고 ✓
결과: 코드 품질이 자동으로 유지됨

Stop Hook으로 최종 점검

상황: Claude가 작업을 완료하기 전 최종 점검

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

타이밍의 중요성:

Hooks의 진짜 가치는 타이밍입니다. 개발자가:

“포맷팅 해줘” (매번 요청하지 않아도)
“타입 체크 해줘” (자동으로 됨)
“console.log 확인해줘” (자동으로 됨)

시스템이 적절한 시점에 알아서 개입합니다.

3층: Subagents - 전문가 팀의 분업

3층의 역할: “누가” 할 것인가

앞선 두 계층이 ‘무엇을’, ‘언제’ 할지를 정의했다면, Subagents는 ‘누가’ 할지를 분리합니다.

왜 Subagent가 필요한가?

문제 상황:

메인 Claude가 모든 작업을 직접 처리하면:

컨텍스트 윈도우가 빠르게 소진됨
복잡한 작업으로 주요 맥락이 묻힘
전문성이 희석됨 (만능이지만 전문가는 아님)

해결책: 전문가 팀 구성

마치 회사에서 역할을 나누듯이, Subagent를 활용합니다:

~/.claude/agents/
├── planner.md              # 기획자: 구현 계획 수립
├── architect.md            # 설계자: 시스템 설계 결정
├── code-reviewer.md        # 리뷰어: 코드 품질 검토
├── security-reviewer.md    # 보안 전문가: 취약점 분석
├── e2e-runner.md          # QA: E2E 테스트 실행
├── refactor-cleaner.md    # 리팩토링 전문가
└── doc-updater.md         # 문서 관리자

실전 예시: 리팩토링 워크플로우

사용자 요청: “이 모듈 리팩토링 해줘”

메인 Claude의 역할:

/refactor-clean 명령 감지
refactor-cleaner.md Skill 참조
refactor-cleaner Subagent에게 위임
진행 상황 모니터링
결과 통합 및 사용자에게 보고

Subagent의 작업:

  
---
name: refactor-cleaner
description: Specialized in cleaning up dead code and improving code structure
tools: Read, Edit, Bash, Grep
model: sonnet
---

당신은 리팩토링 전문가입니다.

## 작업 순서
1. 코드베이스 스캔
2. 미사용 함수/변수 식별
3. 중복 코드 패턴 찾기
4. 모듈화 기회 분석
5. 리팩토링 실행
6. 테스트 실행으로 검증

동작 흐름:

사용자: /refactor-clean src/utils/

메인 Claude: 
  → "리팩토링을 시작하겠습니다."
  → refactor-cleaner Subagent 생성
  
Subagent (독립 컨텍스트):
  → src/utils/ 분석
  → 미사용 함수 3개 발견
  → 중복 로직 2곳 발견
  → 리팩토링 수행
  → 테스트 실행: PASS
  
메인 Claude:
  → 결과 수신
  → "3개 함수 제거, 2개 모듈 통합 완료"

Subagent의 권한 제한

보안과 명확성을 위한 설계:

각 Subagent는 필요한 도구만 사용할 수 있습니다:

  
---
name: security-reviewer
tools: Read, Grep, Glob  # 읽기만 가능, 편집 불가
model: opus              # 더 강력한 모델 사용
---

# 보안 리뷰 전문가
코드를 읽고 보안 취약점을 찾습니다.
파일을 수정하지는 않습니다.

이렇게 하면:

예상치 못한 파일 수정 방지
각 Subagent의 역할이 명확
메인 Claude의 컨텍스트 보호

컨텍스트 보존의 가치

메인 Claude의 관점:

컨텍스트 사용량:
├── 프로젝트 구조: 15k tokens
├── 대화 맥락: 25k tokens
├── CLAUDE.md: 10k tokens
└── 여유 공간: 150k tokens

Subagent 위임 후:
├── 프로젝트 구조: 15k tokens
├── 대화 맥락: 25k tokens
├── CLAUDE.md: 10k tokens
├── Subagent 진행상황: 2k tokens
└── 여유 공간: 148k tokens ← 거의 그대로 유지!

Subagent의 관점:

새로운 독립 컨텍스트 (200k tokens):
├── Subagent 지침: 5k tokens
├── 필요한 파일들: 30k tokens
├── 작업 수행: 50k tokens
└── 여유 공간: 115k tokens

결과: 복잡한 작업도 메인 컨텍스트를 오염시키지 않음!

3층 구조가 맞물릴 때

종합 예시: 새 기능 개발

사용자 요청:

/tdd /security

로그인 API 엔드포인트를 만들어주세요.
JWT 인증을 사용하고, rate limiting을 적용해야 합니다.

실행 과정:

1층 (Skills & Commands):

/tdd → TDD Skill 활성화
/security → Security Skill 활성화
Skills가 기본 원칙 제공

2층 (Hooks):

파일 생성 시 → PostToolUse Hook으로 자동 포맷팅
Bash 명령 실행 시 → PreToolUse Hook으로 권한 확인
작업 완료 시 → Stop Hook으로 보안 체크

3층 (Subagents):

planner Subagent: API 설계 수립
architect Subagent: 인증 구조 설계
security-reviewer Subagent: JWT 구현 검토
code-reviewer Subagent: 최종 코드 리뷰

결과:

일관된 코드 품질
자동화된 보안 검증
체계적인 테스트 커버리지
메인 컨텍스트는 여전히 깨끗함

핵심 교훈

자동화를 도구의 나열로 보면:

“이 도구가 저 작업을 빠르게 해준다”

자동화를 계층의 조합으로 보면:

“이 작업 전체를 어떻게 구조화할 것인가?”
“각 계층이 어떻게 협력할 것인가?”
“어떻게 확장 가능하게 만들 것인가?”

속도의 개선은 부수적입니다. 진짜 가치는 작업의 재정의에 있습니다.

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

이론과 현실의 간극

스펙상:

Claude Sonnet 4.5: 200,000 토큰 컨텍스트 윈도우
“충분해 보인다. 긴 코드베이스도 담을 수 있을 것 같다.”

실전에서:

MCP 14개 + 플러그인 14개 활성화
실제 사용 가능한 컨텍스트: 70,000 토큰
증발한 130,000 토큰은 어디로?

도구 정의가 먹는 컨텍스트

MCP의 숨겨진 비용

각 MCP 서버의 실제 토큰 소비:

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

문제: 도구를 사용하지 않아도, 정의만으로 토큰을 소비합니다.

실제 사례: 컨텍스트 압박

한 개발자의 세션 시작 시점:

> /context

컨텍스트 사용량:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
claude-sonnet-4-5 • 62.8k/200k tokens (31.4%)

시스템 프롬프트:     2.7k (1.3%)
시스템 도구:        14.4k (7.2%)
MCP 도구:          42.6k (21.3%) ← 주범!
커스텀 에이전트:     0.4k (0.2%)
메모리 파일:         1.7k (0.9%)
메시지:            0.1k (0.0%)
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
사용:              62.8k (31.4%)
여유:             137.2k (68.6%)

한 줄도 입력하지 않았는데 31.4%가 사라졌습니다!

해커톤 우승자의 해법: 선택적 활성화

“20-30개 설정, 10개 미만 활성화, 80개 미만 도구” 규칙

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

  
{
  "mcpServers": {
    "github": { "command": "npx", "args": ["@mcp/github"] },
    "supabase": { "command": "npx", "args": ["@mcp/supabase"] },
    "vercel": { "command": "npx", "args": ["@mcp/vercel"] },
    "docker": { "command": "npx", "args": ["@mcp/docker"] },
    "playwright": { "command": "npx", "args": ["@mcp/playwright"] },
    "cloudflare": { "command": "npx", "args": ["@mcp/cloudflare"] },
    "railway": { "command": "npx", "args": ["@mcp/railway"] },
    "clickhouse": { "command": "npx", "args": ["@mcp/clickhouse"] },
    "firecrawl": { "command": "npx", "args": ["@mcp/firecrawl"] },
    "postgres": { "command": "npx", "args": ["@mcp/postgres"] },
    "mongodb": { "command": "npx", "args": ["@mcp/mongodb"] },
    "redis": { "command": "npx", "args": ["@mcp/redis"] },
    "elasticsearch": { "command": "npx", "args": ["@mcp/elasticsearch"] },
    "stripe": { "command": "npx", "args": ["@mcp/stripe"] }
  }
}

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

웹 프로젝트:

  
{
  "mcpServers": {
    "github": { "enabled": true },
    "vercel": { "enabled": true },
    "supabase": { "enabled": true },
    "playwright": { "enabled": true }
    // 나머지는 disabled
  }
}

백엔드 프로젝트:

  
{
  "mcpServers": {
    "github": { "enabled": true },
    "postgres": { "enabled": true },
    "redis": { "enabled": true },
    "docker": { "enabled": true }
    // 나머지는 disabled
  }
}

결과:

전체 설정: 14개 MCP
실제 활성화: 4-5개
컨텍스트 소비: 20-25k tokens (절약된 100k+ tokens!)

최신 업데이트: MCP Tool Search (게임 체인저!)

Claude Code 2.1.7의 혁신

2026년 1월 16일 출시된 MCP Tool Search가 이 문제를 근본적으로 해결했습니다.

이전 방식 (Eager Loading):

세션 시작 → 모든 MCP 도구 로드 → 67k 토큰 소비 → 작업 시작

새로운 방식 (Lazy Loading):

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

실제 측정 결과

같은 설정으로 비교:

이전:

MCP 도구 컨텍스트: 51,000 토큰
실제 사용 가능: 149,000 토큰 (74.5%)

MCP Tool Search 적용 후:

MCP 도구 컨텍스트: 8,500 토큰
실제 사용 가능: 191,500 토큰 (95.75%)

절약: 42,500 토큰 (46.9% 감소!)

작동 방식

인덱스 생성: ``` 도구 이름 + 한 줄 설명만 로드 docker-mcp:
- list-containers: Docker 컨테이너 목록 조회
- get-logs: 컨테이너 로그 조회 ```

키워드 매칭:

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

세션 캐싱:

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

개발자가 해야 할 일

MCP 서버 제작자:

  
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "serverInstructions": "이 서버는 데이터베이스 쿼리와 분석 기능을 제공합니다. SQL 실행, 스키마 조회, 성능 분석에 사용하세요."
    }
  }
}

serverInstructions 필드가 이제 매우 중요합니다. Skills처럼, Claude가 언제 이 서버를 찾아야 하는지 알려줍니다.

사용자:

자동 활성화됩니다! MCP 도구가 컨텍스트의 10% 이상을 차지하면 자동으로 Tool Search 모드로 전환됩니다.

수동 설정 (선택사항):

  
{
  "enable_tool_search": true
}

컨텍스트가 중요한 이유

컨텍스트 ≠ 단순 저장 공간

컨텍스트는 Claude의 작업 기억(working memory) 입니다:

어떤 코드를 봤는지
어떤 결정을 내렸는지
대화의 맥락이 무엇인지

컨텍스트가 부족하면:

복잡한 리팩토링 중...

Claude (20분 전): "User 클래스는 싱글턴 패턴으로 설계하겠습니다."

[컨텍스트 부족으로 이전 결정 잊어버림]

Claude (지금): "User 클래스를 일반 클래스로 만들겠습니다."

개발자: "??? 아까 싱글턴이라고 했잖아요?"

일관성 없는 코드가 나옵니다.

도구 과다의 숨겨진 비용

기능적 비용:

줄어든 대화 맥락
밀려난 프로젝트 정보
잊혀진 설계 결정

인지적 비용:

도구가 많을수록, Claude는 매 작업마다:

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

선택 피로(Decision Fatigue) 가 발생합니다.

도구가 적으면:

선택이 빠르고 명확
에너지가 실제 작업에 집중

실전 가이드: 컨텍스트 최적화

1. 프로젝트 유형별 MCP 세트 정의

웹 프론트엔드:

필수: GitHub, Vercel, Playwright
선택: Figma, Storybook
제외: 데이터베이스 관련 모든 MCP

백엔드 API:

필수: GitHub, Docker, Postgres
선택: Redis, Stripe
제외: Vercel, Playwright

데이터 분석:

필수: Postgres, ClickHouse, Jupyter
선택: MongoDB, Elasticsearch
제외: Vercel, Docker

2. 컨텍스트 모니터링

정기적으로 체크:

  
> /context

# 30% 이상 사용 중이면 MCP 정리 고려
# 50% 이상이면 즉시 조치 필요

3. “Just-in-Time” MCP 활성화

  
# 작업 시작 시
> /context
# MCP 도구: 8.5k tokens (4.25%) ← 건강!

# 필요할 때만 활성화
"이제 Docker 배포가 필요해"
→ Claude가 자동으로 Docker MCP 도구 로드

# 작업 끝나면 자동 정리 (세션 종료 시)

4. Subagent 활용으로 컨텍스트 절약

복잡한 분석 작업은 Subagent에 위임:

메인 Claude (컨텍스트 사용):
├── 프로젝트 정보: 20k
├── 대화 맥락: 30k
└── 여유: 150k

분석 작업 → Subagent 위임
Subagent (독립 컨텍스트):
├── 분석 수행: 80k
└── 메인에 결과만 전달: 2k

결과: 메인 컨텍스트 거의 그대로!

핵심 교훈

기능 확장 ≠ 더 나은 성능

오히려:

기능 확장 → 컨텍스트 압박 → 성능 저하

진짜 최적화:

필요한 것만 켜기
불필요한 것은 끄기
MCP Tool Search 활용하기
Subagent로 작업 분리하기

컨텍스트는 희소 자원입니다. 희소 자원의 관리가 시스템 성능을 결정합니다.

세 번째 핵심: 분리를 통한 병렬 처리

병렬 처리의 함정

직관적으로 생각하면:

작업을 동시에 처리하면 빠르다
더 많이 동시에 하면 더 빠르다

하지만 현실에서:

동시 작업 A: 파일 X 수정
동시 작업 B: 파일 X 수정

결과: 충돌! 💥

병렬 처리는 “동시에”만으로는 안 됩니다. 먼저 분리하고, 그 다음 동시에 실행해야 합니다.

세 가지 병렬화 전략

해커톤 우승자는 세 가지 도구로 병렬 처리를 구현합니다:

/fork - 대화 세션 분리
Git Worktrees - 코드베이스 분리
Subagents - 역할 분리

세 방법 모두 같은 원리를 따릅니다: 분리 → 병렬 실행

1. /fork: 대화 세션 분리

개념

/fork는 현재 Claude 대화를 복제해서 별도의 독립 세션으로 분기시킵니다.

실전 시나리오

상황: 백엔드 API와 프론트엔드 UI를 동시에 개발

기존 방식 (순차):

1. 백엔드 API 작업 (30분)
2. 프론트엔드 컴포넌트 작업 (30분)
총: 60분

Fork 활용 (병렬):

원본 세션 (백엔드):

> /fork frontend-work

"인증 API 엔드포인트를 계속 작업합니다."
- src/api/auth.ts 수정
- src/middleware/jwt.ts 추가
- tests/api/auth.test.ts 작성

분기된 세션 (프론트엔드):

  
# 새 터미널에서
> claude --session=frontend-work

"로그인 폼 컴포넌트를 만듭니다."
- src/components/LoginForm.tsx 생성
- src/hooks/useAuth.ts 추가
- tests/components/LoginForm.test.tsx 작성

결과: 30분으로 단축!

성공의 조건: 비중첩(Non-overlapping)

작동하는 경우:

세션 A: src/api/* 수정
세션 B: src/components/* 수정
충돌 가능성: 없음 ✓

작동하지 않는 경우:

세션 A: src/utils/helper.ts 수정
세션 B: src/utils/helper.ts 수정
충돌 가능성: 높음 ✗

실전 팁

분기 전 체크리스트:

파일 범위 확인

세션 A: 어떤 디렉토리/파일 수정?
세션 B: 어떤 디렉토리/파일 수정?
→ 겹치면 순차 처리!

Git 브랜치 전략

원본 세션: feature/auth-api
분기 세션: feature/login-ui
→ 나중에 개별 PR로 병합

공유 파일 주의

package.json, tsconfig.json 같은 설정 파일은
한 세션에서만 수정하기

2. Git Worktrees: 코드베이스 분리

개념

Git Worktrees는 하나의 저장소에서 여러 개의 독립적인 작업 디렉토리를 생성합니다.

일반 Git vs Git Worktrees

일반 Git:

repo/
└── .git/

브랜치 전환:
git checkout feature-a  # 전체 디렉토리 변경
git checkout feature-b  # 또 전체 디렉토리 변경

Git Worktrees:

repo/
├── .git/
├── main/           # main 브랜치 체크아웃
├── feature-a/      # feature-a 브랜치 체크아웃
└── feature-b/      # feature-b 브랜치 체크아웃

각 디렉토리가 독립적!

설정 방법

1. 기본 저장소 설정

cd ~/projects
git clone https://github.com/user/repo.git
cd repo

2. Worktree 생성

  
# feature-auth 브랜치의 작업 디렉토리 생성
git worktree add ../repo-feature-auth feature-auth

# feature-ui 브랜치의 작업 디렉토리 생성  
git worktree add ../repo-feature-ui feature-ui

# 핫픽스 브랜치 작업 디렉토리
git worktree add ../repo-hotfix hotfix/critical-bug

3. 디렉토리 구조

~/projects/
├── repo/                    # 메인 저장소 (main 브랜치)
├── repo-feature-auth/       # feature-auth 브랜치
├── repo-feature-ui/         # feature-ui 브랜치
└── repo-hotfix/             # hotfix 브랜치

4. 각 디렉토리에서 Claude 실행

  
# 터미널 1
cd ~/projects/repo-feature-auth
claude

# 터미널 2
cd ~/projects/repo-feature-ui
claude

# 터미널 3
cd ~/projects/repo-hotfix
claude

실전 시나리오

상황: 새 기능 개발 중 긴급 버그 발견

문제 (일반 Git):

  
# 현재 feature 브랜치에서 작업 중
git status
# 20개 파일 수정됨, 커밋 안 함

# 긴급 버그 수정 필요!
git stash        # 작업 임시 저장
git checkout main
git checkout -b hotfix/urgent

# 버그 수정...

git checkout feature-branch
git stash pop    # 작업 복원

# 다시 context 설정... 😫

해결 (Worktrees):

  
# 터미널 1 - feature 작업 계속
cd ~/repo-feature
# 작업 그대로 진행

# 터미널 2 - 긴급 버그 수정
cd ~/repo-hotfix
claude
# "이 버그 고쳐줘"

# 완전히 독립적! 상태 전환 없음!

/fork vs Worktrees 비교

특징	/fork	Git Worktrees
분리 대상	대화 세션	파일 시스템
독립성	부분적 (같은 파일 시스템)	완전 (별도 디렉토리)
충돌 가능성	중간	매우 낮음
사용 복잡도	낮음	중간
언제 사용?	빠른 병렬 작업	완전한 격리 필요 시

Git Worktrees 활용 패턴

패턴 1: 기능별 개발

  
repo-main/          # 프로덕션 코드
repo-feature-a/     # 기능 A 개발
repo-feature-b/     # 기능 B 개발
repo-feature-c/     # 기능 C 개발

패턴 2: 버전별 유지보수

  
repo-v2/            # v2 신규 개발
repo-v1-hotfix/     # v1 버그 수정
repo-v1-security/   # v1 보안 패치

패턴 3: 리뷰 + 개발

repo-dev/           # 내 개발 작업
repo-review/        # 동료 PR 리뷰

3. Subagents: 역할 분리

개념 복습

Subagents는 작업의 성격을 분리합니다. 각 Subagent는:

독립적인 컨텍스트
제한된 도구 권한
특화된 전문성

병렬 실행 패턴

패턴 1: 탐색 + 실행

사용자: "인증 시스템 리팩토링 해줘"

메인 Claude:
  ├─ [동시 실행]
  │   ├─ Explore Subagent → 현재 코드 분석
  │   └─ Research Subagent → 베스트 프랙티스 조사
  │
  └─ [결과 통합] → 리팩토링 계획 수립

메인 Claude:
  ├─ [동시 실행]
  │   ├─ Refactor Subagent → 코드 수정
  │   └─ Test Subagent → 테스트 작성
  │
  └─ [검증]
      └─ Security Reviewer Subagent → 보안 검토

패턴 2: 다층 리뷰

코드 작성 완료

메인 Claude:
  └─ [병렬 리뷰]
      ├─ Code Reviewer → 품질 검토
      ├─ Security Reviewer → 보안 검토  
      ├─ Performance Reviewer → 성능 분석
      └─ Documentation Reviewer → 문서 검토

메인 Claude:
  └─ [결과 통합] → 종합 리포트 생성

실전 예시: 복잡한 기능 개발

사용자 요청:

결제 시스템을 구현해주세요.
- Stripe 연동
- 재시도 로직
- 웹훅 처리
- 에러 핸들링

메인 Claude의 오케스트레이션:

1단계: 계획 수립
├─ Planner Subagent
│  ├─ 컴포넌트 분석
│  ├─ 의존성 파악
│  └─ 일정 추정
│
└─ Architect Subagent
   ├─ 시스템 설계
   ├─ 데이터베이스 스키마
   └─ API 인터페이스

2단계: 병렬 구현
├─ Backend Subagent
│  ├─ Stripe SDK 통합
│  ├─ 재시도 로직 구현
│  └─ API 엔드포인트
│
├─ Database Subagent  
│  ├─ 트랜잭션 테이블
│  ├─ 로그 테이블
│  └─ 마이그레이션
│
└─ Test Subagent
   ├─ 단위 테스트
   ├─ 통합 테스트
   └─ E2E 시나리오

3단계: 병렬 검증
├─ Security Reviewer
│  ├─ API 키 저장 검증
│  ├─ 웹훅 서명 확인
│  └─ PCI 컴플라이언스
│
├─ Code Reviewer
│  ├─ 코드 품질
│  ├─ 에러 핸들링
│  └─ 테스트 커버리지
│
└─ Documentation Updater
   ├─ API 문서
   ├─ README 업데이트
   └─ 배포 가이드

4단계: 통합 및 배포
메인 Claude
└─ 모든 결과 통합
   └─ 최종 검증
      └─ 배포 준비

왜 충돌이 없는가?

역할의 명확한 분리:

  
Backend Subagent:
- 도구: Edit, Bash, Read
- 접근: src/api/*, src/services/*
- 역할: 구현

Database Subagent:  
- 도구: Edit, Bash (DB 전용)
- 접근: migrations/*, src/db/*
- 역할: 스키마

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

→ 접근 범위가 완전히 분리됨!

권한의 제한:

  
Security Reviewer:
- 도구: Read, Grep, Glob (읽기만!)
- 역할: 분석만 수행, 수정 불가

Code Reviewer:
- 도구: Read, Grep, Glob (읽기만!)
- 역할: 리뷰만 수행, 수정 불가

→ 리뷰어는 코드를 수정하지 않음!

세 전략의 통합 활용

완전한 격리가 필요한 대규모 작업

시나리오: 마이크로서비스 3개 동시 개발

  
# Git Worktrees 설정
git worktree add ../service-auth auth-service
git worktree add ../service-payment payment-service  
git worktree add ../service-notification notification-service

# 각 서비스마다 Claude 인스턴스
터미널 1: cd service-auth && claude
터미널 2: cd service-payment && claude
터미널 3: cd service-notification && claude

# 각 Claude 내부에서
터미널 1: /fork test-writing (세션 분기)
터미널 2: /fork integration-test (세션 분기)
터미널 3: /fork documentation (세션 분기)

# 각 Claude가 Subagent 활용
모든 터미널:
└─ Planner Subagent (계획)
└─ Builder Subagent (구현)  
└─ Tester Subagent (테스트)
└─ Reviewer Subagent (리뷰)

결과:

3개 서비스 × 2개 세션 × 4개 Subagent
총 24개 작업이 동시에 진행!
충돌 없음 (완벽한 격리)

공통 원리: 분리 → 병렬

패턴 정리

1. /fork

분리 단위: 대화 세션
병렬 수준: 중간
사용 시기: 같은 코드베이스, 다른 작업
예시: API 개발 + UI 개발

2. Git Worktrees

분리 단위: 파일 시스템
병렬 수준: 높음
사용 시기: 완전한 격리 필요
예시: 버전별 유지보수, 기능별 개발

3. Subagents

분리 단위: 역할과 권한
병렬 수준: 매우 높음
사용 시기: 전문화된 작업
예시: 구현 + 테스트 + 리뷰 병렬 처리

의사결정 플로우차트

작업이 동시에 진행되어야 하는가?
  ↓ Yes
  
같은 파일을 건드리는가?
  ↓ Yes → 순차 처리 or Subagent 역할 분리
  ↓ No
  
완전한 격리가 필요한가? (다른 브랜치)
  ↓ Yes → Git Worktrees
  ↓ No
  
빠른 분기가 필요한가?
  ↓ Yes → /fork
  ↓ No
  
전문화된 작업인가? (리뷰, 분석, 테스트)
  ↓ Yes → Subagents

핵심 교훈

병렬 처리는 속도의 문제가 아닙니다.

본질은 분리의 문제입니다.

두 작업의 범위가 겹치면:

동시 실행 불가
또는 충돌 발생

범위를 명확히 나누면:

동시 실행이 자연스럽게 가능
충돌 없음

도구는 다르지만 원리는 같습니다:

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

“먼저 나누고, 그 다음 동시에”

이 원리는 Claude Code를 넘어 모든 시스템 설계에 적용됩니다.

실전 활용: 프로젝트에 적용하기

이론을 배웠으니, 이제 실제 프로젝트에 어떻게 적용하는지 단계별로 살펴봅시다.

1단계: 기본 구조 설정

CLAUDE.md 작성

  
cd your-project
claude --init  # 또는 수동으로 작성

템플릿:

  
# 프로젝트명

## 개요
간단한 프로젝트 설명

## 기술 스택
- 언어/프레임워크
- 주요 라이브러리
- 데이터베이스

## 프로젝트 구조
\`\`\`
src/
├── api/      # REST API 엔드포인트
├── services/ # 비즈니스 로직
├── db/       # 데이터베이스 레이어
└── utils/    # 유틸리티 함수
\`\`\`

## 코딩 규칙
1. TypeScript strict mode 사용
2. 함수는 50줄 이하
3. async/await 사용 (Promise.then 금지)

## 명령어
\`\`\`bash
npm run dev      # 개발 서버
npm run test     # 테스트 실행
npm run build    # 프로덕션 빌드
\`\`\`

## 주의사항
- API 키는 반드시 환경 변수로
- 민감한 데이터 로깅 금지

2단계: 필수 Skills 생성

Skill 1: 코딩 표준

~/.claude/skills/coding-standards.md:

  
---
name: coding-standards
description: 프로젝트 코딩 표준과 베스트 프랙티스
---

# 코딩 표준

## 네이밍
- 변수/함수: camelCase
- 클래스/타입: PascalCase
- 상수: UPPER_SNAKE_CASE

## 함수 작성
- 하나의 함수는 하나의 기능
- 최대 50줄
- 순수 함수 우선

## 에러 처리
\`\`\`typescript
// Good
try {
  const result = await riskyOperation();
  return { success: true, data: result };
} catch (error) {
  logger.error('Operation failed', { error });
  return { success: false, error: error.message };
}

// Bad
const result = await riskyOperation(); // 에러 처리 없음
\`\`\`

Skill 2: 테스트 작성

~/.claude/skills/testing-guide.md:

  
---
name: testing-guide
description: 테스트 작성 가이드라인. Use when writing tests.
---

# 테스트 가이드

## 단위 테스트
\`\`\`typescript
describe('UserService', () => {
  describe('createUser', () => {
    it('should create a user with valid data', async () => {
      // Arrange
      const userData = { name: 'John', email: 'john@example.com' };
      
      // Act
      const result = await userService.createUser(userData);
      
      // Assert
      expect(result.success).toBe(true);
      expect(result.data.name).toBe(userData.name);
    });
  });
});
\`\`\`

## 커버리지 목표
- 라인 커버리지: 80% 이상
- 브랜치 커버리지: 75% 이상

3단계: 편리한 Commands 설정

Command 1: 빠른 리팩토링

~/.claude/commands/refactor.md:

  
---
name: refactor
description: Code refactoring workflow
---

다음 순서로 리팩토링을 수행합니다:

1. **코드 분석**
   - 복잡도가 높은 함수 찾기
   - 중복 코드 패턴 식별
   
2. **리팩토링 계획**
   - 어떤 함수를 분리할지
   - 어떤 패턴을 적용할지

3. **실행**
   - 함수 분리
   - 변수명 개선
   - 중복 제거

4. **검증**
   - 테스트 실행
   - 타입 체크

사용:

/refactor src/services/user.ts

Command 2: 풀 테스트 스위트

~/.claude/commands/test-all.md:

  
---
name: test-all
description: Run complete test suite with coverage
---

전체 테스트를 다음 순서로 실행합니다:

1. 단위 테스트
2. 통합 테스트  
3. E2E 테스트
4. 커버리지 리포트 생성
5. 결과 요약

4단계: Hooks로 자동화

Hook 설정 파일

~/.claude/settings.json:

  
{
  "hooks": [
    {
      "name": "auto-format-ts",
      "matcher": "tool == 'Edit' && tool_input.file_path matches '\\.(ts|tsx)$'",
      "hooks": [
        {
          "type": "command",
          "command": "prettier --write \"$file_path\"",
          "description": "TypeScript 파일 자동 포맷팅"
        }
      ]
    },
    {
      "name": "type-check",
      "matcher": "tool == 'Edit' && tool_input.file_path matches '\\.ts$'",
      "hooks": [
        {
          "type": "command",
          "command": "tsc --noEmit",
          "description": "타입 체크"
        }
      ]
    },
    {
      "name": "warn-console-log",
      "matcher": "tool == 'Edit' && tool_input.file_path matches '\\.(ts|tsx|js|jsx)$'",
      "hooks": [
        {
          "type": "command",
          "command": "if grep -q 'console\\.log' \"$file_path\"; then echo '⚠️  console.log가 추가되었습니다.'; fi",
          "description": "Console.log 경고"
        }
      ]
    }
  ]
}

5단계: 핵심 Subagents 생성

Subagent 1: 코드 리뷰어

~/.claude/agents/code-reviewer.md:

  
---
name: code-reviewer
description: 코드 품질과 베스트 프랙티스 검토
tools: Read, Grep, Glob
model: sonnet
---

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

## 리뷰 체크리스트

### 1. 코드 품질
- [ ] 가독성 (명확한 변수명, 적절한 주석)
- [ ] 복잡도 (함수 50줄 이하)
- [ ] DRY 원칙 (중복 제거)

### 2. 타입 안정성  
- [ ] TypeScript strict mode 준수
- [ ] any 사용 최소화
- [ ] 타입 가드 사용

### 3. 에러 처리
- [ ] try-catch 적절히 사용
- [ ] 에러 로깅
- [ ] 사용자 친화적 에러 메시지

### 4. 테스트
- [ ] 테스트 존재 여부
- [ ] 커버리지 80% 이상
- [ ] 엣지 케이스 테스트

## 리뷰 형식

\`\`\`markdown
## 코드 리뷰 결과

### ✅ 잘된 점
- 항목 나열

### ⚠️ 개선 필요
- 항목 나열 (우선순위 포함)

### 🔴 필수 수정
- 반드시 고쳐야 할 항목

### 💡 제안
- 추가 개선 아이디어
\`\`\`

Subagent 2: 보안 리뷰어

~/.claude/agents/security-reviewer.md:

  
---
name: security-reviewer
description: 보안 취약점 분석 전문가
tools: Read, Grep, Glob
model: opus
---

당신은 보안 전문가입니다.

## 보안 체크리스트

### 인증/인가
- [ ] JWT 토큰 검증
- [ ] 권한 체크
- [ ] 세션 관리

### 데이터 보호
- [ ] 민감 데이터 암호화
- [ ] SQL 인젝션 방지
- [ ] XSS 방지

### API 보안
- [ ] Rate limiting
- [ ] CORS 설정
- [ ] API 키 보호

### 로깅
- [ ] 민감 데이터 로깅 금지
- [ ] 보안 이벤트 로깅

## 발견 시 보고 형식

\`\`\`markdown
## 🔐 보안 리뷰

### 🚨 Critical (즉시 수정)
- 취약점 설명
- 파일: 위치
- 수정 방법

### ⚠️ High (우선 수정)
- 취약점 설명

### ℹ️ Medium (검토 필요)
- 잠재적 이슈

### ✅ 통과
- 검증된 보안 구현
\`\`\`

6단계: MCP 설정 (선택적)

프로젝트에 필요한 MCP만 활성화:

.claude/config.json:

  
{
  "mcpServers": {
    "github": {
      "enabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    },
    "postgres": {
      "enabled": true,
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"]
    }
  }
}

7단계: 워크플로우 테스트

시나리오 1: 새 기능 개발 (TDD)

  
> /tdd

새 기능: 사용자 프로필 업데이트 API

Claude:
1. 테스트 작성 (RED)
   → tests/api/profile.test.ts 생성

2. 최소 구현 (GREEN)
   → src/api/profile.ts 구현

3. 리팩토링 (REFACTOR)
   → 코드 개선

4. 자동 실행 (Hooks)
   → Prettier 포맷팅 ✓
   → TypeScript 타입 체크 ✓
   → 테스트 실행 ✓

5. 리뷰 (Subagent)
   → code-reviewer 호출
   → security-reviewer 호출

시나리오 2: 긴급 버그 수정

  
# 메인 작업 (feature 브랜치)
터미널 1: claude
> "결제 기능 구현 중..."

# 긴급 버그 발견!
터미널 2: 
cd ../repo-hotfix  # Git Worktree 사용
claude
> "로그인 버그 수정해줘"

# 메인 작업은 중단 없이 계속됨!
터미널 1: (계속 진행)

시나리오 3: 병렬 개발

  
> /fork frontend-work

# 원본 세션 (백엔드)
"API 엔드포인트 작성"
→ Architect Subagent (설계)
→ Builder Subagent (구현)
→ Tester Subagent (테스트)

# 분기 세션 (프론트엔드)  
"React 컴포넌트 작성"
→ Designer Subagent (UI 설계)
→ Builder Subagent (구현)
→ Tester Subagent (테스트)

# 동시 진행!

8단계: 지속적인 개선

주기적 리뷰

매주:

  
> /context
# 컨텍스트 사용량 확인
# 30% 이상이면 MCP 정리 고려

매월:

사용하지 않는 Skills 제거
Commands 업데이트
Subagents 최적화

팀 공유

효과적인 설정을 팀과 공유:

  
# Plugin으로 패키징
~/.claude/
├── skills/
├── commands/
├── agents/
└── hooks/

# Git에 커밋하여 팀 공유
git add .claude/
git commit -m "Add Claude Code configuration"
git push

최신 업데이트: Claude Code 2.1의 게임 체인저

2025년 12월에 출시된 Claude Code 2.1과 2026년 1월의 2.1.7 버전은 많은 사용자들이 요청했던 기능들을 대거 추가했습니다. 주요 개선사항을 살펴봅시다.

1. MCP Tool Search: 컨텍스트 혁명 (2.1.7)

이전의 문제

세션 시작 → 모든 MCP 도구 로드
Docker MCP: 135개 도구 → 125k 토큰
GitHub MCP: 27개 도구 → 18k 토큰
Playwright MCP: 21개 도구 → 14k 토큰

총: 157k 토큰 소비! (78.5%)
실제 작업 공간: 43k 토큰만 남음

2.1.7의 해결책

자동 Lazy Loading:

컨텍스트 사용량이 10% 초과 시:
→ 자동으로 Tool Search 모드 전환
→ 도구 인덱스만 로드: 5k 토큰
→ 필요할 때만 도구 로드

결과: 157k → 8.5k 토큰 (94.6% 감소!)

실제 측정 결과:

Before MCP Tool Search:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
사용: 67,300 tokens (33.7%)
여유: 132,700 tokens (66.3%)

After MCP Tool Search:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
사용: 15,800 tokens (7.9%)
여유: 184,200 tokens (92.1%)

절약: 51,500 tokens! 🎉

개발자가 할 일:

대부분의 경우 아무것도 안 해도 됩니다! 자동으로 활성화됩니다.

MCP 서버 제작자만 serverInstructions 추가:

  
{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["server.js"],
      "serverInstructions": "데이터베이스 쿼리, 스키마 분석, 성능 모니터링 기능을 제공합니다."
    }
  }
}

2. Skills 대폭 개선 (2.1)

핫 리로드

이전:

Skill 수정 → Claude 재시작 필요 → 컨텍스트 손실

2.1 이후:

Skill 수정 → 즉시 반영! → 계속 작업

실전 워크플로우:

  
터미널 1 (Claude 실행 중):
> "API 엔드포인트 만들어줘"

터미널 2 (Skill 수정):
vim ~/.claude/skills/api-standards.md
# "에러 처리 규칙 추가"
:wq

터미널 1:
# 다음 작업부터 자동으로 새 규칙 적용!
> "다음 엔드포인트 만들어줘"

Slash Command 메뉴

이전:

Skills는 자동 활성화만 가능
수동 호출 불가능

2.1 이후:

  
> /ski[TAB]

자동완성:
/skill-api-design      # API 설계 가이드
/skill-testing        # 테스트 작성 가이드
/skill-security       # 보안 체크리스트

Skills에 user-invocable 옵션:

  
---
name: api-design
description: API 설계 베스트 프랙티스
user-invocable: true  # 슬래시 명령으로 호출 가능
---

이제 /skill-api-design으로 직접 호출할 수 있습니다!

Skills에서 Hooks 정의

이전:

Hooks는 settings.json에서만 정의
Skills와 분리됨

2.1 이후:

Skills 내부에서 Hooks 정의 가능
라이프사이클 통합

  
---
name: secure-operations
description: 보안 작업 수행
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh $TOOL_INPUT"
          once: true
---

# 보안 작업 가이드

보안 검사를 먼저 수행하고 작업을 진행합니다...

3. Auto-Continue: 더 이상 멈추지 않는 Claude

이전의 제한

Claude: "파일 10개 분석 중... (5/10)"
[토큰 제한 도달]

→ 작업 중단
→ 사용자: "계속해줘" 입력 필요
→ 컨텍스트 손실 가능

2.1의 Auto-Continue

Claude: "파일 100개 분석 중..."
[토큰 제한 도달]

→ 자동으로 중요 정보 압축
→ 새 컨텍스트로 자동 전환
→ 작업 계속 진행

사용자 개입 불필요!

실전 효과:

이전: 
작업 시작 → 15분 진행 → 중단 → "계속해줘" → 5분 → 중단 → ...
총 시간: 30분 + 사용자 개입 5회

2.1:
작업 시작 → 자동 계속 → 자동 계속 → 완료
총 시간: 20분, 사용자 개입 0회

4. Resilient Subagents: 포기하지 않는 에이전트

이전의 문제

Subagent: "파일 접근 권한 요청"

사용자: [거부]

Subagent: ❌ "작업 중단" (포기)
메인 Claude: "Subagent가 실패했습니다."

2.1의 해결

Subagent: "파일 접근 권한 요청"

사용자: [거부]

Subagent: "대안 찾는 중..."
→ 공개 문서 검색
→ 기존 지식 활용
→ 부분 결과 제공 ✓

메인 Claude: "Subagent가 대안으로 작업 완료"

검증 루프의 개선:

이전:
Subagent → 테스트 실행 → 실패 → 포기 ❌

2.1:
Subagent → 테스트 실행 → 실패 → 다른 방법 시도 → 성공 ✓

5. Frictionless Plan Mode

사용자: "이 기능 분석해줘"

Claude: "Plan 모드로 전환하시겠습니까? [승인 필요]"
사용자: [승인]

Claude: "분석 시작..."

승인 다이얼로그가 흐름을 방해함.

2.1

사용자: "이 기능 분석해줘"

Claude: [자동으로 Plan 모드 진입]
"분석 중... Explore Subagent 생성..."

또는 명시적으로:

사용자: "/plan 이 기능 분석해줘"

Claude: [즉시 Plan 모드]

Plan Mode 단축키:

/plan - Plan 모드 활성화
Shift+Tab 불필요 (자동 활성화)

6. Hooks 통합: 모든 곳에서 Hooks

2.1의 Hooks 적용 범위

Skills에서 Hooks
Commands에서 Hooks  
Subagents에서 Hooks
전역 Hooks (settings.json)

예시: Command에서 Hooks 사용

  
---
name: deploy
description: 프로덕션 배포
hooks:
  PreToolUse:
    - matcher: "Bash && tool_input.command matches 'deploy'"
      hooks:
        - type: prompt
          message: "⚠️  프로덕션 배포입니다. 계속하시겠습니까?"
          require_approval: true
---

프로덕션 배포를 수행합니다...

예시: Subagent에서 Hooks 사용

  
---
name: database-migrator
description: 데이터베이스 마이그레이션 실행
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/backup-db.sh"
          description: "마이그레이션 전 DB 백업"
  PostToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/verify-migration.sh"
          description: "마이그레이션 검증"
---

once: true 옵션

세션당 한 번만 실행:

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/setup-env.sh"
          once: true

첫 Bash 명령 시에만 실행되고, 이후는 건너뜁니다.

7. 미래 로드맵 (커뮤니티 요청사항)

아직 구현되지 않았지만 요청 중인 기능:

Skill 제어 옵션

  
# 원하는 기능
> claude --skill=analysis  # 특정 Skill 강제 활성화
> claude --disable-skill=verbose  # 특정 Skill 비활성화

# 아직 불가능

Skill 호출 로깅

  
# 원하는 기능
> /skill-log

Skill 활성화 이력:
13:45 - api-design (API 설계 요청으로 활성화)
13:47 - testing (테스트 작성 중 자동 활성화)
13:50 - security (보안 키워드 감지)

# 아직 불가능

조건부 Hooks

  
# 원하는 기능
hooks:
  PreToolUse:
    - matcher: "Bash"
      condition: "previous_tool == 'Edit' && failed == true"
      hooks:
        - type: command
          command: "git checkout $file_path"

# 부분적으로만 지원

8. 2.1 업그레이드 가이드

마이그레이션 체크리스트

1. Claude Code 업데이트

npm update -g @anthropic-ai/claude-code
# 또는
brew upgrade claude-code

2. Skills 파일 검토

user-invocable: true 추가 고려:

  
---
name: my-skill
user-invocable: true  # 슬래시 명령으로 호출 가능
---

3. MCP 설정 최적화

더 이상 수동 활성화/비활성화 불필요!

  
{
  "mcpServers": {
    // 필요한 모든 서버 등록
    // Tool Search가 자동으로 관리
  }
}

4. Hooks 통합 기회

settings.json의 Hooks를 Skills/Commands로 이동 고려:

기존 (settings.json):
{
  "hooks": [...]
}

새로운 방식 (Skill 내부):
---
name: my-workflow
hooks:
  PreToolUse: [...]
---

5. Plan Mode 워크플로우 간소화

/plan 명령 활용:

  
# 이전
"Shift+Tab을 눌러 Plan 모드로 전환 → 승인"

# 2.1
"/plan 분석 시작"

마치며: 진짜 가치는 어디에 있는가

도구의 관점 vs 시스템의 관점

도구의 관점에서 보면:

Claude Code는 “코드를 빠르게 작성해주는 AI”
Skills는 “프롬프트를 저장하는 파일”
Hooks는 “자동 실행 스크립트”
Subagents는 “작업을 나눠서 처리하는 기능”

시스템의 관점에서 보면:

Claude Code는 “개발 워크플로우 전체를 재정의하는 프레임워크”
Skills는 “조직의 지식을 코드화하는 방법”
Hooks는 “품질을 강제하는 가드레일”
Subagents는 “전문성을 구조화하는 아키텍처”

패러다임 전환

이전의 개발 방식

개발자의 머릿속:
"이 기능을 어떻게 구현하지?"
  → 코드 작성
  → 테스트 작성
  → 리뷰 요청
  → 수정
  → 배포

AI 도구 사용:
"Copilot, 이 함수 자동완성해줘"
"ChatGPT, 이 에러 어떻게 고쳐?"

여전히 개발자가 워크플로우를 관리합니다.

Claude Code 패러다임

개발자:
"결제 시스템 구현해줘. 우리 표준 준수하고, 
테스트 포함하고, 보안 리뷰 받아야 해."

Claude Code:
├─ [자동] coding-standards Skill 참조
├─ [자동] testing-guide Skill 참조
├─ [자동] Planner Subagent로 계획 수립
├─ [자동] Builder Subagent로 구현
├─ [자동] PostToolUse Hook으로 포맷팅
├─ [자동] Tester Subagent로 테스트 작성
├─ [자동] Security Reviewer로 보안 검토
└─ [자동] Code Reviewer로 품질 검토

개발자: [최종 승인]

워크플로우 자체가 자동화됩니다.

세 가지 핵심 인사이트 재정리

1. 계층적 자동화

낮은 수준: 도구의 나열

ESLint + Prettier + GitHub Actions
= 각각 별도 설정, 수동 연결

높은 수준: 계층의 조합

Skills (원칙) + Hooks (타이밍) + Subagents (역할)
= 자동 연결, 자동 협력

2. 컨텍스트 경제학

잘못된 접근:

"기능이 많으면 좋다"
→ 모든 MCP 활성화
→ 컨텍스트 고갈
→ 성능 저하

올바른 접근:

"필요한 것만 적절히"
→ 선택적 활성화 (또는 Tool Search)
→ 컨텍스트 보존
→ 일관된 품질

3. 분리를 통한 병렬성

표면적 이해:

"병렬로 돌리면 빠르다"

깊은 이해:

"충돌하지 않게 분리하면, 
자연스럽게 병렬이 가능하다"

실천 가능한 시작점

초보자 (Claude Code 처음 사용)

1주차:

CLAUDE.md 작성
기본 Skills 2-3개 만들기
자주 사용하는 명령을 Command로 저장

2주차:

PostToolUse Hook으로 자동 포맷팅 설정
첫 Subagent (code-reviewer) 생성

3주차:

/fork로 병렬 작업 시도
컨텍스트 모니터링 습관화

중급자 (기본 사용법 숙지)

목표:

Skills 5-10개로 지식 체계화
Hooks로 품질 가드레일 구축
Subagents 3-5개로 전문화

체크리스트:

프로젝트 표준이 Skills로 문서화됨
반복 작업이 Commands로 자동화됨
품질 검증이 Hooks로 강제됨
전문 작업이 Subagents로 위임됨

고급자 (팀 전체 적용)

목표:

조직 표준의 코드화
지식의 민주화
온보딩 시간 단축

전략:

Plugin으로 팀 설정 배포
Git Worktrees로 병렬 개발 구조화
CI/CD와 Hooks 통합
정기적인 설정 리뷰 세션

마지막 조언

1. 완벽을 추구하지 마세요

❌ "완벽한 Skill을 먼저 만들어야지"
✅ "일단 간단하게 만들고 개선하자"

Claude Code 설정은 살아있는 문서입니다. 프로젝트와 함께 진화합니다.

2. 측정하세요

  
# 정기적으로
> /context

# 30% 넘으면 최적화 신호
# 50% 넘으면 즉시 조치

3. 공유하세요

혼자만의 최적화는 제한적입니다. 팀과 공유하고, 커뮤니티에 기여하세요.

4. 실험하세요

이 가이드는 시작점입니다. 여러분의 프로젝트와 팀에 맞게 변형하고 실험하세요.

결론

Claude Code는 단순한 코딩 도구가 아닙니다. 개발 워크플로우 전체를 재설계하는 프레임워크입니다.

속도의 개선은 부수적입니다.

진짜 가치는:

지식의 코드화
품질의 자동화
전문성의 구조화
워크플로우의 재정의

그리고 이 모든 것은 분리와 조합이라는 단순한 원리에서 시작됩니다.

참고 자료

공식 문서

커뮤니티 리소스

affaan-m/everything-claude-code - 해커톤 우승자의 전체 설정
Awesome Claude Code - 커뮤니티 Skills, Commands, Plugins

목차

들어가며: 자동화를 바라보는 새로운 시각

우리가 알던 자동화

Claude Code가 제시하는 새로운 패러다임

기초 개념: Claude Code의 구성 요소 이해하기

1. CLAUDE.md: 프로젝트의 헌법

2. Skills: 자동으로 활성화되는 전문 지식

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

4. Hooks: 이벤트 기반 자동화

5. Subagents: 전문가 팀 구성

6. MCP (Model Context Protocol): 외부 세계와의 연결

첫 번째 핵심: Skills, Hooks, Subagents의 3층 구조

1층: Skills와 Commands - 지식과 진입점

Skills: 광범위한 가이드라인

Commands: 구체적인 실행 버튼

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

PreToolUse Hook의 실전 활용

PostToolUse Hook으로 품질 자동 유지

Stop Hook으로 최종 점검

3층: Subagents - 전문가 팀의 분업

왜 Subagent가 필요한가?

실전 예시: 리팩토링 워크플로우

Subagent의 권한 제한

컨텍스트 보존의 가치

3층 구조가 맞물릴 때

핵심 교훈

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

이론과 현실의 간극

도구 정의가 먹는 컨텍스트

MCP의 숨겨진 비용

실제 사례: 컨텍스트 압박

해커톤 우승자의 해법: 선택적 활성화

“20-30개 설정, 10개 미만 활성화, 80개 미만 도구” 규칙

최신 업데이트: MCP Tool Search (게임 체인저!)

Claude Code 2.1.7의 혁신

실제 측정 결과

작동 방식

개발자가 해야 할 일

컨텍스트가 중요한 이유

컨텍스트 ≠ 단순 저장 공간

도구 과다의 숨겨진 비용

실전 가이드: 컨텍스트 최적화

1. 프로젝트 유형별 MCP 세트 정의

2. 컨텍스트 모니터링

3. “Just-in-Time” MCP 활성화

4. Subagent 활용으로 컨텍스트 절약

핵심 교훈

세 번째 핵심: 분리를 통한 병렬 처리

병렬 처리의 함정

세 가지 병렬화 전략

1. /fork: 대화 세션 분리

개념

실전 시나리오

성공의 조건: 비중첩(Non-overlapping)

실전 팁

2. Git Worktrees: 코드베이스 분리

개념

일반 Git vs Git Worktrees

설정 방법

실전 시나리오

/fork vs Worktrees 비교

Git Worktrees 활용 패턴

3. Subagents: 역할 분리

개념 복습

병렬 실행 패턴

실전 예시: 복잡한 기능 개발

왜 충돌이 없는가?

세 전략의 통합 활용

완전한 격리가 필요한 대규모 작업

공통 원리: 분리 → 병렬

패턴 정리

의사결정 플로우차트

핵심 교훈

실전 활용: 프로젝트에 적용하기

1단계: 기본 구조 설정

CLAUDE.md 작성

2단계: 필수 Skills 생성

Skill 1: 코딩 표준

Skill 2: 테스트 작성

3단계: 편리한 Commands 설정