Haiku 5.5를 서브 에이전트 모델로 등록하는 방법

haiku5.5가 오늘 등장했습니다.

마침 서브 에이전트의 토큰 소비에 고민하던 필자에게는 정말 반가운 소식이었습니다.

그래서早速(바로) 서브 에이전트를 haiku5.5로 지정해 보았으니 그 방법을 공유합니다.

결론

Claude Code의 서브 에이전트 모델은 사용자 설정 파일(settings.json)의 두 곳에 추가하는 것만으로 Haiku 5.5로 전환할 수 있습니다. 프로젝트 파일은 변경하지 않습니다.

• env에 CLAUDE_CODE_SUBAGENT_MODEL을 추가합니다 (서브 에이전트 모델).
• modelSettings에 Haiku 5.5의 effortLevel을 추가합니다 (사고의 강도).

본 기사는 2026/10/8 시점의 내용입니다. Claude Code의 버전에 따라 동작 방식이 다른 부분이 있으니, '주의사항'도 읽어주세요.

전제: Haiku 5.5 모델 ID

Haiku 5.5는 2026/10/7에 공개되었습니다. 공식 모델 목록에서는 다음과 같습니다.

방법을 선택하기

서브 에이전트 모델을 결정하는 방법은 몇 가지가 있습니다.

~/.claude/agents/에 사용자용 정의를 놓는 방법도 있습니다. 다만, 동일한 이름의 프로젝트 정의가 있다면, 그쪽이 우선합니다.

절차

1. 사용자 설정 파일 열기

파일이 없으면 새로 만듭니다.

2. 두 곳에 추가하기

{
"model": "sonnet",
"env": {
...

• model은 대화 본체의 모델 예시입니다. 자신의 설정대로 유지해 주세요. - 이미 env나 modelSettings가 있는 경우, 그 안에 항목을 추가합니다. 블록을 겹쳐서 쓰지 마세요. - 이미 modelSettings에 다른 모델 행이 있는 경우, 앞 행 뒤에 쉼표(,)를 추가합니다.

"modelSettings": {
"claude-sonnet-5-5": {
"effortLevel": "high"
...

3. JSON 확인하기

python -c "import json,os; print(json.load(open(os.path.expanduser('~/.claude/settings.json'),encoding='utf-8')))"

에러 없이 설정이 표시되면, JSON은 올바릅니다.

4. 반영 확인하기

새로운 세션에서 서브 에이전트를 하나 실행합니다. model을 지정하지 않고, 다음과 같이 요청합니다.

서브 에이전트를 하나 실행하고, 작동하는 모델의 ID를 시스템 프롬프트에 기재된 그대로 대답하게 하세요.

claude-haiku-5-5라고 답하면, 반영된 것입니다.

모델 결정 우선순위

공식 문서에서는 서브 에이전트의 모델은 다음 순서로 결정됩니다 (v2.1.251 이후).

• 호출 시의 model 지정 - 서브 에이전트 정의의 model

（inherit

은 대화 본체 모델） - 환경 변수
CLAUDE_CODE_SUBAGENT_MODEL

• 대화 본체 모델

즉, 이 기사 방법이 효과를 보는 것은 model을 지정하지 않은 서브 에이전트만입니다.

model

을 작성한 경우에는 그것이 우선됩니다. 노력(effort)은 다음 순서로 결정됩니다.

--effort

플래그 - 환경 변수
CLAUDE_CODE_EFFORT_LEVEL

modelSettings.<모델ID>.effortLevel

• 최상위의
  effortLevel

• 모델의 기본값

필자의 환경에서 확인한 결과

서브 에이전트에게 자신의 시스템 프롬프트 모델 ID를 답변하게 한 결과입니다.

• 2026/10/8 시점에서는 별칭 haiku는 아직 Haiku 4.5를 가리키고 있었습니다. 정의 파일의 model에는 별칭이 아닌, claude-haiku-5-5와 완전한 모델 ID를 작성해 주십시오. - 이것은 서브 에이전트의
  자기 신고입니다. 실행이나 과금되는 모델을 다른 방법으로 확인한 것이 아닙니다.

주의할 점

• 리뷰/평가용 서브 에이전트의 품질: model을 작성하지 않은 모든 서브 에이전트는 Haiku 5.5가 됩니다. 리뷰나 설계 판단을 맡기는 경우, 품질이 떨어질 수 있습니다. 그 역할만 정의의 model에 더 강력한 모델을 작성해 주십시오. - :xhigh
  의 비용 xhigh는 medium(기본값)보다 토큰과 시간이 늘어납니다. Haiku의 빠르고 저렴하다는 장점이 희미해질 수 있습니다. 먼저 medium부터 시작하고, 필요하면 올리십시오. - effort가 서브 에이전트에게 적용되는지: modelSettings 설정이 서브 에이전트 실행에도 적용되는지는 문서에 명시되어 있지 않습니다. 필자의 환경에서도 적용 여부는 확인되지 않았습니다. - 정의 파일: 서브 에이전트 정의의 frontmatter에 effort를 작성할 수 있는지는 공식 문서의 기재가 모순됩니다. 이 기사에서는 사용하지 않겠습니다. - Claude Code 버전: Haiku 5.5에 대응하지 않는 구형 버전에서는 동작하지 않을 수 있습니다. 그럴 경우, Claude Code를 업데이트해 주십시오.

원상 복구하기

추가한 env 블록과, modelSettings의 claude-haiku-5-5 행을 삭제합니다. 이전 줄 뒤의 쉼표도 함께 지워주세요.

참고

Discussion