클로드 코드에서 클로드 하이쿠 5.5 사용법: 서브 에이전트 모델로 활용하기

Claude Code에서 Claude Haiku 5.5를 사용하려면 claude update로 v2.1.293 이상으로 업데이트한 뒤 claude --model claude-haiku-5-5로 세션을 시작하거나, 실행 중인 세션에서 /model claude-haiku-5-5를 실행하십시오. 대부분의 경우 Haiku 5.5는 주 모델보다 서브에이전트로 사용할 때 효율적입니다. 서브에이전트 파일에 model: haiku를 지정하고 Sonnet 5.5 또는 Opus 5.5가 검색 결과 검토, 테스트 판단, 최종 요약을 맡게 하십시오. API 키 사용 시 최대 100K 토큰 프롬프트는 입력/출력 백만 토큰당 $0.10/$0.50이며, 100K를 초과하면 $0.50/$2.50입니다.

지금 Apidog를 사용해 보세요

이 글에서는 설정 방법, haiku 별칭의 주의점, 노력 수준, 서브에이전트 파일 작성, 100K 가격 단계, Sonnet 또는 Opus를 주 모델로 유지해야 하는 경우를 다룹니다. 모델 자체에 대해서는 Claude Haiku 5.5란 무엇인가를 참고하십시오. 코드에서 API를 호출한다면 Apidog로 Haiku 서브에이전트가 실행할 테스트 시나리오를 관리할 수 있습니다.

Claude Code에서 Claude Haiku 5.5 한눈에 보기

설정	Haiku 5.5
최소 버전	v2.1.293 (claude update)
모델 ID	claude-haiku-5-5
haiku 별칭	Anthropic API의 Haiku 5.5만 해당
컨텍스트	모든 플랜에서 1M 기본, [1m] 접미사 없음
자동 압축	기본적으로 약 967K 토큰
기본 노력 수준	medium (low부터 max까지)
사고 기능 (Thinking)	항상 켜져 있음, 끌 수 없음
API 가격	최대 100K 토큰 프롬프트에 $0.10/$0.50, 100K 초과 시 $0.50/$2.50
플랜	Pro, Max, Team, Enterprise 또는 API 키. 무료 플랜 불가

1단계: Claude Code 업데이트

Haiku 5.5는 Claude Code v2.1.293 이상이 필요합니다. 변경로그에서는 이를 “현재 Anthropic API의 기본 Haiku 모델”로 설명합니다.

claude update

업데이트 후 버전을 확인하고, 필요하면 Claude Code를 다시 시작하십시오.

Claude Code는 무료 플랜에서 사용할 수 없습니다. 무료 사용자는 Claude.ai 앱에서 Haiku 5.5를 선택할 수 있지만, Claude Code를 사용하려면 Pro, Max, Team, Enterprise 플랜 또는 Anthropic API 키가 필요합니다. claude.com/pricing에 따르면 Pro는 연간 청구 시 월 $17 또는 월 $20이며, Max는 $100부터 시작합니다.

2단계: Haiku 5.5를 주 모델로 선택

새 세션을 Haiku 5.5로 시작하려면 전체 모델 ID를 사용하십시오.

claude --model claude-haiku-5-5

이미 실행 중인 세션에서는 다음 명령을 사용합니다.

/model claude-haiku-5-5

저장된 model 설정이 haiku인 경우, Haiku 4.5에서 저장한 세션은 Haiku 5.5에서 다시 시작될 수 있습니다.

haiku 별칭은 Anthropic API의 Haiku 5.5만 의미합니다

제공업체	haiku가 해석되는 모델
Anthropic API	Haiku 5.5
AWS의 Claude Platform	Haiku 4.5
Amazon Bedrock, Google Cloud의 Agent Platform	Haiku 4.5
Microsoft Foundry	Haiku 4.5

클라우드 제공업체를 사용한다면 서브에이전트 파일의 /model haiku 또는 model: haiku가 Haiku 4.5를 선택할 수 있습니다. 이 경우 전체 모델 ID를 명시적으로 고정하십시오.

• Google Cloud 및 AWS Claude Platform: claude-haiku-5-5
• Microsoft Foundry: 배포 이름
• Amazon Bedrock: us.anthropic.claude-haiku-5-5 같은 추론 프로필 ID

또는 5단계에서 설명하는 ANTHROPIC_DEFAULT_HAIKU_MODEL 환경 변수로 기본 별칭을 지정할 수 있습니다.

3단계: 노력 수준 선택

Haiku 5.5는 노력 수준을 제어할 수 있는 첫 번째 Haiku 모델입니다. Claude Code의 기본값은 medium이며, 다음 값을 사용할 수 있습니다.

low
medium
high
xhigh
max

