블로그로 돌아가기
Claude Code Advisor 기능 완전 분석: Opus가 Sonnet을 지휘하는 새로운 패러다임

Claude Code Advisor 기능 완전 분석: Opus가 Sonnet을 지휘하는 새로운 패러다임

7분 읽기0

Claude Code Advisor 기능 완전 분석: Opus가 Sonnet을 지휘하는 새로운 패러다임

비유로 먼저 설명드리겠습니다. 건설 현장을 떠올려 보세요. 기능공(Executor)이 대부분의 벽돌을 쌓지만, 구조적으로 중요한 접합부에서는 수석 엔지니어(Advisor)가 잠깐 내려와 설계도를 확인해 줍니다. Claude Code의 Advisor 기능은 바로 이 현장 감리 패턴을 API 한 번의 요청 안으로 내장한 것입니다.

Anthropic이 2026년 4월 9일 공개한 Advisor Strategy는 단순한 기능 추가가 아니라 에이전트 아키텍처의 구조적 전환입니다. 이번 글에서는 이 기능이 왜 중요한지, 실무에서 어떻게 쓰는지, 그리고 1인 개발자와 소규모 팀 관점에서의 적용 지점을 정리해 드립니다.

Advisor 기능이란 무엇인가

Advisor 기능은 Executor-Advisor 2단계 모델 협업 패턴입니다. 빠르고 저렴한 Executor 모델(Haiku 4.5, Sonnet 4.6)이 작업 대부분을 주도하고, 구조적 판단이 필요한 순간에만 고성능 Advisor 모델(Opus 4.7)에게 계획·수정·중단 신호를 받습니다.

핵심은 이것이 단일 /v1/messages 요청 내부에서 서버사이드로 처리된다는 점입니다. 기존 오케스트레이션 방식은 개발자가 직접 여러 요청을 조율해야 했지만, Advisor는 Anthropic 서버가 컨텍스트 전달과 응답 통합을 대신 해줍니다.

항목ExecutorAdvisor
역할도구 호출, 코드 작성, 사용자 응답가이드 제공 (도구 호출·사용자 응답 없음)
모델 후보Haiku 4.5, Sonnet 4.6, Opus 4.6, Opus 4.7Opus 4.7 (항상 executor보다 강해야 함)
Extended thinking선택적항상 사용 (thinking block은 결과 비포함)
호출 비용기본 토큰 과금usage.iterations[] 배열로 분리 보고

공개된 벤치마크: 품질은 오르고 비용은 내려간다

Anthropic이 공식 블로그에서 공개한 수치는 이 패턴의 가치를 직관적으로 보여줍니다.

SWE-bench Multilingual (실제 코딩 태스크)

  • Sonnet 4.6 단독: 72.1%
  • Sonnet 4.6 + Opus Advisor: 74.8% (+2.7%p)
  • 비용: 11.9% 절감

품질이 올라가면서 동시에 비용이 내려간다는 점이 반직관적이지만 실제 측정된 결과입니다. 이유는 Advisor가 잘못된 방향으로 돌아가는 시간을 줄여주기 때문입니다.

BrowseComp (웹 리서치 태스크)

  • Haiku 4.5 단독: 19.7%
  • Haiku 4.5 + Opus Advisor: 41.2% (2배 이상)
  • 비용: Sonnet 단독 대비 85% 저렴

이 조합이 가장 극적입니다. 속도는 Haiku 수준, 판단력은 Opus 수준, 가격은 Sonnet보다도 싼 조합이 현실에서 가능해졌습니다.

Terminal-Bench 2.0

터미널 기반 에이전트 벤치마크에서도 유의미한 개선이 확인됐습니다(구체 수치는 공식 블로그 참조).

기술 아키텍처: 요청이 내부에서 어떻게 흐르는가

API 레벨에서 Advisor는 다른 도구(web_search, code execution)와 동일한 tools 배열의 엔트리입니다. 다만 실행 흐름이 특수합니다.

  1. Executor가 server_tool_use 블록을 발행합니다 (name="advisor", input={}).
  2. Anthropic 서버가 현재 컨텍스트를 Advisor 모델에게 전달합니다.
  3. Advisor가 extended thinking을 거쳐 가이드를 생성합니다.
  4. advisor_tool_result 블록이 Executor 응답 스트림에 삽입됩니다.
  5. Executor가 해당 가이드를 참고하여 작업을 이어갑니다.

호출당 토큰 사용량은 텍스트 400-700 토큰, thinking 포함 시 1,400-1,800 토큰 수준입니다. 스트리밍 중 Advisor 호출이 발생하면 Executor 스트림은 일시 정지되고 30초 간격 SSE ping만 전송됩니다.

두 가지 활성화 경로

1. Claude Code 사용자: /advisor 한 번

CLI 또는 터미널에서 Claude Code를 사용 중이라면 슬래시 커맨드 한 번으로 끝납니다.

/advisor

토글이 켜지면 이후 모든 에이전트 루프에서 Advisor 전략이 자동 적용됩니다. 별도 설정 파일 수정이나 환경 변수 조정이 필요 없습니다.

2. API 직접 사용자: 베타 헤더 + 도구 선언

