Claude Code 서브에이전트, 이제 사용량 한도를 더 적게 소모합니다

이제 Claude Code 서브에이전트가 사용량 한도를 더 적게 차지합니다. Anthropic이 백그라운드 서브에이전트의 상태 라인 처리 방식을, 긴 대화 전체를 다시 읽던 방식에서 짧은 메모를 바탕으로 작업하는 Haiku 5.5 방식으로 바꾼 것입니다. 이제 업데이트 한 번의 비용은 약 99% 줄었고, 백그라운드 서브에이전트를 사용한 세션은 한도를 약 5% 덜 소모했습니다. 이 혜택을 받으려면 v2.1.316 이상으로 업데이트하세요.

네 문장이면 전체 내용이 정리됩니다. 이 글의 나머지 부분에서는 이 변경이 적용되는 대상, 두 퍼센트 수치가 의미하는 바, 아직 알려지지 않은 부분, 그리고 서브에이전트 사용량을 더 줄여주는 설정들을 다룹니다.

Claude Code 서브에이전트에서 달라진 것

백그라운드 서브에이전트는 여러분이 작업을 계속하는 동안 메인 세션과 함께 실행되는 도우미입니다. 터미널에서는 짧은 상태 라인을 표시해 무엇을 하고 있는지 확인할 수 있으며, 이 라인은 30초마다 갱신됩니다.

Anthropic은 2026년 11월 5일 X에서 이 변경 사항을 발표했습니다:

이전: 30초마다 이루어지는 업데이트가 서브에이전트의 전체 대화를 다시 읽었습니다.
현재: Haiku 5.5가 짧은 메모를 바탕으로 업데이트를 작성합니다.
그대로인 것: 서브에이전트는 자신의 모델을 그대로 사용합니다. Opus 5.5나 Sonnet 5.5로 실행 중이었다면 여전히 그렇습니다. 상태 라인만 Haiku 5.5로 옮겨진 것입니다.

설정을 바꿀 필요도 없고, 작업 자체의 품질을 희생할 필요도 없습니다. 서브에이전트의 결과물은 이전과 동일한 모델에서 나옵니다.

서브에이전트 상태 라인이 비쌌던 이유

상태 라인이 비싸던 이유는, 한 줄짜리 요약을 위해 긴 대화 전체를 읽는 비용을 치러야 했기 때문입니다. 출력은 아주 작았지만 입력은 그렇지 않았고, 서브에이전트가 실행되는 내내 이 작업이 30초마다 반복됐습니다.

Diagram comparing two flows: before, the whole subagent conversation fed each status update every 30 seconds; now, short notes go to Haiku 5.5, which writes the update at about 99% less cost per update

간단한 계산만 해도 얼마나 빠르게 쌓이는지 알 수 있습니다. 30초마다 한 번씩 업데이트하면, 1시간 동안 실행된 서브에이전트 하나가 120회의 업데이트를 만들어냅니다. 세 개가 1시간 동안 실행되면 360회입니다.

대화 길이도 영향을 미칩니다. Claude Code 비용 문서에 따르면 토큰 비용은 컨텍스트 크기에 비례해 늘어나는데, 서브에이전트의 대화는 파일을 읽고 도구를 실행할수록 길어집니다. 따라서 기존 설계에서는 오래 실행된 서브에이전트가 컨텍스트를 가장 많이 쌓았을 때 비용도 가장 많이 나왔을 가능성이 높습니다. Anthropic이 이에 대한 비용 곡선을 공개하지 않았기 때문에, 이것은 문서를 바탕으로 한 우리의 해석입니다.

이를 /statusline으로 설정하는 사용자 지정 상태 라인과 혼동하지 마세요. 상태 라인 문서에 따르면 사용자 지정 상태 라인은 로컬에서 실행되며 API 토큰을 소모하지 않습니다. 이번 변경은 실행 중인 각 서브에이전트에 대해 Claude Code가 생성하는 상태 라인에 관한 것입니다.

