AI Code With
개발 튜토리얼

Claude Code 백그라운드 서브에이전트, 사용 한도를 덜 쓴다: 2.1.316부터 Haiku 5.5가 상태 줄 작성 — 업데이트·확인·모델 설정 방법

Anthropic 공식 계정 @ClaudeDevs에 따르면 Claude Code 백그라운드 서브에이전트가 30초마다 갱신하는 상태 줄은 지금까지 매번 서브에이전트의 대화 전체를 다시 읽었습니다. 이제 Haiku 5.5가 짧은 메모로 작성해 갱신 한 번에 드는 양이 약 99% 줄고, 백그라운드 서브에이전트를 쓰는 세션은 한도를 약 5% 덜 써서 같은 한도로 프롬프트를 약 6% 더 보낼 수 있습니다. v2.1.316 이상이 필요합니다. 누구에게 적용되는지, 업데이트와 버전 확인 방법, API Key로 Claude Code 2.1.318을 연결한 실측, CLAUDE_CODE_SUBAGENT_MODEL·에이전트 파일·/tasks로 모델을 설정하는 방법을 정리했습니다.

10 分钟阅读
Claude Code 백그라운드 서브에이전트, 사용 한도를 덜 쓴다: 2.1.316부터 Haiku 5.5가 상태 줄 작성 — 업데이트·확인·모델 설정 방법

핵심 요약

  • Anthropic 공식 계정 @ClaudeDevs(미국 시간 11월 4일 게시)에 따르면, 실행 중인 백그라운드 서브에이전트는 30초마다 상태 줄을 갱신하는데 지금까지는 갱신할 때마다 서브에이전트의 대화 전체를 다시 읽었습니다. 이제 Haiku 5.5가 짧은 메모로 작성하므로 갱신 한 번에 드는 양이 약 99% 줄었습니다.
  • 후속 게시물에 따르면 서브에이전트 자체는 자기 모델을 그대로 씁니다. 백그라운드 서브에이전트를 쓰는 세션은 한도를 약 5% 덜 써서, 같은 한도로 프롬프트를 약 6% 더 보낼 수 있습니다. 대부분의 Pro·Max·Ultra 사용자와 모든 Team·Enterprise 사용자에게 적용됐고, Claude Code v2.1.316 이상이 필요합니다.
  • 할 일은 하나입니다. claude --version으로 확인하고 2.1.316보다 낮으면 업데이트하세요. AlphaSignal 보도에 따르면 설정은 바꿀 필요가 없습니다.
  • 11월 5일 aicodewith API Key로 Claude Code 2.1.318을 연결해 실측했습니다. 백그라운드 서브에이전트의 상태 줄은 실제로 약 30초마다 바뀌었고(「Reading shop and test files」→「Re-running tests on test_shop.py」), 서브에이전트는 1분 46초 만에 정확한 file:line을 보고했습니다. API Key로 연결했을 때 저희가 잡은 상태 갱신 요청은 서브에이전트 자신의 모델을 썼습니다. 서브에이전트와 상태 줄을 모두 Haiku 5.5로 돌리려면 CLAUDE_CODE_SUBAGENT_MODEL을 설정하면 되고, /tasks에 「Haiku 5.5」가 표시됩니다.

API Key를 만들고 Claude Code에서 백그라운드 서브에이전트 실행하기 →

무엇이 바뀌었나

항목이전v2.1.316부터(공식 설명)
갱신 간격서브에이전트가 작업하는 동안 약 30초마다같음
갱신 때 읽는 것서브에이전트의 대화 전체(갈수록 길어짐)서브에이전트가 작업하며 남기는 짧은 메모
한 줄을 쓰는 주체서브에이전트 자신의 모델Haiku 5.5
갱신 한 번당대화가 길어질수록 늘어남약 99% 감소
세션 전체—한도 약 5% 덜 사용, 프롬프트 약 6% 더
서브에이전트의 작업 모델설정한 모델그대로

출처는 @ClaudeDevs의 본 게시물과 후속 게시물입니다. METAL 보도에 따르면 공식 계정은 6.6초짜리 설명 영상도 함께 올렸고, AlphaSignal에 따르면 게시 시점은 미국 시간 11월 4일입니다.

