Escalate hard decisions with the advisor tool: 비싼 추론은 ‘결정 순간’에만 올리는 Claude Code 비용 최적화 패턴

1. 개요

Escalate hard decisions with the advisor tool은 Claude Code에서 항상 강한 모델을 돌리는 대신, “계획 확정/반복 에러/완료 판정”처럼 결정이 어려운 순간에만 더 강한 모델(Advisor)을 호출해 비용과 품질을 동시에 최적화하는 운영 패턴입니다.

개발 주체는 Anthropic(Claude Code)이며, 기술적 기반은 Claude Code의 Advisor tool, 서브에이전트(Sub-agents), 그리고 레포 단위의 오케스트레이션 규칙(CLAUDE.md) 입니다. 핵심 목표는 (1) 메인 컨텍스트를 가볍게 유지하고 (2) 고비용 모델 호출을 최소화하며 (3) 위임/판단을 규칙 기반으로 재현 가능하게 만드는 것입니다.

---

2. 차별성

기존 방식의 한계 (기존 vs 새로운 방식)

핵심 역량 (Capabilities)

• Advisor tool로 “어려운 결정”만 상위 모델에 에스컬레이션(escalation)
• Sub-agents로 작업을 분리해 메인 컨텍스트를 안정적으로 유지
• CLAUDE.md 규칙으로 “위임이 자동이 아님” 문제를 해결(명시적 트리거)
• 비용 한도/품질 요구에 따라 메인 모델과 어드바이저 조합을 유연하게 선택

---

3. 시스템 구성 요소

주요 컴포넌트

작동 원리(흐름)

[세션 시작]
   |
   | 1) /model (메인 모델 선택)
   v
[메인 모델이 작업 수행]
   |
   | 2) /advisor (어드바이저 모델 설정)
   v
