서브 에이전트(Sub-agent)를 다루다 보면, 짧은 의뢰를 단 한 번 던졌을 뿐인데 입력과 캐시 생성의 합계가 수만 토큰 규모에 달하는 상황을 마주하게 됩니다. 감사를 해보니, 직전 1주일간의 실행 대부분에서 캐시 재사용이 이루어지지 않았습니다.

이때 가장 먼저 하고 싶어지는 것은 "절감률을 산출하는 것"입니다. 래퍼(Wrapper)를 적용하기 전후의 수치를 나열하며 몇 %가 줄었다고 말하고 싶어집니다. 하지만 그 절감률은 성립하지 않습니다. 나열된 수치의 비교 조건이 다르기 때문입니다. 모델도 다르고, 의뢰의 무게도 다르며, tools 구성도 hook 상태도 다릅니다. 단발적인 수치만을 나열한 절감률은 래퍼의 효과도, 설계의 효과도 아닙니다.

따라서 이 기사에서는 절감에 관한 이야기를 주제로 삼지 않습니다. 절감보다 감사, 즉 "왜 이번 한 번의 실행이 컸는가"를 나중에 추적할 수 있는 설계에 관한 이야기를 쓰겠습니다.

이 기사는 AI와의 협업을 통해 구성과 문장을 다듬었습니다. 감사 시점의 실측 로그를 1차 소재로 삼았으며, 사양은 공식 자료를 확인했습니다. 관측된 사실, 그로부터의 해석, 아직 증명되지 않은 것을 나누어 기록합니다. 해석과 최종 확인의 책임은 필자에게 있습니다.

필자

서브 에이전트란, 주역 AI로부터 다른 AI에게 업무 일부를 위임하기 위해 기동하는 워커(Worker)입니다. 여러 AI를 조합하면 조사와 구현, 집필과 리뷰와 같이 역할을 나눌 수 있습니다. 이번에 확인한 것은, 한 번의 기동으로 무엇이 읽히고, 어디에 상한이 설정되며, 무엇이 기록되는가 하는 점입니다.

결론부터 말씀드리겠습니다. 래퍼(이번에는 claude-worker.sh)는 프로필, 턴(Turn) 상한, 예산 상한, 정규 기동 경로를 통일하는 가드레일(Guardrail)로서 기능합니다. 목적은 절감이 아니라, 매 회차의 조건을 나중에 추적할 수 있도록 하는 것입니다. 절감 효과를 논하고 싶다면, 모델·의뢰·tools·hook 조건을 고정한 반복적인 A/B 비교를 별도로 구성해야 합니다.

짧은 의뢰임에도 왜 기동 시에 대량의 입력이 모이는가

짧은 의뢰일지라도, 그 의뢰를 해석하기 위한 시스템 지시(System Instruction), 프로젝트 규칙, hook, 추가 문맥 등이 기동 시에 모입니다. 본문이 작다고 해서 총량도 작다는 뜻은 아닙니다. Claude Code의 경우, 컨텍스트 윈도우(Context Window)의 공식 해설에 따르면 시스템 프롬프트(System Prompt)는 약 4,200토큰이며, 여기에 CLAUDE.md나 스킬 기술, MCP tool 이름 등이 매 세션 기동 시에 읽힙니다. 프롬프트를 한 줄 쓰기도 전에 이미 수천~수만 토큰이 채워져 있다는 전제입니다.

까다로운 점은, 화면상의 답변이 짧으면 이용자가 고정비(Fixed Cost)를 알아차리기 어렵다는 것입니다. "이 설계로 문제없는지 봐줘"라고 부탁하여 몇 단락의 답변이 돌아오면 가벼운 상담처럼 보입니다. 하지만 내부에서는 답변을 만들기 전에 대량의 입력을 읽고, 재사용할 수 없는 문맥을 캐시(Cache)로 다시 만들고 있을지도 모릅니다.

요리에 비유하자면, 차 한 잔을 주문할 때마다 주방을 새로 짓고 있는 것과 같습니다. 차의 양을 절반으로 줄여도 주방 건설비는 거의 변하지 않습니다. 프롬프트를 몇 줄 줄이는 것 자체가 무의미하지는 않지만, 먼저 기동 고정비를 확인하지 않으면 개선의 초점이 어긋나게 됩니다.

