Claude Code 서브에이전트는 따로 정한 값이 없으면 세션의 effort를 그대로 물려받습니다. 세션을 high로 두면, 파일 목록을 뽑는 정도의 잔심부름도 high로 돕니다. 2.1.316에서 서브에이전트 기본값만 따로 정하는 환경 변수가 생겼습니다.
근거: Claude Code CHANGELOG 2.1.316, 공식 문서 Model configuration: Adjust effort level·Subagents: Choose an effort level. 실행 결과는 Claude Code 2.1.317에서 직접 확인했습니다(2026년 11월 4일).
직접 확인했습니다
빈 폴더에서 같은 명령을 두 번 돌렸습니다. 세션은 --effort high, 서브에이전트(Explore)에게 파일 목록을 시켰습니다.
claude -p "Spawn one Explore subagent to list the files in this folder. Then reply with just the file names." \
--effort high --model sonnet그리고 ~/.claude/projects/<폴더>/ 아래 세션 기록(jsonl)에서 effort 값을 셌습니다. 서브에이전트 기록은 <세션>/subagents/ 에 따로 남습니다.
| 실행 | 본 대화 | 서브에이전트 |
|---|---|---|
| 환경 변수 없음 | high | high |
CLAUDE_CODE_SUBAGENT_EFFORT=low | high | low |
본 대화는 그대로 두고, 서브에이전트만 내려갔습니다.
공식 문서는 effort를 이렇게 설명합니다. “낮은 effort는 단순한 작업에서 더 빠르고 저렴하고, 높은 effort는 복잡한 문제에 더 깊이 추론한다.” 두 번의 실행은 작업이 너무 작아 비용 차이를 잴 만한 크기가 아니었습니다. 이 글에서 절약 폭을 숫자로 말하지 않는 이유입니다.
넣는 법
셸 설정(~/.zshrc 등)에 한 줄을 넣습니다.
export CLAUDE_CODE_SUBAGENT_EFFORT=lowsettings.json 의 env에 넣어도 됩니다.
{
"env": { "CLAUDE_CODE_SUBAGENT_EFFORT": "low" }
}어떤 값이 먼저인가
이 변수는 아무것도 정하지 않았을 때의 기본값입니다. CHANGELOG 표현으로 “when nothing else names one”.
| 정한 곳 | 결과 |
|---|---|
CLAUDE_CODE_EFFORT_LEVEL 환경 변수 | 모든 것을 덮습니다(서브에이전트 포함) |
호출할 때 넘긴 effort 값 | 에이전트 파일보다 먼저 |
에이전트 파일의 effort: | 이 변수보다 먼저 |
| 아무것도 없음 | CLAUDE_CODE_SUBAGENT_EFFORT 값 |
또 하나, 2.1.317부터는 본 대화와 다른 모델로 도는 서브에이전트가 그 모델에 저장한 effort나 모델 기본값을 씁니다. 세션 effort가 넘어가는 경우는 같은 모델일 때입니다.
언제 쓰면 좋은가
탐색·검색·파일 정리처럼 서브에이전트에 넘기는 일이 대부분 단순하다면 low나 medium이 맞습니다. 리뷰나 설계처럼 깊이 생각해야 하는 서브에이전트는 에이전트 파일에 effort: high를 적어 두면, 이 변수와 상관없이 그 값으로 돕니다.
쇼츠로 보기
이 글은 비치콤버스 쇼츠 No.24의 짝 글입니다. 짧은 주소 beachcombers.co.kr/s/24.