Claude Code 토큰 최적화와 에이전트 전략

2026년 3월 17일·12 min read

DevTools claude-code token-optimization subagent team skill publishing

토큰 소모 원리: 누적 재전송

Claude Code는 매 턴(turn)마다 전체 대화 기록을 API에 재전송한다.

턴 N의 API 호출 비용 = 시스템 프롬프트 + 턴 1~N-1 전체 + 현재 입력

예시: 파일 분석 작업

턴 1: [시스템] + [사용자: "분석해줘"]                    → 2K 토큰
턴 2: [시스템] + [턴1] + [Read 파일A: 500줄]             → 7K 토큰
턴 3: [시스템] + [턴1~2] + [Read 파일B: 300줄]           → 10K 토큰
턴 4: [시스템] + [턴1~3] + [Read 파일C: 400줄]           → 14K 토큰

핵심: 읽은 내용이 이후 모든 턴에 계속 재전송된다. 파일 20개를 읽으면 마지막 턴에는 20개 파일 내용이 전부 포함된 상태로 API를 호출한다.

10턴 후:
- 파일 분석 결과 80K가 이후 매 턴에 재전송
- 80K × 10턴 = 800K 누적 전송

세 가지 실행 환경

스킬 (Skill) — 메인 컨텍스트에 지침 주입

┌─ 메인 컨텍스트 ──────────────────────┐
│ Skill("widget")                      │
│   → 프롬프트 2K 주입                  │
│   → 이후 모든 턴에 2K가 계속 딸려감   │
│                                      │
│ 내가 직접 파일 읽기, 분석, 수정       │
│   → 전부 여기서 토큰 소모             │
└──────────────────────────────────────┘

비유: 매뉴얼을 펼쳐놓고 내가 직접 하는 것
특징: 가볍고 빠름. 하지만 작업량이 많으면 컨텍스트가 빠르게 차옴
적합: 짧은 지침, 워크플로우 가이드, 코딩 컨벤션 참조

서브에이전트 (Task) — 격리된 일회성 작업자

메인 컨텍스트                     서브에이전트 (별도 API 세션)
┌────────────┐                   ┌──────────────────────┐
│ Task() 호출 │ ── prompt ──→    │ 파일 20개 읽기 (50K)  │
│ (0.5K)     │                   │ 분석 (10K)            │
│            │                   │ 중간 추론 (20K)       │
│            │ ←── 결과 ────     │ 총 소모: ~80K         │
│ 결과 수신   │                   └──────────────────────┘
│ (1K)       │                        종료, 컨텍스트 소멸
│            │
│ 이후 턴에   │
│ 1.5K만 누적 │  ← 80K가 아닌 1.5K만!
└────────────┘

비유: 다른 사람에게 일을 시키고 결과만 받는 것
특징: 별도 컨텍스트 윈도우에서 작업, 결과만 메인에 반환. 기본적으로 작업 후 비활성화되지만, resume 파라미터로 이전 컨텍스트를 유지한 채 재개할 수 있다
토큰 절약:
- 메인 직접: 80K × 10턴 = 800K 누적 전송
- 서브에이전트: 80K(서브) + 1.5K × 10턴 = 95K
적합: 파일 많이 읽는 분석, 코드 리뷰, 엣지케이스 탐색

팀 (Team) — 지속적 병렬 작업자들

리더 (메인)          팀원A              팀원B
┌──────────┐      ┌──────────┐      ┌──────────┐
│ 각자 독립  │      │ 독립      │      │ 독립      │
│ 컨텍스트   │      │ 컨텍스트   │      │ 컨텍스트   │
│           │ ←→  │           │ ←→  │           │
└──────────┘      └──────────┘      └──────────┘
  메시지만 교환        자기 작업은          자기 작업은
                     자기 컨텍스트에서     자기 컨텍스트에서

비유: 슬랙 채널에서 팀원들과 협업하는 것
서브에이전트와의 차이:
- 서브에이전트: 결과 반환 후 비활성화 → 기본적으로 대화 끝. 단, resume으로 이전 컨텍스트를 유지한 채 재개 가능
- 팀원: 살아있음 → 메시지로 추가 지시, 수정 요청, 팀원 간 조율 가능
적합: 상호 의존적 대규모 작업, 장시간 협업

비교표

	스킬	서브에이전트	팀
실행 위치	메인 컨텍스트	별도 프로세스	별도 프로세스 × N
수명	메인과 동일	작업 후 비활성 (resume 가능)	shutdown까지 지속
통신	직접 주입	단방향 (결과 반환)	양방향 메시지
팀원 간 소통	-	불가	가능
컨텍스트 비용	메인에 누적	결과만 누적	메시지만 누적
적합한 작업	가벼운 참조	독립 단일 작업	상호 의존 작업

조합 가능

스킬과 서브에이전트는 대립 관계가 아니다. 서브에이전트 안에서 스킬을 사용할 수 있다.

메인: Task(prompt="Skill('widget') 참고해서 분석해줘")
       ↓
서브에이전트:
  Skill("widget") → 지침 주입 (서브 컨텍스트에서)
  파일 읽기, 분석 (서브 컨텍스트에서)
  결과 반환
       ↓