예를 들어 긴 에이전트 작업에 high를 지정하려면 다음과 같이 실행합니다.

claude --model claude-haiku-5-5 --effort high

실행 중인 세션에서는 다음과 같이 변경합니다.

/effort low

권장 기준은 다음과 같습니다.

작업 유형	권장 노력 수준
짧은 도구 호출, 대량 반복 작업	low
일반적인 코딩 및 분석 작업	medium
긴 에이전트 작업	high
평가에서 품질 향상이 검증된 작업	xhigh, max

Haiku 5.5의 사고 기능(Thinking)은 Claude Code에서 항상 활성화됩니다. 다음 설정은 효과가 없습니다.

alwaysThinkingEnabled: false
MAX_THINKING_TOKENS=0

사고 토큰 사용량을 줄이려면 사고 기능을 끄는 대신 노력 수준을 낮추십시오. low가 가장 저렴한 설정입니다. 원시 Messages API에서는 high 이하 수준에서 사고 기능을 비활성화할 수 있습니다.

4단계: Haiku 5.5를 서브에이전트로 실행

Anthropic은 Haiku 5.5가 코딩 작업에서 Opus 5.5 및 Sonnet 5.5와 서브에이전트로 잘 조합된다고 설명합니다.

서브에이전트 파일은 다음 위치에 Markdown 파일로 저장합니다.

.claude/agents/     # 현재 프로젝트
~/.claude/agents/   # 모든 프로젝트

YAML 프론트매터에서 name과 description은 필수입니다. 서브에이전트 문서에 따르면 model에는 sonnet, opus, haiku, fable, 전체 모델 ID 또는 inherit를 지정할 수 있습니다. 서브에이전트의 범위와 도구 설계는 Claude Code 서브에이전트 가이드에서 확인할 수 있습니다.

Explore를 저렴한 탐색기로 교체

내장 Explore 서브에이전트는 Haiku가 아니라 주 대화의 모델로 실행됩니다. 예를 들어 Opus 5.5 세션에서는 모든 Explore 검색이 Opus에서 실행될 수 있습니다.

Explore라는 프로젝트 또는 사용자 서브에이전트를 만들면 내장 Explore를 재정의하면서 별도 모델을 지정할 수 있습니다.

.claude/agents/Explore.md 파일을 만드십시오.

---
name: Explore
description: 빠르고 읽기 전용 코드베이스 검색. 아무것도 편집하지 않고 파일, 심볼 및 호출 사이트를 찾을 때 사용합니다.
tools: Read, Grep, Glob
model: haiku
effort: low
---

코드베이스를 검색하고 찾은 내용을 보고합니다. 줄 번호와 각 일치 항목에 대한 짧은 요약을 포함한 파일 경로를 반환합니다. 파일을 절대 편집하지 마십시오.

서브에이전트가 실제로 어떤 모델로 실행되는지 확인하려면 작업 중 /tasks를 실행하십시오.

클라우드 제공업체를 사용 중이라면 model: haiku를 2단계에서 설명한 전체 모델 ID로 교체하십시오.

모든 서브에이전트를 Haiku로 강제 설정

Explore를 포함한 모든 서브에이전트를 Haiku로 실행하려면 설정 파일의 env 블록에 두 환경 변수를 모두 추가하십시오.

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

CLAUDE_CODE_SUBAGENT_MODEL만 설정하면 기본값으로만 작동합니다. 즉, 서브에이전트 파일 내부의 model 필드가 우선하며 Explore도 자동으로 변경되지 않습니다.

5단계: 백그라운드 작업을 Haiku 5.5로 지정

ANTHROPIC_DEFAULT_HAIKU_MODEL은 haiku 또는 claude --resume 같은 백그라운드 기능이 사용할 모델을 지정합니다.

이전 환경 변수인 ANTHROPIC_SMALL_FAST_MODEL은 환경 변수 참조에 따라 더 이상 사용되지 않습니다. 셸 프로필에 이 값이 있다면 교체하십시오.

Anthropic API에서는 별도 설정이 필요하지 않습니다. 하지만 Google Cloud에서는 백그라운드 작업이 기본적으로 Sonnet을 사용할 수 있고, Foundry는 기본 모델을, Bedrock은 Sonnet 또는 기본 모델을 사용할 수 있습니다.

Haiku 5.5가 계정에서 활성화되어 있다면 다음처럼 명시적으로 고정하십시오.

# Google Cloud의 Agent Platform
export ANTHROPIC_DEFAULT_HAIKU_MODEL=claude-haiku-5-5

# Amazon Bedrock: 추론 프로필 ID 사용
export ANTHROPIC_DEFAULT_HAIKU_MODEL=us.anthropic.claude-haiku-5-5