핵심 수치: 업데이트당 99%, 세션당 약 5%

두 수치는 서로 다른 것을 측정하며, 한도를 설명하는 것은 둘 중 하나뿐입니다.

수치	측정 대상	해당하지 않는 것
약 99% 감소	상태 업데이트 한 번의 비용	청구서나 사용량 한도의 절감
약 5% 감소	백그라운드 서브에이전트가 있는 세션의 한도 사용량	서브에이전트가 없는 세션의 절감
약 6% 증가	Anthropic 발표 기준, 같은 한도에서 얻게 되는 프롬프트 수	한도 자체의 상승

Bar comparison: one status update drops by about 99 percent, while a whole session with background subagents drops by about 5 percent, as stated by Anthropic

숫자 하나만 기억한다면 5%를 기억하세요. 세션에서 차지하던 비중이 작았던 부분을 99% 줄인다고 해도 세션 전체에서의 절감은 작습니다. 서브에이전트는 여전히 자신의 모델로 실제 작업을 수행하며, 사용량 대부분은 바로 그 작업에서 발생합니다.

Anthropic은 이전에 상태 업데이트가 한도의 얼마를 사용했는지 밝히지 않았습니다. 두 수치를 조합해 보면 그 세션들에서 대략 20분의 1 정도였을 것으로 짐작할 수 있지만, 이는 반올림된 수치에 근거한 추론이지 공개된 수치가 아닙니다.

실제 절감 폭은 여러분의 상황에 따라 달라집니다. 약 5%는 Anthropic이 백그라운드 서브에이전트가 있는 세션 전반에 대해 보고한 수치입니다. 구체적인 범위는 공개되지 않았으며, 짧은 서브에이전트 하나를 실행한 세션은 여러 개의 긴 서브에이전트를 실행한 세션보다 절감 폭이 작습니다.

서브에이전트 사용량 절감이 적용되는 대상

Anthropic에 따르면 이 변경 사항은 대부분의 개인 플랜과 모든 조직 플랜에 적용되었으며, CLI에서만 해당됩니다.

Claude Code 사용 환경	상태
Pro, Max, Ultra	대부분의 사용자에게 적용됨(전체는 아님)
Team, Enterprise	모든 사용자에게 적용됨
CLI	해당됨, v2.1.316 이상
데스크톱 앱	변경할 사항 없음: 이 상태 라인을 생성하지 않음
API key, Bedrock, Vertex, Foundry	언급 없음

데스크톱 관련 내용은 같은 스레드에서 Anthropic의 Lydia Hallie가 남긴 답글에서 나온 것으로, 데스크톱 앱은 이 서브에이전트 상태 라인을 생성하지 않기 때문에 변경할 것이 없었다고 말했습니다.

다음 두 가지 정보 공백은 알아둘 가치가 있습니다:

'대부분'에는 공개된 확인 방법이 없습니다. 스레드와 문서 어디에서도 자신의 Pro, Max, Ultra 계정에 적용되었는지 알려주는 플래그나 표시 방법을 소개하지 않습니다. 올바른 버전을 사용하고 있는 것은 필요 조건이지만, 변경 사항이 실제로 여러분에게 적용되었다는 증거는 아닙니다.
토큰 종량제 사용자는 아직 답을 얻지 못했습니다. Anthropic은 이 발표를 플랜 한도를 중심으로 설명했고, API 키나 클라우드 공급자 설정에는 언급하지 않았습니다. 다만 2.1.318 체인지로그에는 Bedrock, Vertex, Foundry 환경이나 텔레메트리가 꺼진 경우의 서브에이전트 진행 요약 변경 사항이 있습니다: 프롬프트 캐시가 콜드 상태일 때는 서브에이전트의 대기 중인 응답을 최대 5분까지 기다려야 할 수 있다는 내용입니다. 이는 그런 환경들에 별도의 처리가 적용된다는 점을 보여줄 뿐, 이번 절감이 적용된다는 의미는 아닙니다.