캐시 재사용이 없었던 이유도 단 하나로 결정되지 않습니다. 기동 경로, 읽어들이는 설정, 환경 변수, 추가 문맥, 병렬 실행 등이 후보입니다. 어느 하나만을 바꾼 비교가 없는 이상, 감사를 통해 발견된 재사용의 부족함만으로 원인을 단정할 수는 없습니다.

무엇을 기록해야 기동 비용의 정체를 볼 수 있는가

기동 비용의 정체를 추적하려면 의뢰문만으로는 부족합니다. 입력 토큰, 캐시 생성, 출력, model, tools, 작업 디렉토리, hook 조건, 종료 이유, 의뢰 완수 여부 등을 동일한 실행 단위로 묶어야 합니다. 후술할 현행 ledger는 이 정도까지 기록하고 있지 않습니다.

상담형과 구현형을 나누는 설계 자체는 의미가 있습니다. 필요한 도구도, 허용하는 턴 수도 다르기 때문입니다. 다만, 서로 다른 작업의 단발적인 수치를 나열하는 것은 프로필별 통상값이나 절감 효과가 될 수 없습니다.

비교 단위는 "저렴한 한 번"이 아니라 "동일한 의뢰를 완수한 한 번"입니다. 동일한 작업, 동일한 모델, 동일한 도구, 동일한 상한 내에서 성공과 실패를 포함하여 비교합니다. 이 조건을 갖추어야 비로소 입구를 바꿨을 때의 차이를 검토할 수 있습니다.

claude -p를 금지했는가

개선 전에는 호출하는 측에서 필요에 따라 claude -p 플래그를 선택할 수 있는 상태였습니다. -p는 대화 화면을 열지 않고 결과를 출력한 뒤 종료하는 비대화형(Non-interactive) 실행 방법입니다. 자동화에組み込み(組み込み, 포함)하기 쉬운 반면, 호출하는 측이 매번 옵션을 구성할 수 있게 되면 그곳에 재량(Discretion)이 남게 됩니다.

재량(Discretion)은 편리합니다. 급한 상담이라면 가볍게, 구현이라면 도구를 늘리는 식으로 그 자리에서 선택할 수 있습니다. 하지만 이용량을 관리해야 하는 상황에서는 그 편리함이 감사(Audit) 불가능의 원인이 됩니다. 어떤 날은 턴(Turn) 상한을 설정하고, 다른 날은 설정하는 것을 잊어버립니다. 예산 상한을 지정한 호출과 지정하지 않은 호출이 섞입니다. 로그를 남기는 경로와 남기지 않는 경로가 병존합니다. 이래서는 나중에 "왜 이 한 번만 비용이 컸는가"를 알 수 없습니다.

그래서 직접적인 claude -p 호출을 정규 경로에서 제외하고, claude-worker.sh라는 래퍼(Wrapper)를 경유하도록 일원화했습니다. 래퍼란 본체 명령어를 직접 호출하는 대신, 공통 설정이나 기록 처리를 사이에 끼워 넣는 얇은 입구입니다.

어떻게 일원화했는가 — 프로파일과 덮어쓰기 가능한 항목

claude-worker.sh는 선택한 프로파일(Profile)의 기본값을 읽고, --max-turns와 --max-budget-usd를 본체 명령어에 반드시 붙입니다. 호출 방식은 다음과 같습니다. 상한값은 각 환경의 실측치를 바탕으로 결정하는 것이므로, 본 기사에서는 구체적인 수치를 기재하지 않습니다.

claude-worker.sh consult "설계상의 우려 사항을 확인한다"
claude-worker.sh impl "대상을 편집하여 검증한다"

프로파일 이름은 허용된 후보와 일치하는지 가장 먼저 검사하며, 알 수 없는 이름일 경우 중단합니다. 외부에서 전달할 수 있는 것은 프로파일 이름과 요청 내용뿐만 아니라, model, max-turns, max-budget-usd, resume, cwd, effort, chrome, fresh-env, dry-run을 명시적으로 덮어쓸(Override) 수 있습니다. 임의의 알 수 없는 플래그를 그대로 통과시키는 것이 아니라, 래퍼가 나열한 항목만 받아들이는 설계입니다.

