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로 받을 수 있습니다.