여기서 말하는 「상태 줄」은 /statusline으로 꾸미는 하단 표시줄이 아닙니다. 입력창 아래 서브에이전트 패널에서 각 백그라운드 서브에이전트 뒤에 붙는 「지금 무엇을 하는지」 한 줄입니다. 개발자 Gabriel Anhaia의 DEV 글에 따르면 이 한 줄은 지금까지 서브에이전트의 대화를 서브에이전트 자신의 모델에 보내 최근 동작을 3~5단어로 요약하게 해서 만들었습니다. 작업 중인 백그라운드 서브에이전트에만 발생하고 쉬고 있을 때는 발생하지 않습니다. 서브에이전트를 많이, 오래 돌릴수록 이 부분이 쌓입니다.

Claude Code 변경 기록을 보면 이 한 줄은 이전에도 몇 차례 손질됐습니다. 2.1.128은 진행 요약이 프롬프트 캐시를 놓치던 문제를, 2.1.274는 요약이 여러 문단짜리 긴 답으로 바뀌던 문제를 고쳤고, 최신 2.1.318은 백그라운드 서브에이전트가 도는 동안 「Now using usage credits」 안내가 약 30초마다 다시 뜨던 문제를 고쳤습니다.

누구에게 영향이 있나

내 상황영향
Pro·Max·Ultra 구독, 백그라운드 서브에이전트를 자주 씀공식에 따르면 대부분 적용됨. 2.1.316+에서 같은 한도로 프롬프트 약 6% 더
Team·Enterprise공식에 따르면 전원 적용
서브에이전트를 거의 안 씀변화 거의 없음. 바뀐 것은 백그라운드 서브에이전트 상태 줄뿐
API Key로 Claude Code 연결(ANTHROPIC_BASE_URL)토큰 단위로 계량되며 구독 한도와 별개. 실측에서는 갱신이 여전히 서브에이전트 모델을 따랐으니, 토큰을 아끼려면 서브에이전트를 Haiku 5.5로(아래 참고)

한도 계산 방식(5시간 창과 주간 한도)은 「Claude Code 사용 한도와 Max 20x」를 참고하세요.

2.1.316+로 업데이트하고 버전 확인

먼저 현재 버전을 확인합니다.

bash
claude --version
2.1.318 (Claude Code)

2.1.316보다 낮으면 설치 방식에 맞게 업데이트합니다. Claude Code 설치 문서에 따르면 네이티브 설치는 백그라운드에서 자동 업데이트되지만, Homebrew와 WinGet은 기본적으로 자동 업데이트되지 않습니다.

bash
# 네이티브/npm 설치: 최신 버전으로 업데이트
claude update
# Homebrew: claude-code 캐스크는 stable 채널이라 보통 약 1주 늦음, 바로 받으려면 @latest
brew upgrade claude-code@latest
# Windows WinGet
winget upgrade Anthropic.ClaudeCode
# 설치 방식, 자동 업데이트 상태, 마지막 업데이트 결과 확인
claude doctor

새 터미널을 열고 claude --version을 다시 실행하세요. 공식 게시물에는 새 스위치나 설정 항목이 없으니, 업데이트한 뒤 평소처럼 백그라운드 서브에이전트를 쓰면 됩니다.

실측: API Key로 Claude Code를 연결해 백그라운드 서브에이전트 실행

테스트 일시는 2026년 11월 5일, Claude Code 2.1.318(Linux), 메인 세션은 Opus 5.5입니다. 기존 설정을 건드리지 않도록 빈 HOME 디렉터리를 썼습니다.

1단계: API Key를 만들고 Claude Code에 연결

  1. aicodewith.ai에 가입해 로그인한 뒤 왼쪽 내비게이션 바의 「키 관리」를 누릅니다.
  2. 「키 생성」을 누르고 알아보기 쉬운 이름(예: 「Claude Code 서브에이전트」)을 붙입니다.
  3. 전체 키를 바로 복사해 보관하세요. 대화 상자를 닫으면 전체 키는 다시 볼 수 없습니다. 자세한 내용은 API Key 생성 문서를 참고하세요.