메인: 결과만 수신 (스킬 내용 + 분석 과정은 안 옴)

스킬 = 무엇을 하는지 (매뉴얼) 서브에이전트 = 어디서 하는지 (실행 환경)

실전 전략: 멀티 페이지 퍼블리싱

상황

여러 페이지를 Figma에서 퍼블리싱해야 함
페이지는 서로 독립적
디자인 시스템은 공유 (공용 컴포넌트, 토큰)
페이지 간 유사한 컴포넌트가 많음

전략 1: 서브에이전트 병렬 (위험)

서브A: 페이지A → Button 만듦
서브B: 페이지B → Button 또 만듦 (다르게)
서브C: 페이지C → Button 또 만듦 (또 다르게)
→ 3개의 중복 Button, 스타일 불일치

서로 모르니까 같은 컴포넌트를 각자 만든다.

전략 2: 팀 (과잉)

팀원끼리 소통은 가능하지만, 퍼블리싱은 Figma 조회 → 코드 생성이라 실시간 조율이 크게 필요하지 않다.

전략 3: 2단계 하이브리드

Phase 1 (메인): 공용 컴포넌트 먼저 구현
Phase 2 (서브에이전트 × N): 페이지별 병렬 퍼블리싱
Phase 3 (메인): 통합 검수

공유 자원은 메인에서 먼저 만들고, 독립 작업만 병렬로 분산.

전략 4: 스킬 주입 (더 효율적)

Phase 1 대신 스킬 문서에 공용 컴포넌트를 명시해둔다.

# publishing-guide 스킬
## 공용 컴포넌트
- Button: src/components/ui/button.tsx (variant: primary, secondary, ghost)
- Card: src/components/ui/card.tsx
## 규칙
- 새 공용 컴포넌트 만들지 말 것
- NativeWind 사용

서브에이전트가 스킬을 먼저 참조한 후 퍼블리싱하면, 공용 컴포넌트를 새로 만들지 않고 기존 것을 import한다.

전략 5: 최적 조합 (가장 효율적)

3가지 최적화를 조합:

최적화 A: 커스텀 에이전트 정의

.claude/agents/publisher.md에 퍼블리싱 전용 에이전트를 정의하면, 스킬처럼 도구를 호출해서 읽을 필요 없이 시작할 때 이미 지침이 주입되어 있다.

스킬 방식:     서브에이전트 시작 → Skill() 호출 (1턴 소모) → 작업
커스텀 에이전트: 서브에이전트 시작 → 바로 작업 (지침 내장)

최적화 B: Figma 스펙 사전 분석

각 서브에이전트가 Figma API를 개별 호출하는 대신, 메인에서 한 번 조회해서 구조화된 스펙을 프롬프트로 넘긴다.

현재:  서브 × N → 각자 Figma API 호출 (느림, 토큰 많음)
개선:  메인 1회 조회 → 스펙 JSON → 서브에이전트 프롬프트에 포함

최적화 C: 레퍼런스 페이지 패턴

가장 복잡한 페이지를 메인에서 먼저 만들고, 나머지는 서브에이전트에게 "이 코드를 참고해서 만들어"라고 넘긴다. 규칙을 나열하는 것보다 실제 코드가 더 정확한 결과를 낸다.

최종 플로우

1. 커스텀 에이전트 정의 (.claude/agents/publisher.md)
   → 공용 컴포넌트, 컨벤션, 토큰 규칙 내장
 
2. 메인에서 첫 페이지(가장 복잡한 것) 직접 퍼블리싱
   → 레퍼런스 코드 생성
 
3. 메인에서 나머지 페이지 Figma 스펙 일괄 조회
   → 구조화된 스펙 정리
 
4. 커스텀 에이전트 × N 병렬 실행
   → 프롬프트: "레퍼런스: src/app/page-a/, 스펙: {JSON}"
   → Figma 조회 불필요, 스킬 호출 불필요, 바로 코드 생성
 
5. 메인에서 통합 검수
   → 중복 체크, 스타일 일관성, type-check + lint

최적화 효과 요약

최적화	절약 내용
커스텀 에이전트	스킬 호출 1턴 × N개 절약
Figma 사전 분석	서브에이전트별 Figma API 호출 제거
레퍼런스 페이지	규칙 설명 대신 실제 코드로 품질 향상

효율화 판단 기준

작업 분류
  │
  ├─ 가벼운 참조/지침 → 스킬 (메인에서 직접)
  │   예: 코딩 컨벤션, 워크플로우 가이드
  │
  ├─ 무거운 독립 작업 → 서브에이전트
  │   예: 코드 리뷰, 엣지케이스 분석
  │
  ├─ 병렬 독립 작업 → 서브에이전트 × N (동시 실행)
  │   예: 멀티 페이지 퍼블리싱, 여러 파일 분석
  │
  └─ 상호 의존 대규모 → 팀
      예: 프론트+백엔드 동시 리팩토링

핵심 원칙: 메인 컨텍스트에는 사용자와의 대화와 의사결정만 남기고, 무거운 작업은 격리한다.