Claude Code Fable 오케스트레이션: 서브에이전트 설정과 비용 검증법

Fable이 계획과 검토를 맡고, Sonnet·Haiku 서브에이전트가 일부 작업을 수행하면 비용을 줄일 여지가 있습니다. 하지만 전체 토큰이 줄어든다는 뜻은 아닙니다. 위임할 때마다 설명과 결과 보고가 추가되고, 실패한 작업을 다시 시키면 오히려 더 비싸질 수 있습니다.

이 글은 Claude Code의 공식 문서를 바탕으로 역할 분리 설정과 비용 비교 방법을 설명합니다. 특정 프로젝트에서 절감을 실측한 후기가 아닙니다. 설정은 적용용 예시이며, 아래 비용 계산도 실제 Fable 요금이나 벤치마크가 아닌 가상 조건입니다.

2026년 11월 4일 개정: 종전 제목의 ‘토큰 최대 5~10배 절약’은 이 글에서 재현 조건과 측정 기록을 제시하지 못한 수치라 삭제했습니다. 같은 문구의 대표 이미지와 과거 가격이 포함된 구조도도 제외했습니다. URL은 유지했습니다.

1. 먼저 토큰·비용·구독 한도를 구분하세요

  • 전체 토큰 사용량: 메인 에이전트와 모든 워커가 사용한 입력·출력·캐시 관련 사용량입니다. 메인 세션의 컨텍스트가 가벼워졌다고 전체 토큰까지 줄어든 것은 아닙니다.
  • API 비용: 모델별 입력·출력과 캐시 처리에 적용되는 요금으로 계산합니다. 동일한 토큰 수라도 모델과 과금 항목에 따라 금액이 달라집니다.
  • 구독 사용 한도: 플랜에 포함된 사용량과 추가 과금 조건입니다. API 정가로 계산한 금액이 곧 구독자의 청구액이나 남은 사용 시간을 뜻하지는 않습니다.

서브에이전트는 별도 컨텍스트에서 작업하지만 요청은 같은 사용 한도에 반영됩니다. 따라서 “메인 모델이 덜 읽었다”와 “작업 전체가 더 저렴해졌다”는 별도로 확인해야 합니다.

근거: 서브에이전트 공식 문서, Claude Code 비용·사용량 문서

2. 모든 코드를 넘기기보다 경계가 분명한 일을 맡기세요

오케스트레이터는 목표와 완료 조건을 정하고, 작업을 나누고, 결과를 검토합니다. 워커는 정해진 범위의 탐색이나 구현을 수행합니다. 이 역할 분리는 Fable 전용 기능이 아니며, 작업에 적합한 다른 사용 가능 모델로도 구성할 수 있습니다.

  • 탐색 담당: 특정 함수의 호출 위치, 관련 테스트, 변경 영향 범위를 찾아 파일 경로와 근거를 보고합니다.
  • 구현 담당: 승인된 설계와 수정 범위 안에서 코드를 바꾸고 테스트 결과를 보고합니다.
  • 메인 담당: 요구사항의 모호함, 공통 인터페이스 변경, 보안·설계 판단을 검토하고 최종 결과를 통합합니다.

구현도 판단이 필요한 작업입니다. “저렴한 모델은 생각할 필요 없이 타이핑만 한다”는 식으로 나누기보다, 실패를 알아볼 수 있고 완료 조건을 검증할 수 있는 작업부터 맡기는 편이 낫습니다. 한 줄 수정처럼 짧은 일은 위임 설명이 실제 수정 작업보다 길어질 수 있습니다.

탐색에서 긴 검색 결과와 로그를 워커가 처리하고 필요한 요약만 돌려주면 메인 컨텍스트를 보호할 수 있습니다. 반면 여러 워커가 같은 파일을 반복해서 읽거나 같은 문제를 동시에 풀면 총사용량은 늘어납니다.

3. Fable의 접근 권한과 실제 모델을 먼저 확인하세요