API Key를 만들기 →

키를 ~/.claude/settings.json에 넣습니다.

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY"
  }
}

다른 연결 방법은 「Claude Code를 서드파티 API에 연결하는 방법」을 참고하세요.

2단계: 한동안 도는 작업 준비

데모 저장소는 작은 Python 프로젝트입니다. shop/에 파일 3개, tests/에 테스트 7개가 있고, 각 테스트의 setUp이 일부러 6초씩 기다려 전체 테스트가 한 번에 약 42초 걸립니다. shop/pricing.py에는 「10개 이상 할인」을 qty > 10으로 쓴 경계 버그를 넣어 두었습니다. Claude Code에서 다음을 보냅니다.

text
Use a general-purpose subagent in the background for a read-only review of this repo:
first run python3 -m unittest discover -s tests -v (about 45 seconds), then read every
file in shop/ and tests/ one by one, then run the test suite a second time, and finally
report each failing test with file:line, a one-line fix, and two other risks you notice.
The subagent must not edit any file. While it runs, just tell me it started.

3단계: 백그라운드 서브에이전트 상태 줄 보기

메인 세션은 곧바로 「시작했다」고 답하고, 입력창 아래에 서브에이전트 패널이 나타납니다. 같은 줄을 시간 순서대로 발췌하면 다음과 같습니다.

text
● Agent(Read-only repo review)
  ⎿  Backgrounded agent (↓ to manage · ctrl+o to expand)
✻ Waiting for 1 background agent to finish

  ● main
  ◯ general-purpose  Read-only repo review                 48s · ↓ 12.0k tokens
  ◯ general-purpose  Reading shop and test files        1m 10s · ↓ 14.0k tokens
  ◯ general-purpose  Re-running tests on test_shop.py   1m 40s · ↓ 14.1k tokens

● Agent "Read-only repo review" finished · 1m 46s

처음에는 작업 이름 「Read-only repo review」가 보이다가, 1분 10초에 「Reading shop and test files」, 1분 40초에 「Re-running tests on test_shop.py」로 바뀌었습니다. 간격은 정확히 약 30초였고 1분 46초에 끝났습니다. 테스트를 한 번만 돌린 다른 시도(서브에이전트가 메인 세션과 같은 Opus 5.5 사용)는 59초에 끝났고, 상태 줄은 작업 이름에서 「Preparing shop unittest discovery run」으로 바뀌었습니다.

서브에이전트의 최종 보고(발췌):

text
Tests: 7 ran and 1 failed. Both runs gave the same results, so nothing looks flaky.
Failing test: test_bulk_at_threshold (tests/test_shop.py:10)
- It expects 10 units at 1.0 to total 9.5, but the code returns 10.0.
- The cause is shop/pricing.py:3, which uses if qty > 10.
- Fix: change > to >= at shop/pricing.py:3.
Two other risks:
1. Overselling (shop/inventory.py:4-7): reserve() checks stock and then sets it with no lock.
2. Missing input checks (shop/cart.py:5, shop/cart.py:9).

보고한 shop/pricing.py:3과 >를 >=로 바꾸는 수정은 모두 맞았고, 파일은 하나도 바뀌지 않았습니다.

4단계: 상태 줄은 어떤 모델이 쓰나

API 앞에 모델 이름과 메시지 수만 기록하는 로컬 중계를 두고 확인했습니다.

시점요청모델보낸 대화출력
1분 10초 전후상태 갱신claude-haiku-5-5(서브에이전트 모델)서브에이전트 현재 대화 7개 메시지「Reading shop and test files」, 10토큰
1분 40초 전후상태 갱신claude-haiku-5-5(서브에이전트 모델)서브에이전트 현재 대화 8개 메시지「Re-running tests on test_shop.py」, 15토큰

즉 API Key로 ANTHROPIC_BASE_URL을 쓴 이번 테스트에서는 상태 갱신이 여전히 「서브에이전트의 현재 대화를 서브에이전트 자신의 모델에 보내는」 방식이었고, 공식이 설명한 이전 방식과 같았습니다. 공식은 새 방식이 대부분의 구독 사용자에게 적용됐다고 했고 API Key 연결은 언급하지 않았습니다. API Key 사용자에게 가장 직접적인 방법은 서브에이전트를 Haiku 5.5로 두는 것입니다. 그러면 작업과 상태 갱신이 모두 Haiku 5.5에서 돕니다.

