claude code 서브에이전트 모델 설정 — 199개를 재 보니 모델을 정한 건 호출 한 줄이었다

서브에이전트Claude Code모델mod운영

claude code 서브에이전트의 모델은 네 단계 순서로 정해집니다.

그리고 모델을 정한 것은 거의 언제나 첫 단계였습니다.

순서 어디서 정하나
1 호출할 때 넘기는 model
2 에이전트 파일의 model:
3 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL
4 메인 대화의 모델

30일 동안 띄운 서브에이전트를 셌습니다.

무엇이 모델을 정했나 개수
1단계, 호출의 model 191
아무도 안 정해서 기본값 4
합계 195

비율로는 98%.

역할마다 모델을 나누는 일은 호출 한 줄이 했습니다.

그 한 줄을 매번 쓰게 만든 것은 규칙 두 문장이었습니다.

저희는 이걸 모르고 mod 를 먼저 만들었습니다.

아래는 공식 순서가 어떻게 동작하는지, 실제로 무엇이 골랐는지, mod 가 왜 필요 없었는지입니다.

환경

  • Claude Code 2.1.291 에서 mod 를 만들었고, 이 글은 2.1.318 에서 씁니다
  • 메인 모델은 Fable 5.1 과 Opus 5.5 를 오갔습니다. 서브에이전트에는 Sonnet, Haiku 까지 넷을 씁니다
  • 기간은 2026년 10월 11일부터 11월 9일까지 30일입니다. 서브에이전트 199개, 그 부모 세션은 셋입니다
  • 셈은 세션 기록 폴더의 subagents/*.meta.json 과 같은 이름의 대화 기록에서 했습니다. 명령은 글 끝에 있습니다

서브에이전트 모델은 어떻게 정해지나?

공식 문서의 순서가 위 표 그대로입니다.

위 단계가 정하면 아래 단계는 안 봅니다.

① 호출의 model Claude가 서브에이전트를 띄울 때 Agent 도구에 넘기는 값입니다. 별칭만 받습니다. sonnet, opus, haiku, fable 넷입니다.

② 에이전트 파일의 model: .claude/agents/ 아래 정의 파일의 머리말입니다. 별칭, 전체 모델 ID, inherit 를 받습니다. inherit 는 메인 대화의 모델을 따른다는 뜻입니다.

③ CLAUDE_CODE_SUBAGENT_MODEL 이 변수는 기본값입니다. 위 두 단계가 정하면 지고, 아무도 안 정했을 때만 씁니다. 2.1.251 전에는 반대로 이 변수가 가장 셌습니다. 오래된 글이 이 변수를 강제 설정처럼 설명하는 이유입니다.

④ 메인 대화의 모델 아무도 안 정하면 메인을 따릅니다.

모두 한 모델로 묶고 싶으면 2.1.257 부터 있는 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 를 같이 켭니다.

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

켜 두면 에이전트 파일의 model 도 무시되고 Claude가 호출에 모델을 넘길 수도 없습니다.

용도는 비용 상한.

내장 에이전트는 따로 논다

내장 Explore 와 Plan 은 ③을 안 봅니다. 그리고 Explore 에는 예외가 하나 있습니다.

내장 에이전트 아무도 안 정했을 때
general-purpose ③이 있으면 그것, 없으면 메인
Plan 메인
Explore 메인. 단, 메인이 Fable 이면 Opus
claude-code-guide Haiku

저희 기록의 기본값 4개가 이 표 그대로 돌았습니다.

에이전트 그때 메인 실제로 돈 모델
Explore Fable 5.1 Opus 5.5 (2개)
claude-code-guide Fable 5.1 Haiku 4.5
general-purpose Opus 5.5 Opus 5.5

내장 에이전트의 기본 모델만 바꾸는 설정 키는 없습니다. 대신 같은 이름의 에이전트 파일을 만들면 내장을 덮습니다. 문서의 예가 Explore 라는 이름의 파일에 model: haiku 를 적는 것입니다.

실제로 무엇이 모델을 골랐나?

호출에서 정한 191개를 모델별로 나누면 이렇습니다.

모델 개수
Sonnet 98
Opus 72
Haiku 13
Fable 8

절반 남짓이 Sonnet.

넘긴 모델과 응답한 모델이 어긋난 경우는 없었습니다.

역할로 나누면 무엇을 어디에 썼는지가 보입니다. 역할은 호출에 붙은 설명 문구로 갈랐습니다.

역할 Fable Opus Sonnet Haiku
브랜치 전체 마지막 리뷰 (10) 8 2 0 0
작업 단위 리뷰와 재리뷰 (117) 0 53 57 7
구현과 수정 (61) 0 15 40 6

가장 비싼 모델은 브랜치를 닫기 전 마지막 리뷰에만 갔습니다.

구현은 Sonnet 이 셋 중 둘을 맡았습니다.

그 한 줄은 누가 쓰게 했나?

설정은 하나도 안 썼습니다.

컨텍스트에 늘 실리는 규칙 두 개가 했습니다.

① 스킬의 규칙 작업을 서브에이전트로 쪼개 돌리는 superpowers 스킬의 모델 선택 절이 이렇게 끝납니다.

“Always specify the model explicitly when dispatching a subagent.”

이유도 적혀 있습니다. 모델을 빼면 메인 모델을 물려받는데, 그게 대개 가장 비싸다는 것입니다. 이 스킬로 돈 작업에서는 Claude가 매번 모델을 골라 넘겼습니다.

② 운영자의 배정 규칙 10월 11일에 운영자가 정한 배정입니다. 운영자의 말을 그대로 옮기면 이렇습니다.

“빠른 개발이 아니라 성공적인 개발이 목표니까 깊은 추론이 필요하다면 fable을 사용해도 돼. 간단한 질문에는 sonnet이나 그 이하 모델을 사용해도 되고”

이 말을 Claude가 세션마다 읽는 메모리에 남겼습니다. 깊은 검증과 마지막 리뷰는 Fable, 구현과 설계는 Opus, 탐색과 대조는 Sonnet 이하라는 배정입니다.

둘 다 설정 파일이 아니라 Claude가 읽는 문장입니다. Claude가 그 문장을 읽고 호출마다 1단계를 채웠습니다.

설정만으로 안 되는 것이 둘 있었다

10월 11일, 저희는 공식 설정으로 안 되는 것 둘을 찾았습니다.

① 내장 에이전트마다 다른 기본값 general-purpose 는 Opus, Explore 는 Sonnet 처럼 나누는 설정 키가 없습니다. ③은 하나의 값이고 Explore 와 Plan 은 그마저 안 봅니다.

② 한도에 걸렸을 때 다른 모델로 넘기기 내장 fallbackModel 은 과부하나 서버 오류에만 넘어갑니다. 문서는 rate limit 오류를 넘기지 않는 쪽에 둡니다. 넘어가도 그 턴만입니다.

그래서 mod 를 만들었습니다.

mod 는 Claude Code 안에서 이벤트를 가로채 동작을 바꾸는 TypeScript 플러그인입니다.

이벤트 mod 가 한 일
agent.spawn 모델 없이 뜨는 내장 에이전트에 역할 모델을 넣는다
turn.step Fable 요청이 실패하면 같은 턴에서 Opus 로 다시 보낸다
turn.step 두 번 연속 실패하면 세션 모델을 Opus 로 바꾼다
turn.start 한도 창이 리셋되면 Fable 로 되돌린다

코드 252줄, 테스트 23개.

만들면서 알게 된 엔진의 동작이 다섯 개 있습니다. 문서만으로는 알 수 없던 것들입니다.

관찰 의미
실패한 요청이 예외가 아니라 결과로 온다 stopReason 과 usage 가 둘 다 비어 있으면 실패다
next() 를 다시 부르면 재전송된다 같은 턴 안에서 재시도할 수 있다
turn.step 의 model 은 별칭을 거부한다 opus 가 아니라 전체 모델 ID 를 넣어야 한다
classic.StopFailure 는 턴이 끝난 뒤에 온다 그 턴 안의 판단에는 못 쓴다
$.config.set 으로 바꾼 모델은 설정 파일에 남는다 되돌리지 않으면 다음 세션 기본값이 바뀐다

마지막 줄은 밟았습니다.

시험 중에 기본 모델이 Haiku 로 바뀌어 손으로 되돌렸습니다.

안 된 것

mod 는 테스트를 다 통과했고, 만든 세션에서는 동작했습니다. 그 세션에서 모델 없이 띄운 Explore 가 Sonnet 으로 돌았습니다. 문제는 그 밖이었습니다.

① mod 는 만든 세션에서만 로드됐다 세션 안에서 만든 mod 는 ~/.claude/dev-mods/<세션 ID>/ 아래 생깁니다. 이 폴더는 그 세션이 다시 열릴 때만 로드됩니다. 다른 세션에서 쓰려면 CLAUDE_CODE_PLUGIN_DIRS 에 경로를 넣거나 플러그인으로 설치해야 합니다.

만든 세션은 그 갈림길을 운영자에게 물었습니다.

다른 일로 넘어가면서 답이 정해지지 않았습니다.

세션 mod 로드 기록 서브에이전트
mod 를 만든 세션 있음 4
나머지 두 세션 없음 195

로드 기록은 대화 기록에 남는 loaded 줄로 셌습니다. 기록이 남은 메인 세션 31개 중 그 줄이 나온 것은 하나입니다. 앞의 기본값 4개가 공식 표대로 돈 것도 같은 이유입니다. mod 가 있었다면 Explore 는 Sonnet 이었습니다.

꺼져 있었는데 30일 동안 아무도 몰랐습니다.

1단계가 이미 채워지고 있었기 때문입니다.

② 폴백은 세션 한도를 못 넘는다 mod 를 만든 뒤 한도에 두 번 걸렸습니다.

날짜 메시지 재개
10월 14일 11:52 You’ve hit your session limit 12:21, 리셋 직후
11월 4일 10:28 You’ve hit your session limit 12:01, 리셋 직후

두 번 다 리셋까지 대기.

그 세션에는 mod 가 없었습니다. 있었어도 못 살렸습니다.

걸린 것이 Fable 의 한도가 아니라 세션 한도이고, 세션 한도는 모델이 같이 씁니다. Opus 로 넘겨도 같은 벽입니다. mod 를 만든 날의 메모에도 그렇게 적혀 있었습니다. 저희는 그 줄을 쓰고도 만들었습니다.

모델마다 따로 걸리는 한도에서는 이 폴백이 의미가 있을 수 있습니다. 저희 기록에는 그런 경우가 없습니다.

그래서 지금 권하는 설정

mod 의 두 기능 중 하나는 공식 길로 대신할 수 있고, 하나는 대신할 필요가 없었습니다.

역할마다 모델을 나누려면 Claude가 호출할 때 모델을 넘기게 합니다. CLAUDE.md 에 이런 한 줄이면 됩니다.

서브에이전트를 띄울 때는 model 을 항상 지정한다.
구현은 sonnet, 설계와 리뷰는 opus, 마지막 리뷰만 fable.

같은 역할을 자주 띄우면 에이전트 파일을 만들고 model: 을 적습니다. 내장 이름으로 만들면 내장 에이전트의 기본값도 바뀝니다.

---
name: Explore
description: 코드베이스 탐색
model: sonnet
---

비용 상한이 목적이면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 로 전부 묶습니다.

한도에 걸리면 세션 한도라면 모델을 바꿔도 소용없습니다. 리셋을 기다리거나 작업을 원장과 메모리에 적어 두고 끊는 쪽이 낫습니다. 저희는 두 번 다 그렇게 이어 갔습니다.

이 글을 쓰는 시점에 mod 는 폴더에 그대로 있고 어디에도 연결돼 있지 않습니다.

남는 것

서브에이전트 모델은 호출이 정한다. 네 단계 중 첫 단계가 195개 중 191개를 정했습니다. 설정은 아무도 안 정했을 때의 기본값입니다.

호출을 바꾸는 것은 문장이다. 스킬 한 줄과 배정 규칙 한 문단이 매 호출의 모델을 골랐습니다. Claude가 읽는 곳에 적으면 됩니다.

세션에서 만든 mod 는 그 세션의 것이다. 다른 세션에 붙이는 단계를 따로 밟아야 합니다. 안 붙어 있어도 아무 경고가 없습니다.

한도는 모델 공용인지부터 본다. 폴백을 만들기 전에 걸리는 한도가 무엇인지 메시지를 확인합니다. 저희는 메모에 적고도 만들었습니다.


세션 기록이 있는 머신이면 누구나 같은 셈을 할 수 있습니다.

# 서브에이전트마다 종류와 호출에서 넘긴 모델 — 없으면 null
cat ~/.claude/projects/*/*/subagents/*.meta.json | grep -o '"agentType":"[^"]*"\|"model":"[^"]*"' | sort | uniq -c
# 실제로 응답한 모델
cat ~/.claude/projects/*/*/subagents/*.jsonl | grep -o '"model":"claude-[a-z0-9-]*' | sort | uniq -c
# 세션 안에서 만든 mod 가 로드된 기록
grep -rhoE '[a-z-]+: (re)?loaded (from this session|\(new in)' ~/.claude/projects | sort | uniq -c
# 한도에 걸린 기록
grep -rho 'hit your session limit[^"]*' ~/.claude/projects | sort | uniq -c

자주 묻는 질문

Q. CLAUDE_CODE_SUBAGENT_MODEL 을 sonnet 으로 했는데 에이전트가 opus 로 돌아요

변수보다 위 단계가 정했기 때문입니다.

호출에 model 이 있거나 에이전트 파일에 model: 이 있으면 변수는 안 봅니다. 내장 Explore 와 Plan 은 변수를 아예 안 봅니다. 모두 묶으려면 CLAUDE_CODE_SUBAGENT_MODEL_FORCE 를 1 로 같이 둡니다.

Q. 메인이 Fable 인데 Explore 가 Opus 로 돌아요

문서에 적힌 동작입니다.

메인이 Fable 이면 Explore 는 opus 별칭이 가리키는 모델로 돕니다. 저희 기록의 Explore 2개도 그랬습니다. 바꾸려면 호출에 모델을 넘기거나 Explore 라는 이름의 에이전트 파일을 만듭니다.

Q. inherit 는 무엇인가요?

메인 대화의 모델을 따르라는 값입니다.

에이전트 파일의 model: 에 씁니다. 변수에 inherit 를 넣으면 비워 둔 것과 같습니다. 호출의 model 에는 못 씁니다.

Q. fallbackModel 을 opus 로 해 두면 한도에 걸려도 이어지나요?

이어지지 않습니다.

fallbackModel 은 과부하나 서버 오류에만 넘어가고 rate limit 은 넘기지 않습니다. 모델이 같이 쓰는 세션 한도라면 다른 모델로 넘겨도 같은 벽입니다.

Q. claude code mods 는 어디에 생기나요?

세션 안에서 만들면 ~/.claude/dev-mods/<세션 ID>/ 입니다.

그 세션에서만 로드됩니다. 다른 세션에서 쓰려면 CLAUDE_CODE_PLUGIN_DIRS 에 경로를 넣거나, 마켓플레이스로 묶어 플러그인처럼 설치합니다. mod 는 터미널에서 2.1.287 부터 씁니다.

참고 자료

  • Create custom subagents 는 모델 결정 순서 네 단계, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, 내장 에이전트의 기본 모델과 Fable 일 때의 Explore, 같은 이름의 에이전트 파일이 내장을 덮는다는 것, mod 의 agent.spawn 이 호출보다 앞선다는 것의 근거입니다.
  • Model configuration 은 fallbackModel 이 넘어가는 오류와 넘어가지 않는 오류, 그 턴에만 유지된다는 것의 근거입니다.
  • Mods overview 와 Mods reference 는 turn.step 과 agent.spawn 이 모델을 바꿀 수 있다는 것, 지원 버전, --plugin-dir 로 폴더를 한 세션에 붙이는 법의 근거입니다.
  • superpowers claude code 글 은 작업을 서브에이전트로 쪼개 돌리는 흐름의 기록이고, 플러그인 글 은 깔아 둔 것을 재는 법입니다.

이 사이트의 수치는 주 1회 DB와 다시 대조하고, 판단이 바뀌면 지우지 않고 글 안에 덧붙입니다. 갱신은 RSS로 받을 수 있습니다.