[오케스트레이션 준비]
   |
   | 3) 서브에이전트 정의(.claude/agents/*.md)
   | 4) CLAUDE.md에 위임 규칙 작성
   | 5) /reload-plugins
   v
[실행 단계]
   |
   |--(루틴/기계적 작업)--> [fast-worker(haiku)]
   |
   |--(깊은 추론 필요)----> [deep-reasoner(opus)]
   |
   |--(계획 확정/반복 오류/완료 판정 등 'hard decision')--> [Advisor(fable/opus)]
   v
[결정/검증 결과를 메인 모델이 반영하여 진행]

핵심 컴포넌트 상세

Advisor tool (어드바이저)

• 목적: 강한 모델을 상시 호출하지 않고, 결정이 어려운 순간에만 호출해 품질을 끌어올림
• 대표 트리거(권장):
  • 계획(Plan) 확정/수정이 필요한 시점
  • 동일 오류 반복, 디버깅이 막힐 때
  • “이제 끝났는가?” 같은 완료 판정(Definition of Done) 검증
• 비용 관점: Fable/Opus를 메인으로 상시 돌리는 것 대비 큰 비용 절감 가능

Sub-agents (서브에이전트)

• 목적: 메인 컨텍스트를 보호하면서 역할별로 작업을 분리
• 권장 고정 조합(상황 무관):
  • deep-reasoner = opus (무거운 추론 전용)
  • fast-worker = haiku (반복적/기계적 작업 전용)
• 포인트: 서브에이전트는 **필요할 때만 스폰(spawn)**되므로, “정의해 둔다고 상시 비용이 발생”하지 않음

CLAUDE.md 오케스트레이션 규칙

• 핵심: 위임은 자동이 아님
  규칙이 없으면 Claude가 “알아서” 서브에이전트/어드바이저를 적극적으로 쓰지 않을 수 있음.
• 따라서 “어떤 상황에 어떤 에이전트를 호출할지”를 명시적으로 적어야 함.

---

4. 주요 기능

4.1 어려운 결정만 에스컬레이션(Escalation)

• 메인 모델(Sonnet/Haiku 등)이 대부분의 작업을 처리
• 계획 확정, 반복 실패, 완료 판정 같은 hard decision에서만 Advisor(Fable/Opus)를 호출
• 결과: 품질 저하 없이 비용을 낮추는 운영 패턴 구현

4.2 역할 분리로 컨텍스트/비용 최적화

• deep-reasoner(opus): 설계/아키텍처/복잡한 버그 원인 분석 등 “깊은 추론”
• fast-worker(haiku): 파일 정리, 단순 코드 변환, 문서 포맷팅, 반복 작업
• 메인 모델: 통합 진행/결과 반영/최종 출력

4.3 비용 부담 상황별 추천 조합(메인 모델 vs 어드바이저)

---

5. 사용 방법

5.1 설정 순서(Order) — 왜 이 순서가 중요한가

1. 메인 모델 결정: /model sonnet (상황에 따라 opus/fable)
2. 어드바이저 켜기: /advisor fable (또는 opus)
3. 서브에이전트 파일 작성: .claude/agents/deep-reasoner.md, .claude/agents/fast-worker.md
4. CLAUDE.md에 오케스트레이션 규칙 기술: 언제 무엇을 위임할지 명시
5. 재로딩: /reload-plugins

이 순서인 이유:

• 모델/어드바이저는 세션 레벨 설정이라 먼저 정해야 이후 단계(위임/검증)의 비용 감이 잡힙니다.
• 서브에이전트 파일 → CLAUDE.md 규칙 → reload 순서여야 “위임 대상이 존재하는 상태”에서 규칙을 작성하게 되고, 마지막에 재로딩으로 인식이 완료됩니다.

5.2 요구사항/제약(중요)

• Advisor tool 자체 요구사항: Claude Code v2.1.98+
• Fable을 어드바이저로 사용: Claude Code v2.1.170+
• Anthropic API 기반에서만 가능
  • Bedrock / Vertex / Azure 기반에서는 불가(제약 사항)
• 비활성화 관련 환경변수 등은 공식 문서 참고(예: CLAUDE_CODE_DISABLE_ADVISOR_TOOL)

5.3 명령어 예시

# 1) 메인 모델 선택
/model sonnet

# 2) 어드바이저 설정
/advisor fable
# 또는
/advisor opus

# 5) 서브에이전트 추가/수정 후 재로딩
/reload-plugins

5.4 서브에이전트 파일 예시

.claude/agents/deep-reasoner.md (opus)

---
name: deep-reasoner
model: opus
description: Deep reasoning for architecture, debugging, and hard trade-offs.
---

You are a deep reasoning sub-agent. Focus on:
- Root-cause analysis for complex bugs
- Architecture/design trade-offs
- Producing a clear plan with risks and alternatives
Return concise, actionable guidance to the main agent.

.claude/agents/fast-worker.md (haiku)

---
name: fast-worker
model: haiku
description: Fast mechanical work: refactors, formatting, repetitive edits.
---

You are a fast worker sub-agent. Focus on:
- Mechanical code edits and refactors
- Applying consistent formatting
- Simple transformations and boilerplate generation
Keep responses short and implementation-oriented.

레포마다 새로 만들어야 하지만, ~/.claude/agents/에 두면 전 레포 공용으로 한 번만 설정할 수 있습니다.

5.5 CLAUDE.md 오케스트레이션 규칙 예시

# Orchestration Rules

## When to use Advisor (hard decisions)
- If planning is ambiguous or there are multiple viable approaches, consult the advisor before coding.
- If the same error occurs twice or debugging stalls for >10 minutes, consult the advisor.
- Before declaring completion, consult the advisor to validate "Definition of Done" and edge cases.

## When to delegate to sub-agents
- Delegate deep reasoning (architecture, complex debugging, trade-off analysis) to `deep-reasoner`.
- Delegate mechanical tasks (bulk edits, formatting, repetitive refactors, doc cleanup) to `fast-worker`.

## Output discipline
- Main agent integrates sub-agent/advisor outputs into a single coherent plan and implementation steps.
- Keep main context minimal; offload long analyses to sub-agents when appropriate.

---

6. 적용 시나리오

적합한 사용 사례

• 비용 한도가 있는 팀/개인 개발 환경에서 품질을 유지하며 운영해야 할 때
• PR 단위로 반복되는 작업(리팩터링, 포맷팅, 문서 정리)은 Haiku로 넘기고,
  설계/디버깅/결정은 Opus/Fable로 올리고 싶을 때
• “계획 수립 → 구현 → 검증” 루프에서 검증/완료 판정을 강화하고 싶을 때

제한사항(주의)

• Fable 어드바이저 사용은 Claude Code 버전 및 Anthropic API 제약을 받음(Bedrock/Vertex/Azure 불가)
• CLAUDE.md에 규칙이 없으면 위임이 기대만큼 발생하지 않을 수 있음(“자동 위임”이 아님)
• 서브에이전트 정의 변경 후에는 /reload-plugins가 필요

---

7. 결론

Advisor tool 전략은 “항상 비싼 모델” 대신 “어려운 결정에만 비싼 모델”을 쓰는 방식으로, 비용을 통제하면서도 품질을 끌어올리는 실전형 패턴입니다. 여기에 Sub-agents와 CLAUDE.md 오케스트레이션 규칙을 결합하면, 컨텍스트 비대화를 막고 역할 분업을 통해 개발 흐름을 안정화할 수 있습니다.

향후에는 레포/팀 표준으로 CLAUDE.md 규칙을 템플릿화해, 프로젝트 간 일관된 위임 정책과 비용 예측 가능성을 확보하는 방향이 유효합니다.

---

8. 참고 자료

• Advisor tool 문서: https://code.claude.com/docs/en/advisor
• 모델 설정(/model, opusplan): https://code.claude.com/docs/en/model-config
• 서브에이전트(Sub-agents): https://code.claude.com/docs/en/sub-agents
• 설정 파일(advisorModel 등): https://code.claude.com/docs/en/settings
• 환경변수(CLAUDE_CODE_DISABLE_ADVISOR_TOOL 등): https://code.claude.com/docs/en/env-vars
• 배경 설명 블로그(Advisor strategy): https://claude.com/blog/the-advisor-strategy