서브에이전트 모델 설정 방법

Claude Code 서브에이전트 문서에 따르면 서브에이전트 모델은 다음 순서로 정해집니다.

  1. Claude가 그 호출에 넘기는 model 파라미터
  2. 서브에이전트 정의 파일의 model 필드(inherit는 메인 세션과 동일)
  3. 환경 변수 CLAUDE_CODE_SUBAGENT_MODEL
  4. 메인 세션의 모델

방법 1: 모든 서브에이전트의 기본 모델 지정

~/.claude/settings.json의 env에 한 줄을 추가합니다. 3단계 실측에 쓴 설정입니다.

json
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.aicodewith.ai",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-5-5"
  }
}

이 값은 「기본값」일 뿐입니다. 정의 파일에 model을 쓴 서브에이전트나 Claude가 호출 때 모델을 지정한 경우가 우선합니다. 이 변수만으로는 내장 Explore·Plan 서브에이전트의 모델도 바뀌지 않습니다.

방법 2: 특정 서브에이전트에 모델 지정

프로젝트의 .claude/agents/나 개인 ~/.claude/agents/에 Markdown 파일을 만듭니다.

markdown
---
name: test-runner
description: Runs the test suite and reports failing tests with file:line. Read-only.
tools: Read, Grep, Glob, Bash
model: haiku
effort: medium
---
Run the tests, read only the files you need, and report each failing test
with file:line and a one-line fix. Never edit files.

model에는 haiku, sonnet, opus, inherit 또는 claude-haiku-5-5 같은 전체 모델 ID를 쓸 수 있습니다. 더 자세한 읽기 전용 서브에이전트 작성법은 「Claude Code 서브에이전트를 Haiku 5.5로 설정하기」를 참고하세요.

방법 3: 모든 서브에이전트를 한 모델로 강제

json
{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1",
    "CLAUDE_CODE_SUBAGENT_EFFORT": "medium"
  }
}

CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1은 정의 파일의 model을 무시합니다(v2.1.257 이상). CLAUDE_CODE_SUBAGENT_EFFORT는 2.1.316에서 새로 추가됐고, 서브에이전트의 기본 effort를 메인 세션에서 물려받지 않고 따로 정합니다.

적용됐는지 확인

서브에이전트가 도는 동안 /tasks를 입력하고 선택하면 실제 모델이 보입니다. 실측 출력:

text
/tasks
  general-purpose › Read-only repo review
  1m 1s · 14.0k tokens · 8 tools · Haiku 5.5
  Progress
    Read(shop/cart.py)
    Read(shop/inventory.py)
    Read(shop/pricing.py)
    Read(tests/test_shop.py)
  › Bash(python3 -m unittest discover -s tests -v 2>&1; echo "EXIT=$?")

두 번째 줄 끝의 「Haiku 5.5」가 서브에이전트가 실제로 쓰는 모델입니다. Haiku 5.5와 Sonnet 5.5가 각각 어떤 일에 맞는지는 「Claude Haiku 5.5 vs Sonnet 5.5」를 참고하세요.

한도를 덜 쓰는 다른 방법

자주 묻는 질문

쓰려면 설정을 바꿔야 하나요?

공식은 v2.1.316 이상으로 업데이트하라고만 했고 새 스위치는 언급하지 않았습니다. AlphaSignal 보도에 따르면 설정 변경은 필요 없습니다.

서브에이전트가 Haiku로 바뀌나요?

아닙니다. 공식에 따르면 Haiku 5.5는 상태 줄만 쓰고, 서브에이전트는 설정한 모델로 일합니다. 서브에이전트 자체도 Haiku로 돌리려면 CLAUDE_CODE_SUBAGENT_MODEL을 설정하거나 정의 파일에 model: haiku를 쓰세요.

「99% 감소」와 「5% 감소」는 어떤 관계인가요?