영구 적용하려면 사용하는 셸의 프로필 파일(~/.zshrc, ~/.bashrc 등)에 추가한 뒤 셸을 다시 로드하십시오.

source ~/.zshrc

긴 세션에서의 100K 가격 단계

Haiku 5.5의 가격은 프롬프트 길이에 따라 달라집니다. Claude Code는 매 턴마다 대화 내용을 프롬프트에 포함하므로, 긴 세션은 100K 토큰 가격 단계를 빠르게 넘길 수 있습니다.

세션 컨텍스트가 100K 토큰을 초과하면 각 요청은 다음 요율로 청구됩니다.

프롬프트 길이	입력/출력 백만 토큰당 가격
최대 100K 토큰	$0.10 / $0.50
100K 토큰 초과	$0.50 / $2.50

즉, 100K를 초과하면 짧은 프롬프트 요율의 5배가 됩니다. 문서에는 캐시된 토큰이 이 한도에 포함되는지 명시되어 있지 않으므로, 포함된다고 가정하고 예산을 잡는 것이 안전합니다.

자동 압축만으로는 충분하지 않습니다. Haiku 5.5는 기본적으로 약 967K 토큰에서 압축되므로 100K 가격 단계를 훨씬 넘긴 상태로 세션이 유지될 수 있습니다.

토큰 기반 비용을 관리하려면 다음 두 가지를 적용하십시오.

1. 더 일찍 압축하십시오.
   
   /autocompact 100k로 Claude Code가 허용하는 가장 낮은 창을 설정합니다.

2. 대용량 작업을 서브에이전트로 분리하십시오.
   
   서브에이전트는 별도 컨텍스트를 사용하므로 테스트 로그, 검색 결과, 명령 출력이 주 대화에 계속 누적되지 않습니다.

100K를 초과하더라도 Haiku 5.5의 $0.50/$2.50은 Sonnet 5.5의 $2/$10의 1/4입니다. 다만 유료 플랜에서는 세션이 사용량 제한을 따르며, Anthropic은 Haiku 5.5가 해당 제한에 어떻게 계산되는지 공개하지 않았습니다. 계산 방식은 Haiku 5.5 가격 분석에서 확인할 수 있습니다.

Max 및 Team 구독자는 주의해야 합니다. Anthropic의 API 크레딧 문서에 따르면 새로운 월별 API 크레딧(Max 5배에 $100, Max 20배에 $200, Team에 최대 $500 풀링)은 대화형 Claude Code를 지원하지 않습니다.

Sonnet 5.5 또는 Opus 5.5를 주 모델로 유지해야 할 때

Anthropic은 Sonnet 5.5와 Opus 5.5가 복잡한 에이전트 코딩 작업에 더 적합한 선택이라고 설명합니다.

Anthropic이 Claude Code에서 최대 노력 수준으로 실행한 Terminal-Bench 4.0 결과는 다음과 같습니다.

노력 수준	Haiku 5.5	Sonnet 5.5
medium	$0.68에 20.3%	$0.68에 28.8%
high	$1.04에 24.8%	$1.46에 43%
max	$2.64에 39.2%	$10.44에 70.6%

medium에서는 두 모델의 시도당 비용이 거의 같지만 Sonnet이 더 높은 점수를 기록합니다. Haiku의 낮은 토큰 가격이 어려운 셸 작업의 전체 비용 절감으로 항상 이어지는 것은 아니므로, 복잡한 코딩 세션의 주 모델로는 Sonnet 또는 Opus를 유지하는 편이 좋습니다.

반면 컴퓨터 사용 작업에서는 Haiku가 비용 효율적일 수 있습니다. OSWorld 2.1에서 medium Haiku 5.5는 시도당 $0.13에 53.3%를 기록했고, low Sonnet 5.5는 $0.68에 57.9%를 기록했습니다.

전체 비교 데이터는 Haiku 5.5 벤치마크 분석을 참고하십시오. 주 모델 구성은 Sonnet 5.5 Claude Code 가이드에서 다룹니다.

실무적으로는 다음처럼 분리하는 것이 좋습니다.

• 주 모델: Sonnet 5.5 또는 Opus 5.5
• Haiku 5.5 서브에이전트: Explore, 테스트 실행, 로그 읽기, 문서 수집, 반복적인 검색 작업

예시: Apidog 테스트를 실행하는 Haiku 서브에이전트

테스트 실행은 장황하고 반복적인 출력이 많으므로 Haiku 서브에이전트에 적합합니다. Apidog CLI는 터미널에서 저장된 Apidog 테스트 시나리오를 실행할 수 있으며, 서브에이전트가 결과를 요약하면 주 모델의 컨텍스트를 깨끗하게 유지할 수 있습니다.