Python SDK 기준 최소 설정은 다음과 같습니다.

from anthropic import Anthropic

client = Anthropic()

response = client.messages.create(
    model="claude-sonnet-4-6",  # Executor
    max_tokens=4096,
    tools=[
        {
            "type": "advisor_20260301",
            "model": "claude-opus-4-7",  # Advisor
            "max_uses": 10,
            "caching": {"type": "ephemeral", "ttl": "5m"}
        }
    ],
    extra_headers={
        "anthropic-beta": "advisor-tool-2026-03-01"
    },
    messages=[
        {"role": "user", "content": "리팩토링 대상 코드베이스를 분석하고 개선안을 구현하세요."}
    ]
)

cURL 사용자를 위한 예제도 함께 드립니다.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: advisor-tool-2026-03-01" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-sonnet-4-6",
    "max_tokens": 4096,
    "tools": [{
      "type": "advisor_20260301",
      "model": "claude-opus-4-7",
      "max_uses": 10
    }],
    "messages": [{"role": "user", "content": "..."}]
  }'

언제 Advisor를 호출해야 하는가

Anthropic 공식 프롬프팅 가이드는 다음 네 가지 순간을 권장합니다.

  1. 중요한 작업을 시작하기 전 — 글을 쓰기 전, 해석을 확정하기 전, 가정 위에 구축하기 전
  2. 작업이 완료된 것 같을 때 — 단, 먼저 산출물을 안정적으로 저장해 둔 뒤 호출
  3. 막혔을 때 — 같은 에러가 반복되거나 접근이 수렴하지 않을 때
  4. 접근 방식을 바꿀지 고민될 때

역으로 말하면, 이 순간이 아닌 기계적인 작업(파일 읽기, 단순 변환, 포맷 맞추기)은 Executor가 단독으로 처리해야 비용 효율이 살아납니다.

비용 절감 팁: 트리밍 지시어

시스템 프롬프트에 다음 한 줄을 추가하면 Advisor 토큰 사용량을 35-45% 줄일 수 있습니다(Anthropic 공식 수치).

The advisor should respond in under 100 words and use enumerated steps, not explanations.

실측 결과 품질 저하는 유의미하지 않았고, 오히려 Executor가 Advisor 응답을 빠르게 소화하는 부수 효과가 있었습니다. max_uses 파라미터로 요청당 호출 횟수 상한을 걸어 두는 것도 예산 관리에 유용합니다.

실제 고객 사례

Anthropic이 공개한 초기 도입 사례는 이 패턴의 실용성을 입증합니다.

  • Bolt (Eric Simmons, CEO): "복잡한 작업의 아키텍처 결정이 눈에 띄게 좋아졌다. 계획과 궤적이 완전히 다르다."
  • Genspark (Kay Zhu, CTO): "자체 제작한 planning tool보다 더 좋은 개선을 확인했다."
  • Eve Legal (Anuraj Pandey, ML Engineer): "구조화 문서 추출 작업에서 Haiku 4.5가 Opus 4.6 자문을 받아 프론티어 품질을 5배 저렴한 가격으로 달성했다."

1인 기업과 소규모 팀 관점의 적용 지점

QJC(퀀텀점프클럽)처럼 소규모로 자동화 스택을 운영하는 팀에게 Advisor는 세 가지 지점에서 가치가 있습니다.

  1. 장기 리서치 파이프라인 — /research 같은 커맨드가 멀티스텝으로 돌아갈 때, Executor가 10단계 중 8단계를 처리하고 Advisor는 해석·교차검증 순간에만 개입합니다.
  2. 복잡 코드 에이전트 — 리팩토링, 마이그레이션처럼 판단이 개입되는 작업에서 Opus 단독 비용 부담을 크게 낮춥니다.
  3. Computer Use 에이전트 — 브라우저 자동화 중 UI 판단이 애매할 때 Advisor가 잠깐 올라와 결정을 돕습니다.

반대로 Advisor가 맞지 않는 워크로드도 분명합니다. 단일 턴 Q&A, 모델 선택기, 매 턴 최고 지능이 필요한 커스텀 모델 라우터에는 오히려 오버헤드가 됩니다.

에러 코드 빠른 참조

  • max_uses_exceeded: max_uses 값 상향 또는 Executor 프롬프트에서 호출 빈도 조정
  • overloaded: Advisor 모델 용량 문제, 재시도 또는 다른 모델로 폴백
  • prompt_too_long: Executor 컨텍스트 과다, 캐싱 활용 또는 분할

맺으며: 모델 선택 문제의 구조적 해결

Advisor는 "어떤 모델을 쓸까?"라는 오랜 딜레마를 정면으로 해결합니다. Opus의 판단력을 원하지만 비용이 부담스러웠던 사용자, Haiku의 속도가 좋았지만 품질이 아쉬웠던 사용자 모두에게 중간 지대를 없애 줍니다.

이번 주 Claude Code를 열어 /advisor 한 번만 눌러 보시면 왜 이 기능이 "판을 바꾼다"고 평가받는지 바로 체감하실 수 있습니다.

© 퀀텀점프클럽 정상록 참고: Anthropic 공식 블로그 — The Advisor Strategy