Claude Code에서 /model을 열어 현재 계정과 제공자가 지원하는 모델을 확인합니다. Fable이 표시되고 사용 조건을 확인했다면 선택할 수 있습니다. 보이지 않는다면 해당 계정에서 이용 가능한 모델로 시작하세요. 이 글을 따라 하기 위해 추가 과금을 활성화할 필요는 없습니다.

접근 중단에 관한 옛 글도 날짜를 확인해야 합니다. Anthropic은 2026년 6월 중단 이후 7월 1일 접근 재개를 공지했습니다. 이 과거 공지가 현재 모든 계정의 이용 가능 여부나 무료 포함량을 보장하는 것은 아닙니다.

검토한 모델 설정 문서에는 fable, sonnet, haiku 등의 별칭이 안내되어 있습니다. 별칭이 가리키는 버전은 제공자와 설정에 따라 달라지고 업데이트될 수 있습니다. 재현 가능한 비교를 하려면 별칭만 적지 말고 실제로 실행된 모델 ID, Claude Code 버전, 추론 강도, 연결 제공자를 함께 기록하세요.

추론 강도도 무조건 최대로 올리거나 고정된 값을 만능 설정으로 쓰기보다, 같은 완료 조건에서 결과와 비용을 비교합니다. 메인 세션의 설정이 다른 모델을 쓰는 워커에 그대로 적용된다고 가정하지 마세요.

근거: 모델 설정 공식 문서, Fable 접근 재개 공지, 서브에이전트의 모델·effort 설정

4. 서브에이전트 두 개로 작게 시작하기

프로젝트 전용 정의는 .claude/agents/, 개인 공통 정의는 ~/.claude/agents/에 둡니다. YAML 프런트매터의 name과 description은 필수입니다. 아래 예시는 프로젝트용 파일이며, 실제 저장소에서 실행 검증한 결과가 아니라 공식 형식에 맞춘 시작용 템플릿입니다.

읽기 전용 탐색: .claude/agents/repo-scout.md

---
name: repo-scout
description: 지정한 범위의 코드와 테스트를 읽고 근거 위치를 보고한다.
tools: Read, Glob, Grep
model: haiku
---
요청한 범위만 조사한다. 파일을 수정하지 않는다.
결론마다 파일 경로와 관련 함수 또는 줄 위치를 남긴다.
추측과 확인된 사실을 구분한다.
긴 원문 대신 핵심 결과, 불확실한 점, 다음 확인 항목을 보고한다.

여기서는 읽기·검색 도구만 지정했습니다. 다만 읽을 수 있는 경로에 대한 접근 제어는 별도 설정입니다. 읽기 전용이라는 이유로 비밀값이 있는 파일까지 조사 대상으로 넘기지는 마세요.

범위가 정해진 구현: .claude/agents/scoped-worker.md

---
name: scoped-worker
description: 합의된 수정 범위와 완료 조건에 따라 구현하고 검증한다.
tools: Read, Edit, Write, Glob, Grep, Bash
model: sonnet
---
요청에서 지정한 파일과 기능 범위 안에서 작업한다.
공통 인터페이스나 수정 범위를 넓혀야 한다면 먼저 보고한다.
요청에서 지정한 테스트 명령을 실행하고 실제 결과를 남긴다.
커밋, 배포, 의존성 추가는 별도 승인 없이 하지 않는다.
반환 내용: 변경 파일, 변경 이유, 테스트 명령과 결과, 남은 위험.

Bash는 테스트 전용 권한이 아닙니다. 셸 명령으로 파일을 수정하거나 다른 작업을 할 수도 있습니다. 이 예시를 쓰기 전에 프로젝트의 권한 승인 규칙과 실행 환경을 확인하세요. 프롬프트의 금지 문장은 시스템 수준의 차단 장치가 아닙니다.