.claude/agents/api-test-runner.md 파일을 추가하십시오.

---
name: api-test-runner
description: API 엔드포인트 변경 후 Apidog CLI를 사용하여 프로젝트의 Apidog 테스트 시나리오를 실행한 다음, 실패한 요청과 함께 성공 및 실패 횟수를 보고합니다.
tools: Bash, Read
model: haiku
effort: low
---

변경된 엔드포인트를 다루는 시나리오에 대해 이 저장소의 README에 문서화된 Apidog CLI 테스트 명령을 실행합니다. 성공 및 실패 횟수를 보고합니다. 각 실패에 대해 요청 이름, 예상 결과 및 실제 결과를 제공합니다. 코드를 편집하지 마십시오. 실패한 실행을 한 번 이상 다시 시도하지 마십시오.

이 서브에이전트는 다음 역할에 집중합니다.

1. README에서 프로젝트의 Apidog CLI 실행 명령을 찾습니다.
2. 변경된 API 엔드포인트에 관련된 시나리오를 실행합니다.
3. 성공 및 실패 횟수를 요약합니다.
4. 실패 시 요청 이름, 예상값, 실제값만 간결하게 반환합니다.
5. 코드는 수정하지 않습니다.

인증 및 실행 명령을 포함한 CLI 설정은 Claude Code의 Apidog CLI를 참고하십시오. 서브에이전트가 실행할 테스트 시나리오를 만들려면 Apidog를 다운로드하십시오.

Haiku 4.5에서 앱 마이그레이션

애플리케이션이 API를 통해 Haiku 4.5를 호출하고 있다면 Claude Code로 마이그레이션 작업을 시작할 수 있습니다.

/claude-api migrate this project to claude-haiku-5-5

다음 설정은 Haiku 5.5에서 400 오류를 반환하므로 호환성 문제를 확인해야 합니다.

• 수동 budget_tokens 사고 설정
• 비기본 temperature
• 비기본 top_p
• 모든 top_k
• 어시스턴트 사전 채우기

수정 사항은 Haiku 5.5 vs Haiku 4.5 가이드에서 확인할 수 있습니다.

마이그레이션 후에는 이전 모델과 새 모델 요청을 Apidog에 쌍으로 저장해 비교하십시오. ANTHROPIC_API_KEY는 환경 변수로 관리하고, 테스트에서 다음 항목을 단언하는 것이 좋습니다.

stop_reason
usage

특히 새로운 refusal 중지 사유나 예상보다 큰 토큰 사용량이 프로덕션까지 전달되지 않도록 테스트에서 실패하게 구성하십시오.

FAQ

Haiku 5.5가 Claude Code의 기본 모델입니까?

아닙니다. Haiku 5.5는 Anthropic API의 기본 Haiku 모델입니다. 즉, Anthropic API에서는 haiku 별칭이 Haiku 5.5를 가리킵니다. Claude Code의 주 모델은 --model 또는 /model로 선택하십시오.

무료 플랜에서 Claude Code의 Haiku 5.5를 사용할 수 있습니까?

아닙니다. Claude Code에는 유료 플랜 또는 API 키가 필요합니다. 무료 사용자는 Claude.ai 앱에서 Haiku 5.5를 선택할 수 있습니다. 자세한 내용은 Claude Haiku 5.5를 무료로 사용하는 방법를 참고하십시오.

model: haiku가 Haiku 4.5를 제공하는 이유는 무엇입니까?

Bedrock, Google Cloud, Foundry, AWS Claude Platform을 사용 중이거나 Claude Code v2.1.293 이전 버전을 사용 중일 수 있습니다. 전체 모델 ID를 지정하거나 ANTHROPIC_DEFAULT_HAIKU_MODEL을 설정하십시오.

토큰을 절약하기 위해 사고 기능을 끌 수 있습니까?

Claude Code에서는 불가능합니다. 대신 노력 수준을 낮추십시오. low가 가장 저렴한 설정입니다.

다음 단계

다음 순서로 적용하십시오.

1. claude update를 실행해 v2.1.293 이상으로 업데이트합니다.
2. .claude/agents/Explore.md에 Haiku 기반 Explore 재정의를 추가합니다.
3. 주 모델은 Sonnet 5.5 또는 Opus 5.5로 일주일간 유지합니다.
4. API 프로젝트라면 Apidog 테스트 실행기 서브에이전트를 추가합니다.
5. 세션 비용이 중요하다면 /autocompact 100k를 적용합니다.

자체 코드에서 Haiku 5.5 API를 호출하려면 Haiku 5.5 API 가이드부터 시작하십시오. Apidog는 무료로 시작할 수 있으며, Haiku 서브에이전트가 실행할 실제 API 테스트를 관리할 수 있습니다.