어드바이저 도구란 무엇인가
Anthropic의 문서는 이를 한 문장으로 설명합니다. "어드바이저 도구는 Claude가 접근 방식을 확정하기 전, 반복되는 오류로 막혔을 때, 또는 작업을 완료했다고 선언하기 전과 같은 작업의 핵심 순간에 일반적으로 더 강력한 두 번째 모델과 상담할 수 있게 해줍니다."
작동 방식은 세 가지 세부 사항으로 정의됩니다.
- 두 번째 모델입니다. 일상적인 작업에는 메인 모델을 유지하고, 의사 결정을 위해 어드바이저를 추가합니다.
- Anthropic 측에서 실행됩니다. 문서에 따르면 "어드바이저는 Anthropic 인프라의 서버 측에서 서버 도구로 실행되며, 구독 및 API 청구 계정 모두에서 사용할 수 있습니다."
- Claude가 사용 시점을 결정합니다. "어떤 모델이 어드바이저 역할을 할지 사용자가 선택하면, Claude가 언제 호출할지 결정합니다."
이 도구는 실험적(experimental)으로 표시되어 있습니다. Anthropic API, AWS의 Claude Platform, 또는 Google Cloud의 Claude Models(Anthropic 관리형)가 필요하며, Amazon Bedrock, Google Cloud의 Agent Platform, 또는 Microsoft Foundry를 통해서는 사용할 수 없습니다.
문서에 따르면 어드바이저는 "대부분의 턴은 일상적이지만 계획의 품질이 결과를 결정하는 길고 여러 단계로 구성된 작업"에 적합합니다. 예시로는 대규모 리팩터링, 오류가 계속 반복되는 디버깅 세션, Claude가 완료를 선언하기 전에 확인받고 싶은 작업 등이 있습니다.
어드바이저가 세션에서 확인하는 내용
이 부분은 상담이 얼마나 유용할지를 결정하는 핵심입니다.
문서는 명시적입니다. "어드바이저는 모든 도구 호출 및 결과를 포함한 전체 대화를 수신하며, Claude가 계속하기 전에 적용할 가이드를 반환합니다." 나중에는 이 점을 다시 강조합니다. "어드바이저는 항상 전체 대화를 수신하며, Claude가 타이밍을 제어합니다."
따라서 어드바이저의 시야는 세션의 대화 기록(transcript)입니다. 사용자가 무엇을 물었는지, Claude가 무엇을 읽었는지, 어떤 명령이 반환되었는지, 그리고 Claude가 지금까지 무엇을 결론지었는지를 봅니다. 문서는 별도의 브리핑에 대해 설명하지 않습니다.
이는 실질적인 결과를 초래합니다. 문서는 어드바이저의 입력을 '대화'로 설명합니다. 지난달에 팀에서 내린 결정이나 특정 모듈을 변경해서는 안 되는 이유와 같이 세션 중에 언급되지 않은 제약 조건은 어드바이저가 수신하는 내용에 포함되지 않습니다. 결정에 중요하다면 대화 내용에 포함되어야 합니다.
Claude는 또한 가이드를 판단력을 가지고 다룹니다. 문서에 따르면 "Claude는 일반적으로 어드바이저의 가이드를 따르지만, 자신의 증거가 특정 주장과 모순될 때는 이를 조정합니다." 권장된 단계가 실패하거나 파일 내용이 조언과 상충하는 경우, Claude는 조언을 맹목적으로 따르는 대신 충돌 내용을 표면화합니다.
어드바이저를 켜는 방법
문서에는 세 가지 방법이 나열되어 있으며, 선택이 유지되는 기간이 다릅니다.
/advisor 명령. 인수 없이 실행하여 목록에서 선택하거나, /advisor opus와 같이 모델을 전달합니다. 문서에 따르면 선택 사항은 "사용자 설정의 advisorModel에 저장되어 세션 간에 유지됩니다." (설정 참조에 나열된 몇 가지 예외 제외)
advisorModel 설정. 세션을 열지 않고 기본값을 구성하려면 설정 파일에서 이를 설정합니다.
--advisor 플래그. 저장된 설정을 변경하지 않고 한 세션 동안만 어드바이저를 설정하려면 claude --advisor opus로 실행합니다.
세션이 시작된 후, Claude Code는 어드바이저 도구가 켜져 있으며 더 많은 토큰을 사용할 수 있다는 알림을 표시합니다.
작동하는 모델 조합
어드바이저는 최소한 메인 모델만큼의 능력을 갖추어야 합니다. 문서에 따르면 Claude Code는 어드바이저 역할에 대해 모델의 순위를 매기며, "어드바이저는 세션의 메인 모델과 같거나 그 이상의 순위여야 합니다."
문서의 허용된 조합 표에는 다음과 같은 예시가 포함되어 있습니다.
- Sonnet 5.5가 메인 모델인 경우 Fable, Opus 5 이상, 또는 Sonnet 5.5를 어드바이저로 허용합니다.
- Opus 5 또는 Opus 5.5가 메인 모델인 경우 Fable 또는 Opus 5 이상을 허용합니다.
- Fable 5.2가 메인 모델인 경우 Fable 5.2만 허용합니다.
어드바이저는 fable, opus, sonnet과 같은 별칭(alias)이나 전체 모델 ID로 설정합니다. 문서는 별칭이 "새로운 Claude Code 릴리스와 함께 발전하는 각 모델 제품군의 Claude Code 내장 기본 버전으로 해석된다"고 언급합니다.
또한 일반적인 조합과 적합한 시기도 나열합니다. Sonnet 메인 모델과 Opus 어드바이저 조합은 Sonnet에서 일상적인 작업을 처리하고 계획, 모호한 실패, 완료 확인을 Opus로 에스컬레이션합니다. Opus 메인 모델과 Opus 어드바이저 조합은 중요한 작업에 대해 두 번째 검토를 제공합니다.
서브에이전트도 동일한 규칙을 따릅니다. 문서에 따르면 "서브에이전트는 구성된 어드바이저를 상속받으며 자신의 모델에 대해 동일한 조합 확인을 적용합니다."
Claude가 어드바이저를 호출하는 시점
사용자가 상담 일정을 잡는 것이 아닙니다. 문서에 따르면 Claude는 "접근 방식을 확정하기 전, 오류가 계속 반복될 때, 작업을 완료했다고 선언하기 전에 상담하는 경향이 있지만, 타이밍은 규칙 기반이 아니라 모델에 의해 주도됩니다."
여전히 영향을 줄 수는 있습니다. 프롬프트에서 상담을 요청할 수 있으며, 문서의 예시는 Claude에게 계속하기 전에 어드바이저와 상담하라고 지시하는 것입니다. 빈도에 대해 문서는 다음과 같이 덧붙입니다. "어드바이저 호출을 제한하거나 강제하는 설정은 없습니다. 작업 중에 Claude가 더 자주 또는 덜 자주 상담하기를 원한다면 지침에 그렇게 명시하십시오."
세션 중에 상담은 어드바이저 모델 이름과 함께 'Advising' 라인으로 표시됩니다. 상담이 완료되면 라인에 다음 세 가지 결과 중 하나가 표시됩니다.
- Reviewed: 어드바이저가 대화를 검토했습니다.
Ctrl+O를 눌러 가이드를 읽으세요. - Declined: 어드바이저가 요청에 대한 조언을 거부했습니다.
Ctrl+O를 눌러 이유를 확인하세요. - Unavailable: 호출이 실패했으며 라인에 오류 코드가 표시됩니다.
왜 매 호출마다 전체 대화 기록을 다시 읽는가
어드바이저가 세션을 바라보는 시각은 매번 새롭습니다. 프롬프트 캐싱에 관한 문서 섹션에서 이를 설명합니다.
메인 모델에 미치는 영향은 적습니다. "세션 중간에 어드바이저를 활성화하거나 비활성화해도 메인 모델의 프롬프트 캐시가 무효화되지 않습니다." 그리고 가이드 자체도 기록의 일부가 됩니다. "어드바이저가 반환한 가이드는 이후 턴에서 대화 기록의 일부로 캐시됩니다."
어드바이저 측에서는 아무것도 이월되지 않습니다. "어드바이저 모델이 대화를 읽은 내용은 캐시되지 않습니다. 각 어드바이저 호출은 호출 간의 재사용 없이 전체 대화 기록을 새로 처리합니다."
두 가지 결과가 뒤따릅니다.
- 세션이 길어질수록 각 상담의 규모가 커집니다. 어드바이저는 매번 전체 대화를 읽으므로, 긴 세션의 후반부 호출은 초반부 호출보다 더 많은 내용을 처리합니다.
- 어드바이저 측의 호출 간에는 재사용되는 것이 없습니다. 한 호출과 다음 호출을 연결하는 것은 이전에 반환된 가이드를 포함하는 대화 기록뿐입니다.
이것이 어드바이저를 켜는 것이 모델을 전환하는 것과 다른 이유이기도 합니다. 문서는 두 가지를 직접 대조합니다. 모델 전환과 달리 /advisor를 토글하는 것은 캐시된 접두사(prefix)를 그대로 유지합니다. 모델 전환이 세션의 캐시와 컨텍스트에 미치는 영향은 Claude Code 세션 중간에 모델 전환하기 가이드에서 다루었습니다.
비용
어드바이저는 대화를 읽으므로, 각 호출은 메인 모델 사용량 외에 어드바이저 모델의 요율로 토큰을 사용합니다. API 청구 방식에서는 어드바이저 모델의 입력 및 출력 요율을 지불합니다. 구독 플랜에서 어드바이저 사용량은 플랜의 사용 한도에 포함되며, Fable 어드바이저가 사용 크레딧으로 청구되는 플랜의 경우 별도의 규칙이 적용됩니다.
이러한 설계에 대한 문서의 논거는 Claude가 "매 턴이 아니라 결정 시점에" 어드바이저를 호출하므로, 더 빠른 메인 모델과 더 강력한 어드바이저를 사용하는 것이 일반적으로 강력한 모델을 계속 실행하는 것보다 비용이 적게 든다는 것입니다. 어드바이저 사용량은 /usage로 표시되는 세션 합계에 나타납니다.
Claude Code가 알림 없이 어드바이저를 중단하는 경우
이것이 서두의 예시에서 나타난 동작이며, 문서는 여러 사례를 설명합니다.
API가 조합을 거부함. "Claude Code가 첨부한 어드바이저 조합을 API가 거부하면, Claude Code는 어드바이저 없이 해당 요청을 다시 보냅니다. 대화는 어드바이저 없이 계속되므로 오류가 표시되지 않으며 어드바이저 호출도 발생하지 않습니다." 이후 /advisor로 다른 어드바이저를 선택하면, 문서에 따르면 /clear 또는 /compact 이후 및 새 세션에서 적용됩니다.
어드바이저 순위가 메인 모델보다 낮음. Claude Code는 메인 모델의 요청에 이를 첨부하지 않습니다. /advisor 출력과 알림이 이를 보여줍니다.
저장된 어드바이저가 현재 메인 모델을 지원하지 않음. 문서에 따르면 "Claude Code는 현재 메인 모델이 지원하지 않는 어드바이저라도 여전히 저장합니다. 해당 어드바이저는 /model을 통해 호환되는 메인 모델로 전환한 후에 활성화됩니다." 여기에 주의 사항이 추가됩니다. "현재 대화에서 API가 이미 저장된 어드바이저를 거부했다면, 모델을 전환하더라도 /clear 또는 /compact 전까지는 꺼진 상태로 유지됩니다."
모델이 인식되지 않음. "메인 모델이나 어드바이저가 Claude Code가 인식하지 못하는 모델인 경우 어드바이저는 첨부되지 않습니다."
조직에서 모델을 제한함. Claude Code는 조직의 availableModels 허용 목록에서 제외된 저장된 어드바이저를 호출하지 않습니다.
기능 플래그가 꺼져 있음. AWS의 Claude Platform 및 Google Cloud의 Claude Models(Anthropic 관리형) 외에, 어드바이저는 Anthropic에서 가져온 기능 플래그가 필요합니다. DISABLE_TELEMETRY와 같이 가져오기를 끄는 변수가 있는 세션에는 이 기능이 없습니다.
각 사례의 패턴은 동일합니다. 세션은 상담 없이 계속 작동할 뿐입니다. 어드바이저에 의존한다면 긴 작업 중에 'Advising' 라인이 있는지 확인하고, /advisor를 실행하여 무엇이 설정되어 있는지 확인하십시오.
어드바이저와 다른 옵션 비교
문서는 더 강력한 모델을 도입하는 네 가지 방법을 비교합니다.
- 어드바이저 도구: 작업 중간의 결정 시점에 Claude가 호출할 때.
opusplan: 계획 모드 동안 사용하고, 실행은 Sonnet으로 할 때.- 모델이 설정된 서브에이전트: 위임된 하위 작업 전체에 대해.
/model: 전환한 시점의 다음 요청부터 계속해서.
어드바이저는 Claude가 선택한 순간에 강력한 모델이 전체 대화를 검토하는 유일한 방법입니다. 다른 방법들은 작업의 일부를 넘기거나 이후의 모든 작업에 대해 모델을 변경합니다.
어드바이저를 끄는 방법
/advisor off를 실행하거나 선택기에서 'No advisor'를 선택합니다. 도구를 완전히 비활성화하려면 CLAUDE_CODE_DISABLE_ADVISOR_TOOL=1을 설정합니다. 문서에 따르면 이 경우 /advisor 명령을 사용할 수 없게 되며 구성된 모든 advisorModel은 무시됩니다.
사람들이 흔히 겪는 실수
어드바이저가 작동을 멈췄을 때 오류를 예상함. Claude Code는 오류 없이 어드바이저를 제외하고 다시 보냅니다.
어드바이저가 프로젝트 이력을 알고 있다고 가정함. 어드바이저는 현재 대화 내용만 수신합니다.
거부된 후 대화 중간에 어드바이저를 변경함. 새로운 선택은 /clear 또는 /compact 이후에 적용됩니다.
메인 모델보다 약한 어드바이저를 선택함. 메인 모델과 같거나 그 이상의 순위여야 합니다.
상담을 강제하는 설정을 찾음. 그런 설정은 없습니다. 지침(instructions)에서 요청하십시오.
해결 방법: 어드바이저에게 필요한 정보 제공하기
1단계: 조합 확인
/advisor를 실행하여 어드바이저 순위가 메인 모델과 같거나 높은지 확인합니다.
2단계: Advising 라인 주시
긴 작업에서 상담이 여전히 나타나는지 확인하고, Ctrl+O로 가이드를 읽으십시오.
3단계: 핵심 제약 조건을 대화에 포함
중요한 결정을 내리기 전에 중요한 제약 조건을 언급하여 어드바이저가 읽는 내용의 일부가 되도록 하십시오.
4단계: 제약 조건 기록 유지
모든 검토에 영향을 미쳐야 하는 결정과 제한 사항을 기록하여 어떤 세션에서든 가져올 수 있도록 하십시오.
MemoryLake에서 설정하기
어드바이저는 대화에 포함된 내용을 검토합니다. 종속성을 업그레이드할 수 없는 이유, 지난 분기에 실패한 접근 방식, 또는 교체 중인 모듈과 같이 검토에 영향을 미쳐야 하는 결정들은 단일 세션 외부에 존재할 수 있는 프로젝트 컨텍스트입니다.
MemoryLake는 이러한 종류의 프로젝트 컨텍스트(결정, 제약 조건 및 그 이면의 이유)를 위한 기억 레이어입니다. 사용자가 관리하는 한 곳에 보관되며 ChatGPT, Claude Code, Codex 등 연결된 어시스턴트에서 사용할 수 있습니다.
항목은 사용자가 직접 자신의 언어로 작성합니다. Claude Code 세션, 대화 기록, 설정 파일, 어드바이저의 가이드 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다. 어드바이저 도구는 Anthropic이 설명한 방식 그대로 작동합니다.
1단계: API 키 생성
로그인하고 대시보드에서 키를 생성합니다. 다른 자격 증명과 마찬가지로 리포지토리 외부에 저장하십시오.

