Haiku 5.5를 Claude Code 읽기 전용 서브에이전트로 쓰고 실제 모델까지 검증하기
Claude Code에서 범위가 명확한 읽기 전용 조사만 소형 모델에 위임하는 실전 가이드입니다. 정확한 모델 ID를 지정한 사용자 정의 서브에이전트 구성, Explore 역할만 바꾸는 방식과 전체 강제 설정의 차이, /tasks 및 제공자 요청 기록을 통한 실제 실행 모델 검증을 다룹니다.
목차
가장 안전한 방식은 Claude Code 세션 전체를 소형 모델로 바꾸는 것이 아닙니다. Haiku 5.5에는 범위가 명확하고, 읽기 전용이며, 결과를 쉽게 확인할 수 있는 작업만 맡기세요. 예를 들어 심볼 참조 찾기, import 경로 추적, 설정 위치 확인, 지정한 파일 묶음 요약이 적합합니다. 판단, 편집, 테스트, 최종 승인은 Sonnet이나 Opus를 사용하는 메인 대화가 담당하도록 유지합니다.
신뢰할 수 있는 설정에는 프롬프트의 “Haiku를 사용하라”는 문장이나 파일의 model: haiku보다 더 많은 증거가 필요합니다. 세 가지 층을 확인하세요. 에이전트 정의에 명시한 모델, 실행 중인 작업에 대해 Claude Code가 표시하는 모델, 그리고 제공자의 요청 기록에 남은 실제 Model ID입니다. 세 층이 일치할 때만 해당 실행을 검증된 것으로 취급합니다.
어떤 작업을 위임할지 결정하기
Anthropic은 Haiku 5.5를 요약, 컨텍스트 압축, 데이터베이스 질의, 분류처럼 빠르고 반복적인 작업에 적합한 모델로 설명합니다. 또한 Sonnet 5.5나 Opus 5.5와 함께 사용하는 코딩 서브에이전트로 명시합니다. 복잡한 에이전트형 코딩에는 여전히 더 큰 모델을 권장합니다. 자세한 내용은 Haiku 5.5 공식 발표를 참고하세요.
처음에는 다음과 같이 역할을 나누는 것이 좋습니다.
| 작업 | 권장 담당 | 이유 |
|---|---|---|
| 클래스, 함수, 설정의 모든 참조 위치 찾기 | 읽기 전용 소형 모델 서브에이전트 | 입력, 출력, 종료 조건이 명확함 |
| 한 디렉터리 안 파일들의 역할 요약 | 읽기 전용 소형 모델 서브에이전트 | 읽고 종합하면 되며 변경은 필요하지 않음 |
| 진입점에서 데이터베이스 호출까지 요청 경로 추적 | 읽기 전용 소형 모델 서브에이전트 | 파일 경로와 줄 번호로 검증 가능함 |
| 아키텍처, 마이그레이션 전략, 보안 경계 결정 | Sonnet/Opus 메인 에이전트 | 넓은 맥락의 절충과 중요한 판단이 필요함 |
| 코드 수정, 마이그레이션 실행, 의존성 업데이트, 권한 변경 | Sonnet/Opus 메인 에이전트 | 작업 공간을 변경하므로 더 엄격한 검토가 필요함 |
| 조사 후 최종 수정안을 결정하고 구현 | Sonnet/Opus 메인 에이전트 | 증거를 종합하고 결과를 책임져야 함 |
간단한 기준은 다음과 같습니다. 무엇을 찾고, 무엇을 반환하고, 언제 멈출지 한 문장으로 말할 수 있으며 파일을 쓰지 않고 끝낼 수 있습니까? 그렇지 않다면 메인 대화에 남겨 두세요.
서로 다른 네 가지 모델 제어 이해하기
Claude Code에는 혼동하기 쉬운 여러 모델 제어가 있습니다.
- 메인 대화 모델:
/model, 시작 옵션, 설정으로 선택합니다. - 서브에이전트 frontmatter의
model: 해당 에이전트 정의에 적용됩니다. - 별칭과 전체 Model ID:
haiku는 제공자와 버전에 따라 대상이 달라질 수 있는 별칭이고,claude-haiku-5-5는 Anthropic이 공개한 전체 ID입니다. - 특정 역할만 덮어쓰기와 전역 덮어쓰기:
Explore라는 사용자 정의 에이전트는 기본 Explore만 대체하지만,CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1은 거의 모든 서브에이전트에 영향을 줍니다.
현재 공식 서브에이전트 문서의 모델 결정 순서는 호출별 모델, 에이전트 정의의 model, CLAUDE_CODE_SUBAGENT_MODEL, 마지막으로 메인 대화 모델입니다. 따라서 CLAUDE_CODE_SUBAGENT_MODEL만 설정하면 기본값일 뿐이며, 에이전트 정의나 개별 호출이 다시 덮어쓸 수 있습니다. Claude Code 서브에이전트 문서를 확인하세요.
이 작업 흐름에서는 이름이 명확한 읽기 전용 에이전트 하나부터 시작합니다. 전역 강제 덮어쓰기로 시작하지 마세요. Plan, general-purpose, teammate, workflow 에이전트까지 소형 모델로 이동할 수 있기 때문입니다.
1단계: Claude Code 버전과 제공자 ID 확인하기
먼저 클라이언트 버전을 확인합니다.
claude --version버전에 따라 인터페이스와 검증 경로가 모두 달라집니다.
- Claude Code v2.1.198 이상에서는
/agents가 생성 마법사를 열지 않습니다. Claude에게 파일을 만들어 달라고 요청하거나.claude/agents/또는~/.claude/agents/를 직접 편집하라는 안내를 표시합니다. - v2.1.197 이하에서는
/agents가 Running과 Library 탭이 있는 대화형 마법사를 엽니다. - v2.1.242 이상에서는
/tasks가 실행 중인 서브에이전트 행에 모델을 표시합니다. 더 오래된 버전에서는 제공자 요청 기록을 더 중요하게 보세요. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1은 모든 서브에이전트에 같은 모델을 의도적으로 적용할 때만 사용합니다. 이 동작에는 v2.1.257 이상이 필요합니다.
다음으로 제공자가 허용하는 정확한 ID를 확인합니다.
- Anthropic Claude API에서 Haiku 5.5의 공식 Model ID는
claude-haiku-5-5입니다. 공식 모델 페이지를 참고하세요. - 클라우드 플랫폼이나 제3자 게이트웨이에서는 같은 ID가 이미 제공된다고 가정하지 마세요. 배포 이름, 자체 별칭, 선별된 카탈로그를 사용할 수 있습니다.
- 이 가이드를 2026년 10월 10일에 확인했을 때 BetterToken 공개 카탈로그에는
claude-haiku-4-5-20251001,claude-sonnet-5-5,claude-opus-5-5가 있었지만claude-haiku-5-5는 없었습니다. BetterToken을 사용할 때는 새로운 Anthropic ID를 그대로 복사하지 말고 현재 카탈로그에 실제로 있는 ID를 선택하세요. 현재 BetterToken 카탈로그를 확인할 수 있습니다.
“Anthropic이 모델을 출시했다”와 “내 게이트웨이가 그 모델을 제공한다”는 서로 다른 사실입니다. 제공자 카탈로그에 ID가 없다면 자연어 지시나 제품군 별칭만으로 지원된다고 추론하지 마세요.
2단계: 프로젝트용 읽기 전용 서브에이전트 만들기
프로젝트 에이전트는 .claude/agents/에 두고 저장소와 함께 관리할 수 있습니다. ~/.claude/agents/의 사용자 에이전트는 여러 프로젝트에서 사용할 수 있습니다.
저장소 루트에서 프로젝트 디렉터리를 만듭니다.
mkdir -p .claude/agents.claude/agents/repo-researcher.md를 만드세요. Anthropic Claude API를 사용한다면 다음 정의를 사용할 수 있습니다.
---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---
You are a read-only repository researcher.
For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.
Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent세 가지가 중요합니다.
tools는Read,Grep,Glob만 허용하며Write,Edit,Bash를 제공하지 않습니다.description은 언제 위임해야 하는지 설명하여 메인 에이전트가 수정 작업을 잘못 보내는 위험을 줄입니다.model에는 단순히 Haiku를 사용하라는 문장이 아니라 제공자가 허용하는 전체 ID를 사용합니다.
Claude Code를 BetterToken을 통해 연결할 때, 확인 당시 카탈로그에 있던 소형 Claude 모델은 다음과 같습니다.
model: claude-haiku-4-5-20251001이는 현재 카탈로그를 바탕으로 한 예시이며 영구적인 약속이 아닙니다. 매핑을 바꾸기 전에 카탈로그나 Model Plaza를 다시 확인하세요. BetterToken의 Claude Code 문서는 정확한 Model ID를 사용하고 ANTHROPIC_BASE_URL을 https://bettertoken.ai로 설정하되 /v1을 덧붙이지 말라고 안내합니다. BetterToken Claude Code 설정 가이드를 참고하세요.
현재 세션을 시작할 때 .claude/agents/가 존재하지 않았고 새 에이전트를 만든 뒤에도 Claude Code가 인식하지 못한다면 Claude Code를 한 번 재시작하세요. 공식 문서는 세션 시작 시 없었던 첫 agents 디렉터리를 실행 중인 watcher가 발견하지 못할 수 있다고 설명합니다.
3단계: 메인 에이전트는 Sonnet이나 Opus로 유지하기
메인 대화 모델은 별도로 선택합니다. 예를 들어 다음을 사용합니다.
/model sonnet또는:
/model opus게이트웨이를 사용할 경우 별칭 뒤의 최종 모델은 게이트웨이 매핑에 달려 있습니다. 특정 버전을 고정해야 한다면 전체 제공자 ID를 사용하고, 이후 제공자 기록에서 확인하세요.
연구 에이전트 하나만 소형 모델로 바꾸려고 전역 force 변수를 설정하지 마세요. 다음 설정은 훨씬 넓은 범위에 영향을 줍니다.
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}Plan, general-purpose 서브에이전트, teammate, workflow 에이전트까지 같은 모델을 사용하게 하려는 경우에만 사용하세요. 자동 코드 탐색만 바꾸려면 Explore라는 프로젝트 또는 사용자 에이전트를 정의하고 그 정의에만 model을 지정합니다. 그러면 다른 서브에이전트는 그대로 두고 기본 Explore만 대체할 수 있습니다.
4단계: 감사 가능한 테스트로 에이전트 실행하기
처음부터 “저장소 전체를 이해하라”고 하지 마세요. 사람이 직접 확인할 수 있는 좁은 작업을 사용합니다.
Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.실행 후 네 가지를 확인합니다.
- 메인 트랜스크립트에
repo-researcher위임 행이 있고, 메인 에이전트가 몰래 직접 검색하지 않았는지 확인합니다. - 서브에이전트가 파일 경로와 줄 번호를 반환하고 직접 증거와 추론을 구분했는지 확인합니다.
- 작업 트리가 변경되지 않았는지 확인합니다.
git status --short- 이후의 판단과 코드 변경은 연구 에이전트가 아니라 메인 에이전트가 담당하는지 확인합니다.
조사 결과를 보존할 가치가 있다면 먼저 메인 대화에서 검토하세요. 그런 다음 메인 에이전트가 승인된 결과를 프로젝트 문서나 이슈에 저장하게 합니다. 결과를 저장한다는 이유만으로 연구 에이전트에 쓰기 권한을 추가하지 마세요.
5단계: 실제로 실행된 모델 검증하기
1. 에이전트 정의를 확인하되 거기서 끝내지 않기
.claude/agents/repo-researcher.md에 의도한 전체 ID가 있는지 확인합니다. 이것은 정적 설정만 증명합니다. 호출별 모델, 조직 정책, 게이트웨이 매핑이 실제 요청을 바꿀 수 있습니다.
2. 에이전트 실행 중 /tasks 확인하기
다음을 실행합니다.
/tasksClaude Code v2.1.242 이상은 서브에이전트 행에 모델을 표시합니다. 파일과 다르다면 다음을 확인하세요.
- Claude가 이번 호출에 다른 모델을 전달했는지.
CLAUDE_CODE_SUBAGENT_MODEL_FORCE가 활성화되어 있는지.- 조직의
availableModels정책이 허용된 모델로 대체했는지. - 클라이언트 버전이 더 오래된 우선순위 규칙을 따르는지.
3. 제공자 요청 기록과 대조하기
같은 시간대의 요청을 찾아 실제 Model ID를 확인합니다. 제3자 게이트웨이에서는 특히 중요합니다. 클라이언트에 표시된 별칭이 게이트웨이에서 다시 매핑될 수 있기 때문입니다.
BetterToken은 모델, 토큰 수, 최종 청구액, 상태를 하나의 요청 기록에 표시합니다. 이 작업 흐름에서는 검증에 모델과 상태 필드만 사용하고, 해당 기록을 근거 없는 절감 주장으로 확대하지 마세요. 요청 타임스탬프가 서브에이전트 실행 시간대와 일치한 뒤에만 그 에이전트의 요청으로 연결합니다.
다음과 같은 간단한 인수 표를 사용할 수 있습니다.
| 확인 지점 | 기대 증거 | 다를 때 |
|---|---|---|
| 에이전트 파일 | 정확한 Model ID | ID를 수정하고 필요하면 다시 로드하거나 재시작 |
/tasks | 대상 서브에이전트와 실행 모델 | 호출 설정, force 변수, 조직 정책 확인 |
| 제공자 기록 | 같은 시간대의 실제 Model ID와 성공 상태 | 카탈로그, 별칭 매핑, 라우팅, 계정 권한 확인 |
git status --short | 예상치 못한 파일 변경 없음 | 도구를 제한하고 변경을 되돌린 뒤 재실행 |
처음 세 확인 지점에서 모델 증거가 일치할 때만 “모델 전환 검증 완료”라고 기록하세요. Haiku가 적힌 프롬프트, 화면의 에이전트 이름, 답변이 끝났다는 사실만으로는 충분하지 않습니다.
문제 해결
에이전트가 호출되지 않음
파일이 .claude/agents/ 또는 ~/.claude/agents/에 있고, frontmatter에 name과 description이 있으며, YAML이 올바르게 해석되는지 확인합니다. 세션 시작 후 처음으로 에이전트 디렉터리를 만든 경우 Claude Code를 재시작하세요. 계속 로드되지 않는다면 --debug로 Claude Code를 실행하고 로딩 오류를 확인합니다.
/agents에 생성 마법사가 보이지 않음
대부분 정상 동작이며 오류가 아닙니다. v2.1.198 이상의 /agents는 에이전트 파일을 직접 편집하라는 안내를 표시합니다. 대화형 마법사는 v2.1.197 이하의 동작입니다. 오래된 스크린샷이 아니라 실제 사용 중인 버전의 문서를 따르세요.
model: haiku만으로 Haiku 5.5를 증명할 수 없음
haiku는 고정 버전이 아니라 별칭입니다. Claude Code 버전, 제공자, 게이트웨이 매핑에 따라 대상이 달라질 수 있습니다. 감사 가능한 라우팅을 위해 현재 제공자 카탈로그에 있는 전체 ID를 사용하고 /tasks와 제공자 기록을 모두 확인하세요.
게이트웨이가 model not found, 403을 반환하거나 조용히 폴백함
먼저 해당 ID가 게이트웨이의 실시간 카탈로그에 있고 계정에 사용 권한이 있는지 확인합니다. 카탈로그에 claude-haiku-5-5가 없다면 같은 문자열을 반복해서 시도하지 말고, 목록에 있는 적절한 모델을 선택하거나 게이트웨이가 추가할 때까지 기다리세요. 조직 allowlist가 다른 모델로 교체하면서 작업을 계속할 수도 있으므로 실행 증거를 점검해야 합니다.
모든 서브에이전트가 소형 모델로 바뀜
CLAUDE_CODE_SUBAGENT_MODEL_FORCE를 찾아 제거합니다. 하나의 에이전트만 고정하려면 해당 에이전트 frontmatter에 전체 ID를 넣습니다. 자동 탐색만 바꾸려면 대신 Explore를 덮어쓰세요.
연구 에이전트가 파일을 변경함
git status --short로 범위를 확인한 뒤 의도하지 않은 변경을 되돌립니다. tools를 Read, Grep, Glob로 제한하고 시스템 프롬프트에도 읽기 전용 경계를 반복해 적습니다. 쓰기 가능한 도구를 제거하는 것이 프롬프트에 “편집하지 마라”고만 쓰는 것보다 더 신뢰할 수 있습니다.
최소한으로 도입하기
다섯 단계부터 시작하세요.
- Claude Code를 업데이트하고
claude --version을 실행합니다. - 제공자 카탈로그에서 현재 실제로 사용 가능한 전체 Model ID를 복사합니다.
Read,Grep,Glob만 허용한repo-researcher하나를 만듭니다.- 하나의 심볼이나 디렉터리로 제한한 작업으로 실행합니다.
/tasks, 제공자 요청 기록,git status --short를 서로 대조합니다.
목표는 모든 작업을 가장 작은 모델로 보내는 것이 아닙니다. 목표는 감사 가능한 역할 분담을 만드는 것입니다. 소형 모델은 검증 가능한 읽기 전용 증거를 수집하고, Sonnet 또는 Opus 메인 에이전트가 영향이 큰 판단과 변경을 책임집니다. 먼저 좁은 작업 하나를 검증한 뒤, 같은 인수 기준이 유지되는 범위에서만 이 패턴을 확대하세요.