확인한 2.1.316 체인지로그 항목에도 상태 라인이 언급되어 있지 않습니다. 따라서 이 수치와 버전에 관해서는 해당 스레드가 유일한 출처입니다.

Claude Code 업데이트와 버전 확인 방법

세 가지 명령이면 충분합니다:

claude --version   # needs to show 2.1.316 or later
claude update      # installs a newer version if one exists
claude --version   # confirm

claude update는 패키지 매니저로 설치한 경우에도 작동하며, 해당 패키지 매니저를 통해 업데이트를 수행합니다. 11월 5일 기준 체인지로그에 기재된 최신 버전은 2.1.318이었습니다.

서브에이전트가 무엇을 사용하는지 확인하려면 세션 안에서 /usage를 실행하세요. Pro, Max, Ultra, Team, Enterprise 플랜에서는 최근 사용량을 스킬, 서브에이전트, 플러그인, MCP 서버별 백분율로 보여줍니다. d 또는 w 키를 눌러 24시간과 7일 보기를 전환할 수 있습니다. 이 수치는 근사치이며 해당 머신의 로컬 기록을 기반으로 하므로, 변경 전후 비교는 대략적인 참고용으로만 삼으세요. 한도를 꼼꼼히 관리하고 계신다면 Claude Pro·Max 한도 가이드에서 그 작동 방식을 설명하고 있습니다.

서브에이전트 비용을 더 줄이는 다른 방법

상태 라인 수정은 자동으로 적용되지만 절감 폭은 약 5%에 그칩니다. 나머지 부분에 대해서는 문서가 분명합니다: 각 서브에이전트는 자체 요청을 보내며, 이는 메인 대화와 동일한 한도에 포함됩니다. 다음 설정들이 더 큰 절감 여지를 줍니다.

더 작은 모델을 선택하세요. 별도 지정이 없으면 서브에이전트는 세션의 모델을 물려받기 때문에, Opus로 전환하면 해당 서브에이전트들도 함께 영향을 받습니다. 간단한 작업에는 서브에이전트 정의에 model: haiku를 설정하세요. Claude Code에서 Claude Haiku 5.5 사용 가이드에서 이 설정을 다룹니다.

모든 서브에이전트의 기본값을 설정하려면:

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

첫 번째 변수만으로는 기본값일 뿐입니다. 서브에이전트 정의나 Claude가 전달하는 모델이 여전히 우선하며, 내장된 Explore와 Plan 서브에이전트에는 적용되지 않습니다. 두 번째 변수는 모든 서브에이전트에 하나의 모델을 강제합니다.

노력 수준을 낮추세요. 2.1.316 버전에 CLAUDE_CODE_SUBAGENT_EFFORT가 추가되었는데, 이는 다른 곳에서 지정하지 않은 경우 세션의 설정을 물려받는 대신 서브에이전트의 노력 수준을 설정합니다. 체인지로그에는 기록되어 있지만 11월 5일 기준 환경 변수 참조 문서에는 없었으므로, 이에 의존하기 전에 허용되는 값을 확인하세요. 개별 서브에이전트에는 정의에 문서화된 effort 필드를 설정하면 됩니다(모델에 따라 low, medium, high, xhigh, max).

동시 실행 수를 줄이세요. 기본 상한은 세션당 실행 중인 서브에이전트 20개입니다. 확실한 상한을 두고 싶다면 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS를 더 낮은 정수로 설정하세요. /tasks를 실행하면 현재 실행 중인 항목과 각 서브에이전트가 사용하는 모델 및 노력 수준을 확인할 수 있습니다.

작업 지시 범위를 좁게 유지하세요. 비용 문서는 막연한 요청이 광범위한 탐색을 유발한다고 지적합니다. 특정 엔드포인트 하나를 확인하라는 서브에이전트는 API 전체를 검토하라는 서브에이전트보다 읽는 양이 적습니다. 사용자 지정 Claude Code 서브에이전트 만들기 가이드에서 전체 정의 형식을 단계별로 설명합니다.

