Claude Code 2.1.292: 서브에이전트의 비용과 속도를 다이얼처럼 조절한다

다중 에이전트를 쓸 때 가장 아픈 부분은 청구서다.

큰 작업을 잘게 쪼개 여러 에이전트가 병렬로 처리하면 속도는 올라가지만 토큰 비용도 같이 올라간다. 간단한 파일 목록 정리에 최고 성능 모델을 붙이는 건 스포츠카로 마트 주차장을 도는 것과 다를 바 없다. Claude Code 2.1.292는 이 문제를 effort 파라미터 하나로 해결한다.

1. effort 파라미터: 5단계 성능 다이얼

Agent 도구 호출 시 effort 값을 지정할 수 있게 됐다. 선택지는 다섯 가지다: low, medium, high, xhigh, max.

Agent({
  description: "파일 목록 요약",
  prompt: "src/ 디렉토리 파일명만 나열해줘",
  effort: "low"
})

Agent({
  description: "보안 취약점 심층 분석",
  prompt: "인증 로직 전체를 OWASP 기준으로 감사해줘",
  effort: "max"
})

low는 빠르고 저렴하다. max는 느리고 비싸지만 정확하다. 태스크 성격에 맞는 단계를 골라 쓰면 품질 손실 없이 비용을 줄일 수 있다.

2. 우선순위 계층 — 어느 값이 이기나

같은 에이전트에 여러 곳에서 effort가 설정될 때 적용 순서:

1. CLAUDE_CODE_EFFORT_LEVEL 환경 변수 (무조건 최우선)
2. Agent 도구 호출 시 전달하는 effort 파라미터
3. 서브에이전트 정의 frontmatter의 effort 설정
4. 부모 세션의 기본값 (없으면 medium)

팀 관리자라면 환경 변수로 조직 전체 상한을 걸어 놓을 수 있다. 개발자가 코드에서 아무리 max를 지정해도 환경 변수가 medium이면 그게 최우선이다.

3. 실전 전략: 2단계 파이프라인으로 비용 절반 줄이기

// 1차: 관련 없는 파일 빠르게 걸러내기
const scan = await Agent({
  description: "빠른 파일 스캔",
  prompt: "변경된 파일 목록에서 테스트 파일만 분류해줘",
  effort: "low"
})

// 2차: 핵심만 깊게 분석
const review = await Agent({
  description: "코드 리뷰",
  prompt: `이 파일들을 심층 검토해줘: ${scan.result}`,
  effort: "high"
})

단순 분류·목록 조회처럼 "틀려도 금방 알 수 있는" 작업에는 low를, 보안 감사·최종 코드 리뷰처럼 "한 번 놓치면 큰일 나는" 작업에는 max를 쓰는 것이 기본 원칙이다.

4. plugin install --marketplace: 한 줄 설치

같은 버전에서 claude plugin install 명령에 --marketplace 플래그가 추가됐다.

기존 방식 (2단계):

claude marketplace add
claude plugin install my-plugin

새 방식 (1단계):

claude plugin install my-plugin --marketplace

마켓플레이스가 아직 등록되지 않은 환경에서도 이 플래그 하나면 자동으로 마켓플레이스를 추가하고 곧바로 설치까지 진행한다. 새 팀원 온보딩 스크립트나 CI/CD 파이프라인에서 특히 유용하다.

5. 알려진 버그: --max-budget-usd 오버슈팅

커뮤니티 보고에 따르면 이번 버전에서 --max-budget-usd로 설정한 예산 상한이 드물게 초과되는 버그가 발견됐다. 예산 민감 환경에서는 추가 모니터링을 병행하거나 다음 패치를 기다리는 것이 안전하다.

활용 팁

• 팀 차원 비용 관리: .claude/settings.json에서 서브에이전트 기본 effort를 medium으로 설정하고, 필요한 에이전트만 명시적으로 high나 max를 요청하게 만들면 예상 외 토큰 폭탄을 막을 수 있다.
• 교육 환경 응용: 학생 과제 1차 검토 에이전트는 low로 충분하고, 최종 평가 에이전트만 high로 설정하면 비용이 크게 줄어든다. 에듀테크 플랫폼 운영 비용 관리에 즉시 적용 가능하다.
• CI 자동화: --marketplace 플래그를 빌드 스크립트에 추가하면 새 환경 세팅 시간이 단축되고 수동 실수도 줄어든다.
• 부분 적용: 모든 에이전트를 바꾸지 않아도 된다. effort를 지정하지 않으면 기존처럼 medium으로 동작하므로, 비용이 특히 크게 나오는 에이전트부터 조금씩 최적화하면 된다.

Sources:

• Claude Code changelog
• Create custom subagents - Claude Code Docs
• AI CLI Tools Digest 2026-10-07 · agents-radar
• Adopt Claude Code 2.1.292 · hermitd issue #1164
• Feature: configurable reasoning effort level for subagents · anthropics/claude-code #43083