래퍼의 골격을 의사 코드(Pseudo-code)로 나타내면 다음과 같은 구조가 됩니다 (구현 그대로가 아닌 설계 의도의 발췌).

# 1. 프로파일 해결 (알 수 없는 이름은 즉시 중단)
case "$PROFILE" in
consult|impl|probe) ;;
...

상한값은 덮어쓸 수 있지만, --max-turns와 --max-budget-usd라는 정지 조건 그 자체는 실행 명령어에서 빠지지 않습니다. "호출 측은 작업의 종류만 선택한다"는 완전 고정 방식이 아니라, "프로파일의 기본값을 가지며, 허용된 항목만 덮어쓸 수 있다"가 정확한 설명입니다.

consult와 impl은 모델의 기분을 나타내는 이름이 아닙니다. 필요한 도구, 허용되는 턴 수, 예산 상한, 출력의 기대치를 묶어놓은 프로파일입니다. 호출 측은 프로파일을 선택하고, 필요하다면 래퍼가 허용한 항목만 덮어씁니다.

가드는仕組み(구조/메커니즘)로 담보한다

여기서 중요한 것은 가이드라인에 "반드시 래퍼를 사용할 것"이라고 적는 것만으로 끝내지 않았다는 점입니다. 자동화에서는 지켜야 할 규칙과 실제로 통과할 수 있는 경로가 별개라면, 언젠가 다시 생(raw) 명령어로 돌아가게 됩니다. 사람이 의도적으로 어기는 것뿐만이 아닙니다. 다른 AI가 오래된 예시를 읽고 이전의 호출 방식을 재현하는 것만으로도 발생합니다.

정규 경로를 하나로 만든다면, 생 호출을 막는 메커니즘과 래퍼를 통해서만 통과시키는 메커니즘이 필요합니다. 이번에도 제어되지 않는 생 호출은 계속해서 차단하면서, 래퍼를 정규 허가 채널로 취급하도록 가드(Guard)를 개편했습니다.

입구를 하나로 통일하면 개선해야 할 지점도 하나가 됩니다. 캐시 재사용을 노리는 설정을 변경할 때, 프로파일을 늘릴 때, ledger 항목을 추가할 때, 호출원을 일일이 찾아다닐 필요가 없습니다. 이용량 관리뿐만 아니라 향후 변경 비용도 낮아집니다.

종료 코드(Exit code)는 본체를 exec함으로써 그대로 호출 측으로 전달됩니다. 상한 도달이나 인증 실패를 래퍼가 성공으로 변환하는 일은 없습니다. headless 실행 시의 입구를 나타내는 환경 변수 CLAUDE_CODE_ENTRYPOINT=sdk-cli는 감사 시에 실측되었습니다. 워커 전용 처리 범위를 좁히기 위해 CLAUDE_WORKER=1도 사용하고 있습니다. 환경 변수는 문자열 하나를 추가하는 것뿐이지만, 일반적인 Codex 세션과 워커 실행에서 공유되는 훅(Hook)을 일률적으로 중단시키지 않기 위한 경계가 되었습니다. 입구의 이름을 결정하는 것뿐만 아니라, 하류(Downstream)의 처리가 해당 입구를 식별할 수 있는 것이 필요합니다.

턴 상한과 예산 상한은 왜 둘 다 필요한가

입구로 고정된 두 가지 정지 조건이 --max-turns와 --max-budget-usd입니다.

--max-turns

--max-turns는 AI가 도구를 사용하며 처리를 진행하는 횟수에 상한을 두는 플래그입니다. Claude Code의 공식 CLI 리퍼런스(Reference)에서는 print mode (-p)에서 사용할 수 있는 상한으로 설명되어 있으며, 기본값(default)으로는 상한이 없다고 명시되어 있습니다. 상한에 도달했을 경우, 아무 일도 없었다는 듯 성공 처리되어 반환되는 것이 아니라 에러와 함께 종료됩니다.

