클로드 코드 opusplan과 하이쿠 서브에이전트로 모델 나눠 쓰는 설정법 (탐색 서브에이전트는 따로 바꿔야 한다)

클로드 코드(Claude Code)에서 계획은 오퍼스(Opus) 5.5, 코드 작성은 소네트(Sonnet) 5.5, 서브에이전트는 하이쿠(Haiku) 5.5에 맡기는 설정이다.

X에서 "앤트로픽이 문서로 정리한 조합"으로 퍼진 글은 아래 한 줄로 시작하라고 한다.

CLAUDE_CODE_SUBAGENT_MODEL=haiku claude --model opusplan

opusplan은 문서에 있는 실제 별칭이다. 플랜 모드에서는 opus로, 실행할 때는 sonnet으로 바뀐다. 다만 글의 설명 세 군데가 문서와 다르다.

• 저장소 검색이 하이쿠로 돌지 않는다. 클로드 구독이나 콘솔 계정에서 기본 탐색 서브에이전트 Explore는 오퍼스로 돈다. CLAUDE_CODE_SUBAGENT_MODEL만 넣으면 Explore와 Plan 서브에이전트의 모델은 그대로다.
• 오퍼스가 "같은 테스트가 두 번 실패할 때"나 "끝내기 전 diff를 검토할 때" 끼어드는 기능은 없다. opusplan은 플랜 모드인지 아닌지만 보고 모델을 바꾼다. 작업 도중 오퍼스에 묻게 하려면 어드바이저(/advisor opus)를 따로 켠다.
• fallbackModel이 세션을 100% 지켜 주지는 않는다. 모델이 과부하이거나 쓸 수 없을 때만 다음 모델로 넘어가고, 사용량 한도(rate limit)·인증·결제 오류에서는 바꾸지 않는다.

서브에이전트까지 전부 하이쿠로 돌리려면 설정 파일에 아래처럼 넣는다(v2.1.257 이상, 하이쿠 5.5는 v2.1.293 이상).

// ~/.claude/settings.json
{
  "model": "opusplan",
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  },
  "fallbackModel": ["sonnet", "haiku"]
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE가 없으면 Explore·Plan과 정의에 model을 따로 적은 서브에이전트는 원래 모델로 돈다. 탐색만 하이쿠로 돌리려면 FORCE 대신 model: haiku를 적은 Explore 서브에이전트를 직접 만든다.

하이쿠 5.5는 기본으로 100만 토큰 창을 쓰지만 프롬프트가 10만 토큰을 넘으면 요금이 더 비싸다. 서브에이전트가 어느 모델로 도는지는 /tasks를 열면 줄마다 나온다.