muaco Tech Note

Claude Codegithub.com

Claude Code 서브에이전트 effort 설정추론 깊이로 비용과 속도 맞추기

Claude Code 서브에이전트마다 effort 단계를 정해, 간단한 일은 빠르고 싸게, 어려운 일은 깊게 맡길 수 있습니다.

안녕하세요, muaco입니다.

이 글로 할 수 있는 일

Claude Code 서브에이전트마다 생각의 깊이를 따로 정할 수 있게 됩니다. 쉬운 심부름은 얕게 시켜 빨리 끝내고 어려운 일만 깊게 맡겨 비용을 아낍니다.

방법은 두 가지입니다. 한 번만 바꿀 때는 말로 부탁하고 매번 같은 단계로 돌릴 때는 서브에이전트 정의 파일에 적습니다. 기준 버전은 v2.1.292입니다.

서브에이전트란 무엇일까요? 팀장이 일을 쪼개 팀원에게 맡기듯, Claude가 일부 작업을 따로 떼어 맡기는 보조 실행자입니다.

미리 갖춰야 할 준비물

  • Claude Code v2.1.292 이상. 이 버전에서 Agent 도구에 effort 파라미터가 생겨 서브에이전트를 부를 때 말로 단계를 정할 수 있게 됐습니다. 정의 파일에 적는 방식이 언제 생겼는지는 릴리스 노트에 따로 나와 있지 않습니다.
  • effort를 지원하는 모델. Opus 5.5, Sonnet 5.5, Opus 4.7 등은 low부터 max까지 다섯 단계를 씁니다. Opus 4.6과 Sonnet 4.6에는 xhigh가 없습니다.
  • 터미널. CLI(터미널에 명령을 쳐서 쓰는 방식)로 Claude Code를 엽니다.

단계별 쓰임새는 공식 문서가 이렇게 나눕니다.

단계어울리는 일
low결과를 매번 직접 보는 가벼운 일. 아이디어 내기, 이름 바꾸기
medium범위가 분명한 일상 작업. Opus 5.5와 Sonnet 5.5의 기본값
high검증이 중요하고 예외 상황이 많은 일. 기존 코드의 버그 고치기
xhigh토큰을 더 쓰더라도 더 깊게 생각해야 하는 일
max사람 손 없이 끝까지 파고들 어려운 문제. 보안 취약점 찾기

문서는 단계가 낮을수록 빠르고 싸다고 설명합니다. 다만 max는 들인 만큼 나아지지 않고 생각이 지나치게 길어질 수 있으니, 넓게 쓰기 전에 시험해 보라고 합니다.

따라 하기: 단계 정하기

준비: 버전 확인

따라 하기
  1. 터미널에서 claude -v를 입력하세요. 숫자가 2.1.292 이상이면 다음 단계로 넘어갑니다.
  2. 그보다 낮으면 claude update로 올립니다. 끝나면 claude -v를 다시 쳐서 숫자가 바뀌었는지 봅니다.

한 번만: 말로 부탁하기

따라 하기
  1. 작업할 폴더에서 claude를 입력해 세션을 엽니다. 입력창이 뜨면 준비가 끝났습니다.
  2. 서브에이전트 이름과 단계를 함께 적어 부탁하세요. 예: code-reviewer 서브에이전트를 effort low로 돌려서 최근 변경을 훑어봐 줘. 이름 자리에는 이미 만들어 둔 서브에이전트 이름을 넣습니다. 아직 하나도 없다면 6~7단계로 먼저 만들고 돌아오세요. 릴리스 노트에 따르면 Claude는 요청한 단계로 서브에이전트를 실행합니다.
  3. 어려운 일이면 단계를 올려 부탁합니다. 예: 보안 점검은 effort high로 맡겨 줘. 같은 서브에이전트라도 일의 무게에 맞춰 공을 달리 들이게 하려는 단계입니다.

늘 같은 단계로: 정의 파일에 적기