현재 공식 문서는 일반적인 에이전트 파일 변경을 자동 감지한다고 안내하지만, 실행 중 처음 만든 디렉터리 등 일부 조건에서는 재시작이 필요합니다. 정의가 보이지 않으면 파일 위치·YAML 형식과 사용 중인 버전을 확인하고 새 세션에서 다시 확인하세요. 구버전 설명만 보고 /agents가 항상 같은 생성 마법사를 연다고 가정하지 않는 것도 중요합니다.

형식·권한·로드 조건: Create custom subagents

5. 위임할 때는 결과의 모양까지 정합니다

자연어로 에이전트 이름을 언급하면 Claude가 위임 여부를 판단합니다. 특정 에이전트를 명시적으로 호출하려면 입력창에서 @를 누르고 해당 에이전트를 선택하는 방법이 공식 문서에 안내되어 있습니다.

다음은 가상의 날짜 표시 기능을 조사하는 요청입니다. 경로는 자신의 저장소에 맞게 바꾸세요.

repo-scout를 사용해 src/lib/date.ts의 호출 위치와
관련 테스트 파일만 조사해줘. 파일은 변경하지 마.
반환할 내용은 다음 네 가지야.
1. 호출하는 파일과 함수
2. 현재 동작을 확인할 테스트
3. 변경 시 영향을 받을 부분
4. 자료만으로 확인할 수 없는 부분

탐색 결과를 확인한 뒤 구현 워커에는 실제 수정할 파일, 유지해야 할 동작, 저장소에서 확인한 테스트 명령을 전달합니다. 서로 다른 디렉터리라는 이유만으로 독립적인 작업이라고 판단해서는 안 됩니다. 공통 설정·타입·의존성 파일이 겹치는지도 봐야 합니다.

CLAUDE.md에 넣을 위임 원칙 예시

작고 명확한 수정은 불필요하게 쪼개지 않는다.
탐색은 repo-scout, 범위가 확정된 구현은 scoped-worker를 검토한다.
위임 전 목표, 수정 가능 파일, 금지 범위, 완료 조건을 정한다.
같은 파일을 여러 워커가 동시에 수정하지 않게 한다.
공통 인터페이스 변경은 먼저 메인 세션에서 결정한다.
워커 결과는 변경 내용과 실제 테스트 결과로 검토한다.
반복 실패나 범위 확대가 생기면 계속 재시도하지 말고 계획을 다시 본다.

이 규칙은 행동을 유도하는 지침입니다. 반드시 위임하게 하거나 직접 수정을 확실하게 차단하는 권한 정책은 아닙니다. 그런 제약이 필요하면 별도로 검증한 도구 권한과 실행 환경을 사용해야 합니다.

병렬 실행은 대기 시간을 줄일 수 있지만 비용을 자동으로 줄이지는 않습니다. 처음에는 탐색 한 건과 구현 한 건을 순서대로 진행하고, 독립성이 확인된 작업만 병렬화하세요. 작업자 수를 늘리기 전에 중복 탐색과 통합 비용부터 확인하는 편이 좋습니다.

6. 토큰이 늘어도 비용은 줄 수 있습니다: 가상 계산

아래 단가와 사용량은 모두 설명용 가정입니다. 실제 Fable·Sonnet·Haiku 가격이나 측정 결과가 아닙니다. 캐시는 사용하지 않고 다른 요금도 없다고 가정합니다. 모델 A의 입력/출력은 100만 토큰당 $8/$40, 모델 B는 $2/$8로 놓겠습니다.

  • 단일 A 모델: 입력 100,000, 출력 20,000 → 0.1 × 8 + 0.02 × 40 = $1.60
  • 위임 구조의 메인 A: 입력 20,000, 출력 4,000 → 0.02 × 8 + 0.004 × 40 = $0.32
  • 위임 구조의 워커 B 합계: 입력 100,000, 출력 20,000 → 0.1 × 2 + 0.02 × 8 = $0.36

위임 구조의 합계는 $0.32 + $0.36 = $0.68입니다. 총토큰은 120,000개에서 144,000개로 20% 늘었지만, 이 가정의 비용은 (1.60 − 0.68) ÷ 1.60 × 100 = 57.5% 줄었습니다.