99%는 상태 줄 갱신 한 번당, 5%는 세션 전체 한도입니다. 상태 갱신은 세션 전체에서 작은 부분이라 세션 기준으로는 약 5%를 아끼고, 같은 한도로 프롬프트를 약 6% 더 보낼 수 있습니다.

백그라운드 서브에이전트가 지금 무엇을 하는지 어디서 보나요?

입력창 아래 서브에이전트 패널에 백그라운드 서브에이전트마다 한 줄씩 상태, 경과 시간, 토큰 수가 나옵니다. ↓로 고르고 Enter로 기록을 열 수 있으며, /tasks에서 모델, 도구 호출, 진행 상황을 볼 수 있습니다.

API Key로 연결해도 새 방식이 적용되나요?

공식 게시물에는 Pro, Max, Ultra, Team, Enterprise만 나옵니다. API Key로 2.1.318을 실측했을 때 상태 갱신은 서브에이전트 모델을 따랐고, 서브에이전트를 Haiku 5.5로 두자 갱신도 Haiku 5.5에서 돌았습니다.

API Key를 만들고 Claude Code 백그라운드 서브에이전트 시작하기 →

관련 글

相关文章

Conductor 서비스 종료, 이제 어떻게? Conductor 없이 Claude Code / Codex 여러 개를 병렬 실행하는 git worktree 실전 가이드

Conductor 서비스 종료, 이제 어떻게? Conductor 없이 Claude Code / Codex 여러 개를 병렬 실행하는 git worktree 실전 가이드

Meta가 Conductor를 인수했습니다. 공식 발표에 따르면 Conductor Cloud는 11월 13일 읽기 전용으로 바뀌고 11월 20일 서비스를 종료하며 클라우드 데이터 삭제를 시작합니다. 로컬 Mac 앱은 2027년 초까지 업데이트됩니다. 이 글은 일정과 내보내야 할 것을 정리한 뒤, Conductor 없이 같은 일을 하는 방법을 소개합니다. 작업마다 git worktree 하나, worktree마다 Claude Code 또는 Codex 세션 하나, API Key 설정, 마지막으로 병합·검증·정리. claude --worktree, codex --worktree, 병합 충돌 실측과 Orca, Emdash, Claude Squad 같은 대체 도구도 담았습니다.

Postman이 Claude Code·Codex에 몰래 플러그인을 설치했다? 3단계 점검과 삭제(plugins, hooks, MCP, config.toml)

Postman이 Claude Code·Codex에 몰래 플러그인을 설치했다? 3단계 점검과 삭제(plugins, hooks, MCP, config.toml)

GitHub issue #14370과 The New Stack에 따르면 Postman 데스크톱 앱(macOS 12.33.4, 12.35.1)이 기존 사용자 업그레이드 과정에서 Claude Code와 Codex에 Postman 플러그인을 설치하고, ~/.codex/config.toml에 trusted_hash를 써서 자사 SessionStart 훅이 바로 실행되게 했습니다. 이 글은 경위와 Postman의 답변, Claude Code·Codex·Cursor 3단계 점검 명령, 공식 삭제 명령과 그 뒤에 남는 흔적, 그리고 Postman 공식 설치 프로그램을 격리된 디렉터리에서 실행한 재현 테스트를 정리합니다.

DeepSeek Harness Creator Mode 사용법: 설치, 서드파티 API 연결, 첫 플러그인 만들기 실측

DeepSeek Harness Creator Mode 사용법: 설치, 서드파티 API 연결, 첫 플러그인 만들기 실측

11월 2일 DeepSeek Harness 공식 계정이 Creator Mode를 소개했습니다. 원하는 도구를 한 문장으로 설명하면 에이전트가 플러그인을 작성하고 Harness에 설치한 뒤 로드됐는지까지 확인합니다. 이 글은 Creator Mode가 무엇인지, npx로 Harness를 실행하는 방법, OpenAI 호환 서드파티 API(aicodewith Base URL + Key)를 연결해 Claude, GPT, DeepSeek 모델을 쓰는 방법, Creator Mode로 todo_scan 플러그인을 만드는 과정을 실제 출력, 자주 나는 오류, Claude Code / Codex의 대응 방법과 함께 정리합니다.