따라 하기
  1. 프로젝트 폴더 안에 .claude/agents/ 폴더를 만드세요. 이 프로젝트에서만 쓰려면 여기, 모든 프로젝트에서 쓰려면 ~/.claude/agents/에 둡니다.
  2. 같은 이름의 파일이 이미 있다면 새로 만들지 말고 그 파일에 한 줄만 더하세요. 덮어쓰면 원래 설정이 사라집니다. 새로 만든다면 quick-searcher.md라는 파일에 아래 내용을 넣습니다. 
    ---
name: quick-searcher
description: 파일에서 특정 문구나 설정 위치를 빠르게 찾아 줍니다
tools: Read, Grep, Glob
effort: low
---

    요청받은 문구가 어느 파일 몇째 줄에 있는지 찾아 목록으로 알려 줍니다.
    name과 description만 꼭 필요하고 effort는 넣지 않으면 세션 단계를 그대로 따릅니다.

  3. 세션에서 @agent-quick-searcher를 붙여 일을 맡기세요. 이름을 직접 부르면 Claude가 다른 서브에이전트를 고르지 않고 이 서브에이전트를 실행합니다.
  4. 실행 중에 /tasks를 입력해 확인합니다. 서브에이전트 줄에 모델 이름과 함께 effort 단계가 보이면 성공입니다.

막히기 쉬운 네 군데

단계를 말했는데 달라진 게 없어 보입니다

무엇이 보이나: effort를 적어 부탁했는데 평소와 같은 속도로 돌아갑니다. 왜 그런가: 이 기능은 v2.1.292에서 추가됐습니다. 어떻게 하나: claude -v로 버전을 보고, 낮으면 claude update 후 세션을 다시 엽니다.

정의 파일의 effort가 무시됩니다

무엇이 보이나: effort: low를 적었는데 다른 단계로 돕니다. 왜 그런가: 정의 파일의 effort는 세션 단계보다 앞서지만 CLAUDE_CODE_EFFORT_LEVEL 환경 변수보다는 뒤입니다.

어떻게 하나: 터미널에서 이 환경 변수가 설정돼 있는지 확인하세요. macOS·리눅스는 echo $CLAUDE_CODE_EFFORT_LEVEL, 윈도 PowerShell은 echo $env:CLAUDE_CODE_EFFORT_LEVEL을 입력합니다. 빈 줄이 나오면 설정이 없는 상태입니다. 값이 나왔는데 회사 PC라면 관리자가 넣어 두었을 수도 있으니 지우기 전에 물어봅니다.

xhigh가 먹히지 않습니다

무엇이 보이나: xhigh를 골랐는데 기대한 깊이가 나오지 않습니다. 왜 그런가: 쓸 수 있는 단계는 모델마다 다르고 Opus 4.6과 Sonnet 4.6에는 xhigh가 없습니다. 모델이 지원하지 않는 단계를 고르면, 그 단계 이하에서 지원되는 가장 높은 단계로 내려 돌립니다. Opus 4.6에서 xhigh를 고르면 high로 도는 식입니다.

어떻게 하나: 지금 쓰는 모델을 확인하고 그 모델이 지원하는 단계 안에서 고르세요.

세션 전체가 느려졌습니다

무엇이 보이나: 서브에이전트만 바꾸려 했는데 대화 전체가 무거워졌습니다. 왜 그런가: claude --effort high처럼 실행할 때 붙이는 --effort는 세션 전체의 단계를 정합니다. 서브에이전트 하나만 바꾸는 설정과 다릅니다.

어떻게 하나: 세션은 기본값으로 두고 서브에이전트에만 말이나 정의 파일로 단계를 주세요.

여기서 더 나아가려면

자주 맡기는 일을 무게별로 나눠 보세요. 찾기·요약은 low, 점검·수정은 high로 서브에이전트를 따로 두면 매번 말할 필요가 없습니다. 정의 파일의 model 칸에 haiku나 sonnet을 함께 적으면 모델까지 일에 맞출 수 있습니다.

이상으로 글 마치겠습니다.

출처

#Claude Code#서브에이전트#effort 파라미터#추론 깊이#비용 최적화#Agent 도구#v2.1.292

같은 분류의 글