반대로 워커가 같은 분량의 작업을 최초 실행 포함 네 번 소모한다면 $0.32 + 4 × $0.36 = $1.76으로 단일 모델보다 비싸집니다. 실제로는 메인 모델의 재검토 비용도 더해질 수 있습니다.

이 계산은 절감률을 약속하는 예시가 아닙니다. 모델별 사용량, 단가, 재시도 횟수가 모두 필요하다는 것을 보여줍니다. 실제 계산에서는 입력·출력 외에 캐시 읽기·쓰기 등 과금 항목을 구분하고, 도구나 플랫폼의 별도 요금이 있다면 포함하세요.

7. 내 프로젝트에서 효과를 확인하는 비교 절차

실험 대상은 결과를 테스트로 확인할 수 있는 작은 작업 하나로 시작하세요. 단일 모델과 위임 구조의 목표가 다르면 비용을 공정하게 비교하기 어렵습니다.

  1. 출발점 고정: 동일한 저장소 커밋에서 만든 별도 작업 사본을 사용합니다. 기존 작업물을 덮어쓰거나 강제로 되돌리지 않습니다.
  2. 조건 고정: 요청문, 수정 허용 범위, 테스트와 완료 조건을 동일하게 둡니다. 모델 ID·버전·추론 강도·제공자를 기록합니다.
  3. 두 방식 실행: A는 단일 모델, B는 메인 모델과 정의한 워커를 사용합니다. 캐시의 준비 상태와 이전 대화의 영향을 기록합니다.
  4. 전체 사용량 수집: 메인과 모든 워커, 실패한 호출과 재시도까지 포함합니다. 일부 사용량을 확인할 수 없다면 총절감률을 단정하지 않습니다.
  5. 품질을 먼저 대조: 같은 테스트 통과 여부, 누락, 사람이 고친 부분을 확인합니다. 실패한 실행을 싸게 끝났다는 이유로 성공으로 세지 않습니다.
  6. 비용과 시간을 별도 비교: API 비용, 소요 시간, 사람의 검토·수정 시간, 재시도 횟수를 나눠 봅니다. 가능하면 여러 번 비교해 편차도 남깁니다.

검토한 공식 문서에서는 /usage의 Session 영역으로 API 토큰 사용량과 모델별 통계를 확인하도록 안내합니다. 표시된 달러 금액은 추정치이며 최종 청구는 제공자의 사용량·청구 화면에서 확인해야 합니다. 구독 사용자는 플랜 한도와 추가 사용료를 별도로 봐야 합니다. 버전에 따라 명령이나 화면이 다르면 /help와 해당 버전 문서를 확인하세요.

비교 기록 양식
- 실행 날짜 / Claude Code 버전 / 저장소 커밋:
- 제공자 / 실제 모델 ID / 추론 강도:
- 방식: 단일 모델 또는 위임 구조
- 메인 + 워커별 입력 / 출력 / 캐시 읽기·쓰기:
- 전체 추정 비용 / 청구 확인 여부:
- 테스트 명령 / 통과 여부:
- 재시도 횟수 / 누락·오류 / 사람의 수정 내용:
- 작업 시간 / 검토 시간:
- 캐시 상태 등 비교 한계:

오케스트레이션의 목표는 ‘가장 많은 워커를 쓰는 것’이 아니라 같은 완료 기준을 만족하면서 전체 비용과 재작업을 줄이는 것입니다. 위임 효과가 불분명하면 단일 모델이나 탐색 전용 서브에이전트만 쓰는 구성이 더 나을 수 있습니다.

사용량 측정·과금 구분: Manage costs effectively

관련 글

댓글

이 블로그의 인기 게시물

클로드 Gmail 연동 방법: 이메일 분류·요약·답장 자동화

바이브 코딩에 유용한 핵심 AI 스킬 8가지와 생성 프롬프트

Claude Code 토큰 절약 가이드