"기본적으로 상한이 없다"는 것이 무한히 계속 움직인다는 단정은 아닙니다. 일이 끝나면 통상적으로 멈춥니다. 다만, 운영 측에서 "이 종류의 상담은 몇 턴까지"라고 정해두지 않았다면, 정지 조건을 AI의 판단에만 맡기게 됩니다. 조사 대상이 늘어나거나 에러 수정이 계속될 때, 상담 목적이었던 호출이 구현(implementation) 수준만큼 커질 여지가 남습니다.

--max-budget-usd는 API 호출에 사용할 수 있는 금액의 상한을 두는 플래그입니다. 이 또한 공식 리퍼런스에서 print mode용 정지 조건으로 설명되어 있습니다. 여기서 다루는 것은 비용의 예측이 아니라, 실행 시점에 넘어서는 안 되는 경계입니다. 이 글에서는 모델별 단가 계산이나 엔화 환산은 하지 않습니다. 환경이나 계약에 따라 전제가 달라지기 때문입니다.

턴(turn) 상한만으로는 불충분합니다. 하나의 턴에 필요한 입력이 크다면, 적은 턴이라도 부담은 커집니다. 예산 상한만으로도 불충분합니다. 상한에 가까워질 때까지 몇 번이고 도구를 계속 사용한다면, 상담으로서는 너무 길어질 수 있습니다. 횟수와 총량은 서로 다른 축이므로, 양쪽 모두를 설정합니다.

모든 작업에 동일한 상한을 두는 것은 옳지 않습니다. 상담형과 구현형은 완료에 필요한 턴이 다릅니다. 상담용 상한을 구현에 적용하면 검증 전에 멈출 수 있습니다. 구현용 상한을 상담에 적용하면 짧게 끝날 작업에 너무 큰 여백을 주게 됩니다. 따라서 상한은 래퍼(wrapper)에 직접 작성하는 단일 값이 아니라, 프로파일(profile)과 한 쌍으로 구성합니다.

그림 보는 법: 정지 조건 (--max-turns와 --max-budget-usd)은 호출처마다 수동으로 설정하는 것이 아니라, 동일한 입구에서 부여됩니다. ledger (이중 테두리)에는 실행 전의 조건만 기록되며, 결과(토큰 수·비용·종료 코드)는 남지 않습니다. 이 기록이 실제로 본체 명령으로 전달되는 단계가 exec (이중 원) 단계입니다. 이 분리는 다음 절에서 다룹니다.

상한은 AI를 신뢰하지 않기 위한 벌칙이 아닙니다. 의뢰하는 측과 실행하는 측이 어디까지를 한 번의 작업으로 취급할지 합의하는 경계입니다. 경계가 있기 때문에 짧은 작업은 짧은 채로 끝나고, 큰 작업은 처음부터 구현형으로 다룰 수 있습니다.

현행 ledger는 이용량이 아니라 실행 전의 조건만 남긴다

네 번째 메커니즘이 ledger입니다. ledger는 일본어로 하면 대장(台帳)이며, 이번 운용에서는 ~/.claude/logs/claude-worker-ledger.jsonl에 한 줄씩 추가합니다. JSONL은 한 줄에 하나의 JSON 데이터를 쓰는 형식입니다.

현행 구현에서 저장하는 것은 실행 전의 7개 항목뿐입니다. 시각, profile, model, max_turns, 작업 디렉토리, prompt의 앞 100자, fresh_env 유무. 토큰 수, 비용, 종료 코드, 종료 이유, 성패, 결과 본문, 예산 상한은 저장하지 않습니다.

따라서 단발적인 수치들을 나열하여 절감률을 산출할 수는 없습니다. 현행 ledger로 알 수 있는 것은 어떤 조건으로 기동하려고 했는지까지입니다. 실행이 완료되었는지, 얼마나 이용했는지는 별도의 증거와 결합해야 합니다.

다음에 개선한다면, 실행 전의 한 줄과 대응하는 결과 기록을 추가합니다. 적어도 실행 ID, 입력·캐시 생성·출력의 이용량, 비용, 종료 코드, 종료 이유, 의뢰 완료 판정을 동일한 실행에 결합합니다. 거기까지 갖춰져야 비로소 동일한 조건의 반복 결과나 실패로 인한 재실행을 대장에서 비교할 수 있습니다.