2단계: 첫 번째 기억 업로드
해결 방법의 4단계에서 작성한 내용, 즉 모든 검토가 준수해야 하는 제약 조건부터 시작하십시오. 항목당 하나의 결정을 담습니다.

3단계: AI 및 에이전트 연결
Claude Code, Codex 및 사용하는 다른 어시스턴트를 연결합니다. 중요한 결정을 내리기 전에 동일한 제약 조건을 모든 세션에 가져올 수 있습니다.

실제적인 변화
첫 번째 차이점은 더 풍부한 정보에 기반한 검토입니다. 중요한 제약 조건이 어드바이저가 읽는 대화 내용에 포함됩니다.
두 번째는 세션 간의 일관성입니다. 각 새로운 세션은 동일한 결정 사항을 가지고 시작할 수 있습니다.
세 번째는 도구 간의 일관성입니다. Claude Code와 다른 어시스턴트에서 동일한 컨텍스트를 사용할 수 있습니다.
어드바이저 도구 모범 사례
길고 결정이 중요한 작업에 사용하십시오. 짧은 작업에는 큰 이득이 없습니다.
빠른 메인 모델과 강력한 어드바이저를 조합하십시오. 이는 문서에서 강력한 모델을 계속 실행하는 것보다 일반적으로 저렴하다고 설명하는 조합입니다.
모델 변경 후 조합을 확인하십시오. 어드바이저는 메인 모델과 같거나 그 이상의 순위여야 합니다.
침묵을 주의하십시오. 'Advising' 라인이 없다는 것은 어드바이저가 중단되었음을 의미할 수 있습니다.
어드바이저 변경 후 /clear 또는 /compact를 사용하십시오. 거부된 어드바이저는 그 전까지 꺼진 상태로 유지됩니다.
중요한 결정 전에 제약 조건을 명시하십시오. 어드바이저는 대화를 읽습니다.
프롬프트에서 상담을 요청하십시오. 상담을 강제하는 설정은 없습니다.
결론
어드바이저 도구는 Claude가 접근 방식을 확정하기 전, 오류가 반복될 때, 또는 작업을 완료했다고 선언하기 전과 같은 핵심 순간에 더 강력한 모델과 상담할 수 있게 해줍니다. 어드바이저는 매번 전체 대화를 수신하며 자체 읽기 내용은 캐시되지 않으므로, 모든 호출은 전체 대화 기록을 다시 처리합니다. 이를 켜거나 꺼도 메인 모델의 프롬프트 캐시는 무효화되지 않으며, 가이드는 대화 기록의 일부가 됩니다.
Claude Code는 여러 경우에 어드바이저 사용을 중단하며, API가 조합을 거부할 때는 오류 없이 중단합니다. 조합을 확인하고, 'Advising' 라인을 주시하며, 중요한 제약 조건을 대화에 포함시켜 어드바이저의 검토가 실제로 알아야 할 내용을 바탕으로 이루어지도록 하십시오.