Claude Code에서는 프로젝트 하위 에이전트에 별도의 모델과 도구를 지정하고, 기본 대화에서 계획과 검토를 담당할 수 있습니다. 승인된 저장소 변경 하나에 대해 Opus 상위 에이전트가 구현 범위를 제한해 Haiku에 넘길 수 있다는 뜻입니다. 유용한 결과는 검증된 코드 변경과 실제 실행 모델의 기록입니다. 더 저렴한 모델을 선택했다는 사실만으로 절감이 입증되지는 않습니다.
핵심 변화
- 달라진 점: 프로젝트 에이전트 파일에서는 이름이 지정된 코딩 작업자에 대해
model: haiku설정을 요청하고, 상위 세션에서는 Opus를 사용할 수 있습니다. - 중요한 이유: 상위 에이전트는 더 작은 작업 단위를 검토할 수 있지만, diff가 원래의 인수 검사를 통과하는지는 개발자가 판단해야 합니다.
- 주의할 점: 모델 재정의, 조직 정책, 권한, 검토와 재시도 때문에 실제 모델과 총사용량이 달라질 수 있습니다. 비용상 이점이 있다고 말하기 전에 이를 확인하세요.
이미 담당하고 있는 작업에서 시작하기
직접 관리하는 Git 저장소, 변경 권한, Claude Code에서 두 모델 계열을 모두 사용할 수 있는 접근 권한, diff를 보고 평가할 수 있을 만큼 작은 승인된 변경 하나가 필요합니다. 시작 commit, 대상 파일이나 동작, 기존 인수 검사 명령, 통과 결과의 의미를 기록하세요. 실행에는 변경 사항이 없는 깨끗한 checkout을 사용합니다. 명령은 해당 프로젝트에서 가져와야 합니다. 이 가이드는 알 수 없는 저장소에 의미 있는 테스트를 대신 정해 줄 수 없습니다.
먼저 claude --version, 공급자와 과금 방식, 적용 중인 모델 제한을 확인하세요. Anthropic API에서 현재 opus 및 haiku 별칭은 각각 Opus 5.5(claude-opus-5-5) 및 Haiku 5.5(claude-haiku-5-5)로 연결됩니다. 이 조합에는 Claude Code v2.1.293 이상이 필요합니다. 다른 공급자는 같은 별칭을 이전 세대로 연결할 수 있습니다. 조직의 availableModels 정책 때문에 선택이 차단되거나 다른 모델로 대체될 수 있습니다. 기본 세션에서 /model 명령을 사용하고 표시되는 정확한 상위 모델을 기록하세요. 허용된 예산을 정하고 실제 계정 또는 공급자 제어 설정을 확인합니다. 모델에 비용 제한을 요청하는 프롬프트만으로 지출 상한이 보장되지는 않습니다. Anthropic 모델 설정 문서에서 현재 연결 관계와 제한을 설명합니다.
1. 프로젝트용 Haiku 작업자 정의하기
프로젝트에서 이름이 중복되지 않는 파일을 만듭니다. 예를 들어 .claude/agents/bounded-code-worker.md 파일을 작성하고 검토한 다음 claude --model opus 명령으로 Opus 상위 에이전트를 시작하거나 /model 명령으로 Opus를 선택하세요. 아래 예시는 테스트 작업이 아니라 작업자 정의입니다.
---
name: bounded-code-worker
description: Implements one explicitly bounded, authorized repository change and reports the diff and checks for parent review.
model: haiku
tools: Read, Glob, Grep, Edit, Bash
permissionMode: default
---에이전트 파일의 마지막 --- 바로 뒤에 다음 일반 언어 시스템 프롬프트를 추가하세요. 상위 에이전트가 전달한 작업과 파일 범위만 구현하라. 편집 전에 관련 코드와 명시된 인수 검사를 확인하라. 작업, 권한 또는 필수 입력이 없으면 중단하고 누락 사항을 보고하라. 관련된 최소한의 변경만 하라. 허용되는 경우 원래 검사를 실행하고 정확한 명령과 결과를 보고하라. 변경 파일, diff의 목적, 남은 실패, 확인하지 못한 작업을 반환하라. 명시적 권한 없이 commit, 게시, 배포 또는 작업 범위 확대를 하지 마라.
이 tools 목록은 도구를 사용할 수 있게 하지만, 읽기나 shell 명령을 지정된 경로로 제한하지는 않습니다. 위임 전에 프로젝트와 조직의 실제 적용 권한, 특히 shell 접근을 확인하세요. 이 절차에서는 상위 에이전트를 Manual/default 권한 모드로 유지합니다. Anthropic 문서에 따르면 상위 에이전트가 acceptEdits, auto 또는 bypassPermissions 모드이면 작업자의 permissionMode 설정을 재정의합니다. 새로 만든 agents 디렉터리의 첫 파일이라면 에이전트가 나타나지 않을 때 Claude Code를 다시 시작하세요. 하위 에이전트 매뉴얼에서 이러한 제어를 설명합니다.
선택 사항인 isolation: worktree 설정은 작업자에게 별도의 checkout을 제공합니다. 문서상 시작점은 저장소의 기본 브랜치이며, 상위 에이전트의 현재 commit과 다를 수 있습니다. 변경을 사용하거나 비교하기 전에 해당 시작 리비전을 기록한 작업 기준점과 대조하세요. 원래의 인수 검사에는 여전히 깨끗하고 승인된 checkout이 필요합니다.
2. 위임한 뒤 검토하고 수락하거나 거부하기
실제 작업과 연결된 지시를 상위 에이전트에 전달합니다. 파일 범위와 검사 명령은 자신의 것을 사용하세요.
이 승인된 변경을 간단히 계획하라. 지정된 구현만 bounded-code-worker 작업자에게 위임하라. 원래 인수 기준과 최종 검토는 네가 맡아라. 작업자가 돌아오면 정확한 diff와 검사 결과를 보여 달라. 내가 검토할 때까지 변경을 수락하거나 확대하지 마라.작업자가 실행되는 동안 /tasks 화면을 열고 해당 행에 표시된 모델을 기록하세요. 이것이 실행 중 확인입니다. 에이전트 파일이나 프롬프트에 적힌 haiku 단어는 요청일 뿐입니다. Claude Code v2.1.242 이상은 그곳에 실행 모델을 표시합니다. 완료된 백그라운드 작업은 /tasks 화면에 약 30초 동안 남으므로 즉시 확인하고 기록을 보관하세요. 해당 행을 놓쳤다면 파일에서 추정하지 말고 모델 확인이 미완료라고 표시합니다.
실제 diff를 읽고 변경된 파일을 하나씩 검토한 뒤, 관리하는 checkout에서 원래의 인수 검사 명령을 직접 실행하세요. 변경에 필요하다면 목적에 맞는 검사를 추가합니다. 동작, 범위, 검사 결과가 작업과 일치할 때만 수락하세요. 작업자가 일찍 중단되거나 일부 작업만 반환했다면 계속하거나 복구하기 전에 바뀐 내용을 확인합니다. 별도 worktree를 썼다면 기본 checkout에 반영하기 전에 해당 변경을 검토하세요.
AI 도우미로 저장소의 실패 하나를 확인하는 관련 접근법은 AI Goal 복구 및 검증 가이드를 참고하세요. 그 절차는 이 글에서 사용하는 Opus에서 Haiku로의 위임을 설정하지 않습니다.
만약 /tasks 화면에서 다른 모델이나 대체 경고가 보이면 호출의 모델 인수, 에이전트 frontmatter, CLAUDE_CODE_SUBAGENT_MODEL, 관리되는 모델 목록을 확인하세요. 현재 Claude Code에서는 호출에 지정된 모델이 frontmatter보다 우선하고, 그다음이 환경 기본값, 마지막이 상위 모델입니다. v2.1.251 이전에는 환경 설정이 우선했습니다. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 설정(v2.1.257 이상)은 정의를 재정의할 수 있으며, 설치된 mod의 agent.spawn hook은 호출 모델을 바꿀 수 있습니다. 실제 재정의 원인을 수정하거나 실행을 중단하세요. Haiku가 아닌 결과를 Haiku라고 바꿔 부르지 마세요.
3. 절감을 꾸며 내지 않고 사용량 기록하기
통제된 이 세션 전후에 /usage 수치를 확인하세요. 모델별 입력·출력·캐시 토큰, 표시된 비용 추정치, 공급자 또는 요금제, 수락한 diff, 원래 검사 결과, 필요한 검토나 재작업을 기록합니다. Session 블록은 전체 세션을 모델별로 합산하므로, 이름이 지정된 이 작업자의 정확한 청구서가 아닙니다. 요금제 사용 비율은 현지 날짜 기준 하루 또는 일주일의 대략적인 기록이며 이 작업 하나의 측정값이 아닙니다. API 계정의 청구 기준은 Claude Console입니다. 구독에서는 세션의 달러 추정치가 추가 청구액을 뜻하지 않습니다. 마지막으로 알려진 사용량 표시라면 오래된 값이라고 명시하세요.
위임으로 이 작업의 비용을 절약했다고 주장하려면, 같은 깨끗한 시작 리비전과 같은 작업·인수 기준으로 별도 승인된 단일 모델 실행과 비교해야 합니다. 상위 에이전트의 계획과 검토, 작업자 호출, 재시도, 모든 재작업을 포함하고 수락된 결과만 비교하세요. 실행 한 쌍은 여전히 해당 작업에 한정된 관찰입니다. 이러한 기준 실행이 없다면 확인된 모델 경로와 코드 결과를 보고하고, 절감 여부는 알 수 없다고 하세요. Anthropic 비용 가이드에서 사용량 표시와 과금의 한계를 설명합니다.
이 절차는 최신 문서를 바탕으로 하며, BIG CHANGE가 Claude Code를 실행하거나 작업을 측정한 결과가 아닙니다. 조직이 설정된 공급자에 보내도록 승인하지 않은 코드나 비밀정보는 전송하지 마세요. 이 글의 경로는 Claude Code 자체의 Opus 및 Haiku 선택을 사용합니다. 다른 모델 공급자를 쓰려면 별도로 정의한 gateway 또는 오케스트레이션 절차와 그에 맞는 검사가 필요합니다.
출처 및 추가 자료
- Anthropic, 사용자 지정 하위 에이전트 만들기 — 프로젝트 에이전트 파일, 모델 우선순위,
/tasks, 권한과 worktree 동작. 현행 매뉴얼을 2026년 10월 20일 확인했습니다. 기능을 설명하는 문서이며, 실행하지 않은 이 가이드 예시의 결과를 입증하지는 않습니다. - Anthropic, 모델 설정 — 현재 별칭, 공급자별 차이, 버전 요구사항과 관리 모델 제어. 사용 시점에 설치 버전과 공급자를 확인하세요.
- Anthropic, 효율적인 비용 관리 —
/usage: 필드, 추정치, 구독과 API 과금의 차이. 이 작업의 절감을 입증하지는 않습니다. - Anthropic, 권한 설정 — 코드를 변경하는 작업자를 실행하기 전에 확인해야 하는 실제 도구 권한 규칙.