항목을 늘리는 것 자체가 목적은 아닙니다. "이 한 번은 왜 컸는가", "같은 작업을 완수할 수 있었는가"에 답할 수 있는 범위로 좁힙니다. prompt 전문에는 기밀 정보나 개인 정보가 포함될 가능성이 있으므로, 결과 기록을 추가할 때는 저장 범위도 결정해야 합니다.

가볍게 만들수록 망가진다는 함정

기동 비용을 낮추는 작업에서는 "읽어오는 것을 줄이면 된다"는 방향으로 흐르기 쉽습니다. 불필요한 초기화를 줄이는 것은 유효합니다. 하지만 모든 초기화가 무의미한 것은 아닙니다.

구현 중, 최소 기동을 목표로 구현용 프로파일에 --bare를 넣은 실행은 "Not logged in"이 되어 작업을 시작할 수 없었습니다. --bare

--bare를 제거하고 재실행했을 때는 인증이 통과되었기에, 구현용 프로파일에서 이를 삭제했습니다. 저장된 기록을 통해 확인할 수 있는 것은 이 전후 관계까지이며, 내부의 어떤 인증 처리(authentication process)가 생략되었는지까지는 단정하지 않습니다.

숫자만 본다면, 인증 전에 멈추는 실행은 저렴해 보입니다. 하지만 그것은 처리를 완료하지 못한 것뿐입니다. 이용자가 원인을 조사하고, 다시 기동하여, 다른 경로를 시도한다면 오히려 총량은 늘어납니다. 값싼 실패를 양산하기보다, 필요한 초기화(initialization)를 남긴 단 한 번으로 끝내는 편이 안정적입니다.

훅(Hook)도 마찬가지입니다. 훅이란 기동이나 종료 등 특정 타이밍에 자동 실행하는 작은 처리입니다. headless, 즉 사람이 대화 화면을 지켜보지 않는 실행에서는 대화용 훅을 줄일 수 있는 경우가 있습니다. 다만, 동일한 훅이 다른 실행 환경에서 공유되고 있다면, 일률적으로 중단할 경우 일반적인 작업까지 바꿔버리게 됩니다.

이번에는 워커(Worker) 기동에 대한 훅의 가드(Guard) 대상을 좁혔습니다. headless라고 해서 모든 훅을 무효화한 것이 아니라, 입구를 식별하여 처리를 분기시키고 있습니다. 변경 후에는 훅의 테스트 스위트(test suite)가 통과하는 것과, 실제로 래퍼(Wrapper)를 경유한 headless 호출이 라이브로 동작하는 것을 확인했습니다. 이러한 검증은 래퍼와 가드가 동작한다는 증거일 뿐, 토큰 절감률의 인과 관계를 증명하는 증거는 아닙니다. 기능의 건전성 확인과 동일 조건에서의 효과 측정은 별개로 다룰 필요가 있습니다.

자신의 환경에서는 첫 번째 한 번을 어떻게 측정해야 하는가

갑자기 똑같은 래퍼를 만들 필요는 없습니다. 환경마다 불러오는 설정, 사용하는 모델, 계약, 프로젝트의 규모가 다릅니다. 먼저 자신의 현재 위치를 딱 한 번만 측정합니다.

첫 번째 의뢰로는 실무에서 자주 사용하는 작은 상담을 선택합니다. 벤치마크 전용의 인위적인 한 문장이 아니라, 평소라면 서브 에이전트에게 맡길 만한 내용입니다. 파일 편집이나 긴 조사를 동반하지 않는 것으로 합니다. 우선 기동 고정비를 보고 싶기 때문입니다.

그 한 번에 대해 입력, 캐시(Cache) 생성, 출력, 종료 이유를 저장합니다. 이용 중인 환경이 값을 반환한다면 그 값을 사용하고, 반환하지 않는다면 취득 방법을 먼저 확인합니다. 화면에 표시된 답변의 글자 수로 내부 토큰 수를 추측하여 채우지 않는 것이 중요합니다. 타인의 실측치를 자신의 환경 추정치로 그대로 유용하는 것도 피합니다.