Apidog CLI로 백그라운드 서브에이전트에서 API 테스트 실행하기

API 테스트 실행은 백그라운드 서브에이전트에 딱 맞는 작업입니다: 시간이 걸리고, 출력이 장황하며, 결국 필요한 것은 실패한 항목뿐이니까요. Apidog CLI를 사용하면 메인 세션이 계속 코딩하는 동안 서브에이전트가 저장된 테스트 시나리오를 실행하고, 원본 출력은 메인 컨텍스트에 들어오지 않습니다.

한 번만 설정하면 됩니다:

npm install -g apidog-cli@latest
apidog login --with-token <YOUR_TOKEN>
npx -y skills add https://apidog.com   # pick Claude Code when prompted

그런 다음 .claude/agents/api-tester.md 경로에 간단한 서브에이전트를 추가합니다:

---
name: api-tester
description: Runs Apidog test scenarios and reports only the failures.
tools: Bash, Read
model: haiku
background: true
---
Run the Apidog test scenario you are given. Report which steps failed
and why. Don't paste the full output.

이제 Claude Code에 프롬프트 하나만 주면 됩니다:

Use the api-tester subagent to run Apidog test scenario <scenarioId> in
project <projectId> against environment <environmentId>. Keep working on
the checkout refactor. When it finishes, tell me only what failed.

서브에이전트는 다음과 같은 명령을 실행합니다:

apidog test-scenario list --project <projectId>
apidog test-scenario run <scenarioId> --project <projectId> -e <environmentId> -r cli,json --out-dir apidog-reports

백그라운드 서브에이전트에서 발생한 권한 승인 요청은 메인 세션에 표시되며, 요청하는 서브에이전트의 이름을 함께 보여줍니다. 오래 걸리는 작업의 경우 2.1.318부터는 셸 명령이 3분 후 백그라운드로 전환되어, 실행 중에 프롬프트 캐시가 만료되지 않습니다.

동일한 run 명령은 -r junit 옵션과 함께 CI에서도 사용할 수 있으며, Apidog CLI CI/CD 가이드에서 이를 보여줍니다. 일반적인 설정 방법은 Claude Code에서 Apidog CLI 사용하기를 참고하세요. Apidog 무료 플랜은 최대 4명까지 사용할 수 있습니다.

FAQ

Claude Code 서브에이전트가 이제 99% 저렴해졌나요? 아닙니다. 99%는 상태 업데이트 각각에 적용되는 수치입니다. Anthropic에 따르면 백그라운드 서브에이전트가 있는 세션은 한도를 약 5% 덜 사용했습니다.

제 서브에이전트도 이제 Haiku 5.5로 실행되나요? 아닙니다. 서브에이전트는 자신의 모델을 그대로 사용합니다. 상태 라인만 Haiku 5.5로 옮겨졌습니다.

어떤 버전이 필요한가요? v2.1.316 이상입니다. claude --version으로 확인하고 claude update로 업그레이드하세요.

Claude 데스크톱 앱에도 적용되나요? 아니요, 변경할 것이 없었기 때문입니다. Anthropic의 Lydia Hallie는 데스크톱 앱이 이 서브에이전트 상태 라인을 생성하지 않는다고 말했습니다.

제 Pro 플랜에 적용되었나요? 아마 그럴 것이지만 확실하지는 않습니다. Anthropic은 대부분의 Pro, Max, Ultra 사용자와 Team 및 Enterprise의 모든 사용자에게 적용되었다고 밝혔습니다. 다만 스레드와 문서 어디에도 자신의 계정을 확인하는 방법은 나와 있지 않습니다.

API 키나 Bedrock을 사용하는 경우에도 도움이 되나요? Anthropic은 아직 밝히지 않았습니다. 이번 발표는 사용량 한도를 중심으로 다루었으며, API 키, Bedrock, Vertex 사용량은 언급하지 않았습니다.