다음으로 동일한 의뢰를 동일한 입구에서 다시 한번 실행하여, 캐시 재사용 상황을 비교합니다. 의뢰문뿐만 아니라 작업 디렉토리, 불러오는 설정, 추가하는 문맥(context), 이용하는 프로파일도 일치시킵니다. 두 번의 차이가 크다면 어떤 조건이 매번 바뀌고 있는지 추적합니다.

여기서 비로소 상담형 프로파일을 결정합니다. 필요한 도구만 남기고, --max-turns와 --max-budget-usd를 설정합니다. 상한값은 첫 실측값과 상담이 완료되기 위해 필요했던 범위 내에서 결정합니다. 누군가의 기사에 나온 값을 복사하면 업무의 무게가 다르기 때문에, 너무 엄격하거나 너무 느슨한 설정이 됩니다.

구현형도 같은 절차로 별도로 측정합니다. 구현은 파일을 읽고, 편집하고, 테스트하기 때문에 상담보다 커지는 것이 자연스럽습니다. 크다고 해서 실패라고 단정 짓지 말고, 상담과 동일한 입구를 유지한 채 상한만 넓히는 것도 아니라, 업무의 종류로서 분리합니다.

마지막으로 두 프로파일을 래퍼에 가두고, 정규 경로 이외의 것은 차단합니다. 이 순서라면 규칙을 먼저 정해서 업무를 망가뜨리는 것이 아니라, 현재의 업무를 측정하고 나서 경계를 만들 수 있습니다.

순서를 거꾸로 하지 말 것

상한을 정한 뒤에 측정하면 상한에 맞춘 결과밖에 보이지 않습니다. 래퍼를 만든 뒤에 측정하면 개선 전의 비교 대상을 잃게 됩니다. 첫 번째 한 번은 깔끔하지 않아도 괜찮습니다. 현재의 생(raw) 입구를 저장하기 위한 한 번입니다.

단 한 번의 차이만으로 성공이라고 단정 짓지 않는 것도 핵심입니다. 가벼운 상담이 우연히 빨리 끝나는 경우도 있고, 캐시가 우연히 재사용되는 경우도 있습니다. 동일한 입구에서 반복적으로 기록할 수 있는 상태를 먼저 만들고, 그 위에서 평소의 범위를 살펴봅니다. 개선 전의 한 번은 출발점이지, 영구히 고정할 기준이 아닙니다. 업무나 설정이 바뀌면 통상값도 업데이트해도 좋습니다.

비교용 한 번을 남길 때는 설정 파일을 통째로 공개할 필요도 없습니다. 나중에 동일한 조건을 판별할 수 있는 이름과 이용량, 종료 이유가 대응하고 있다면 개선의 출발점이 됩니다. 기밀 정보를 숨기기 위해 기록을 전부 버리는 것이 아니라, 재현에 필요한 식별 정보와 저장해서는 안 되는 본문을 분리합니다. 이 경계 또한 래퍼에 두면 호출 측마다 기록 방법이 흔들리지 않습니다.

입구 설계는 절약보다 감사의 이야기였다

서브 에이전트 (Sub-agent)는 사람이 건건이 감시하지 않아도 업무를 분담할 수 있다는 점에 가치가 있습니다. 하지만 기동할 때마다 플래그 (flag)를 선택하고, 이상 발생 시 로그 (log)를 찾아 헤매며, 상한선 (limit) 설정을 잊지 않았는지 확인해야 한다면, 이용자가 다시 병목 (bottleneck) 현상이 됩니다.

AI 워커 (AI worker)의 소비량에 위화감이 느껴진다면, 우선 한 번의 입력, 캐시 (cache) 생성, 출력, 종료 사유, 완료 판정을 동일한 기록으로 남깁니다. 그다음 조건을 고정하여 반복하며, 콜드 캐시 (cold cache)와 웜 캐시 (warm cache)를 구분합니다. 여기서 얻어야 할 것은 단발적인 숫자가 아니라, 비교 조건과 완료 조건을 통일하는 절차입니다.

Discussion