당사(주식회사 Joinclass)에서는 launchd에 등록된 30개 이상의 작업을 야간 및 주간에 claude -p를 호출하고 있습니다. 기사 생성, 아침 요약본 작성, 부서별 백로그 처리 등이 그 예입니다.
2026년 9월에 재고 조사를 하던 중 문제가 있다는 것을 알게 되었습니다.
- 비용을 기록했던 것은 11종류의 스크립트 중 단 한 종류뿐이었습니다. - 게다가 그마저도,
0.02라는 고정된 추정치를 더하는 수준에 불과했습니다. 실제 측정 결과는 '2+2는?'이라는 질문만 하는 1회 호출에도 $0.27~$0.47가 소요되고 있었습니다.
즉, 실제 소비량을 아는 사람이 아무도 없었던 것입니다. 본문에서는 이후 구현한 측정 시스템을 기반으로 소개합니다. 작업 단위 및 모델 단위로 토큰 수, 소요 시간, 실패율을 집계합니다.
절차는 세 단계입니다.
claude -p를 공통 래퍼(wrapper)를 통해 호출하고, --output-format json의 결과를 기록합니다. - 기록 측에서 모델별, 작업별, 일자별로 누적하여 쌓습니다.
- 집계 스크립트를 사용하여 '부하가 큰 작업', '실패하기 쉬운 작업'을 찾아냅니다.
우선 직접 한 번 시도해 보시기 바랍니다.
claude -p "2+2는?" --output-format json | jq '{
is_error, duration_ms, duration_api_ms, num_turns, total_cost_usd,
usage: .usage | {input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens},
...
}'
측정에 사용되는 필드는 다음과 같습니다.
| 필드 | 용도 |
|---|
duration_ms / duration_api_ms | 전체 소요 시간과 그중 API 대기 시간 |
num_turns | 도구 호출을 포함한 왕복 횟수 (루프 폭주 감지에 사용) |
usage.*_tokens | 입력/출력/캐시 생성/캐시 읽기 토큰 수 |
modelUsage | 실제로 사용된 모델별 내역 (fallback이 작동했는지 여부도 여기서 파악 가능) |
is_error | 실패 플래그. 종료 코드와는 별도로 확인해야 함 |
permission_denials | 도구가 거부된 기록. 응답 자체는 '성공'으로 반환됨 |
제가 처음에 놀랐던 것은 cache_creation_input_tokens의 크기였습니다. 1회 호출만으로 약 41,000 토큰의 캐시를 만들고 있었습니다. 그중 당사(自社)의 CLAUDE.md 및 에이전트/스킬이 차지하는 비중은 5,800토큰 정도였으며, 나머지는 Claude Code 측의 고정 오버헤드였습니다. 프롬프트를 줄여도 효과가 미미했고, 호출 횟수를 줄이는 것만이 효과적이라는 것을 알게 된 것이 이 수치를 보고 난 후였습니다.
각 스크립트에 직접 claude -p를 작성하면 측정 누락이 발생합니다. 그래서 lib/claude-run.sh 파일을 만들고, 모든 작업을 이 함수를 통해 대체했습니다. 실제로 운영 중인 코드입니다 (사무실 화면 알림 등 측정과 무관한 부분은 생략했습니다).
#!/bin/bash
# 사용법:
# source .company/scripts/lib/claude-run.sh
...
호출 측의 변경은 단 1줄입니다.
# Before
RESULT=$(claude -p "$PROMPT" --model sonnet)
# After
...
① PIPESTATUS를 확인하지 않으면 실패율이 0%가 됩니다
claude ... | python3 record-cost.py와 같이 작성하면, $?는 Python의 종료 코드가 됩니다. Claude가 다운되어도 Python은 정상 종료하기 때문에, 모든 작업이 성공으로 처리되고 있었습니다. 2026년 11월에 이를 인지하고, 위와 같이 PIPESTATUS[0]를 우선하는 방식으로 수정했습니다. 실패율을 측정하는 시스템 자체가 실패를 숨기고 있었다는 황당한 상황이었습니다.
② --fallback-model을 붙이면 모델명으로 집계할 수 없게 됩니다
주요 모델이 섞여 있으면, 작업은 다운되지 않고 Sonnet으로 완주합니다. 감사한 기능이지만, --model
전달된 값으로 집계하면 실제와 차이가 생깁니다. 반드시 modelUsage 키로 계산해야 합니다.
③ --max-budget-usd는 폭주 방지용(runaway prevention)으로 사용합니다.
당사는 CLI의 정액제 플랜을 사용하므로, 금액은 참고치입니다. 그럼에도 불구하고 --max-budget-usd 3은 유지하고 있습니다. 통상적인 실측 비용이 1회 $0.02 전후이기 때문에, 평소 운영 환경에서는 이 기능이 발동되지 않습니다. 이는 도구 호출(tool call)이 루프에 빠졌을 때만 작동하는 안전장치입니다.
record-cost.py는 표준 입력(stdin)으로부터 JSON을 받습니다. 응답 텍스트는 표준 출력(stdout)으로 그대로 흘려보내고, 측정된 값은 cost-tracker.json에 누적합니다. 아래 코드는 실제 운영 코드에서 집계 부분만 추출하여 이번 주제에 맞춰 소요 시간과 토큰 수를 추가한 것입니다.
"""claude --output-format json | record-cost.py <작업명>"""
import datetime, json, os, pathlib, sys
...
실제 운영 버전에는 이 외에 다음 두 가지 기능도 포함되어 있습니다.
permission_denials를 1건당 1줄씩 claude-run.err에 기록합니다. 도구 거부(tool rejection)는 응답이 성공으로 처리되는 상태에서 조용히 발생하기 때문에, 로그로 남기지 않으면 인지하기 어렵습니다.
is_error가 참(true)이고 본문에 usage limit 등이 포함되어 있다면 .usage-limited라는 표시 파일을 생성합니다. 이 래퍼(wrapper)는 이를 감지하여 호출을 60분 동안 중단하고 Slack으로 알림을 보냅니다.
COST_FILE은 환경 변수로 대체할 수 있도록 되어 있어, 가짜 JSON만 흘려보내도 동작 확인이 가능합니다.
export COST_FILE=$(mktemp)
echo '{"result":"ok","is_error":false,"duration_ms":4200,"total_cost_usd":0.03,
"usage":{"input_tokens":12,"output_tokens":80,"cache_creation_input_tokens":41000}},
...
calls: 2, errors: 1, duration_ms_max: 90000과 같은 값이 기록되었다면 성공입니다. 당사는 이를 record-cost.test.py로 만들어 단위 테스트(unit test)를 진행하고 있습니다.
마지막으로, 누적된 JSON 데이터를 표 형태로 만듭니다. 이는 jq만으로 작성할 수 있습니다.
#!/bin/bash
F="${1:-.company/scripts/cost-tracker.json}"
...
출력은 다음과 같은 형태가 됩니다 (수치는 설명용으로 반올림된 것입니다).
job calls fail% avg_s max_s out_tok cache_tok models
idle-marketing 310 3 95 540 410000 12700000 opus-5-5=290,sonnet-5-5=20
auto-replenish 30 0 240 600 260000 1300000 opus-5-5=30
...
-
앞서 언급했듯이 고정 오버헤드가 대부분이므로, 먼저 호출 횟수를 줄이는 방안을 고려합니다. 당사에서는 10분 간격으로 실행하던 부서 작업을 '백로그에 작업이 있을 때만 호출'하도록 변경한 것이 가장 효과적이었습니다.
-
cache_tok가 큰 작업 = 호출 횟수가 많은 작업입니다. 이는 주 모델이 혼잡한 시간대에 실행됩니다. 야간 실행 시간을 조정할 후보군입니다.
-
models에 폴백(fallback) 모델이 섞여 있는 작업입니다.
-
특정 작업은 도구 호출 루프에 빠지거나 타임아웃 직전일 수 있습니다. max_s가 avg_s의 5배 이상이라면, num_turns도 함께 기록하면 원인을 좁히기 쉽습니다.
-
fail%는 0인데 결과물이 나오지 않는 경우, claude-run.err에서 permission_denied 라인을 확인해 주십시오. 당사에서는 이 패턴이 가장 많았습니다.
-
최종적으로 claude -p를 --output-format json으로 호출하고, duration_ms, usage, modelUsage, is_error 등을 측정합니다.
기록한다 - 모든 작업을 공통 래퍼(wrapper)를 통과시킨다.
PIPESTATUS
을 확인하지 않으면 실패율이 0%로 나타날 수 있다. 모델명은 --model의 값이 아니라, modelUsage 키로 계산해야 한다. 집계해 보면, 줄여야 할 것은 '프롬프트 길이'보다 '호출 횟수'라는 것을 알 수 있다.
경영진의 관점에서 볼 때, 이 측정 지표를 도입한 후에야 비로소 "어떤 업무에 AI를 몇 번 사용하고 있는지"를 숫자로 이야기할 수 있게 되었습니다. 'AI에게 맡기고 있다'고 감으로 말하던 시기는 사실 아무도 내부 내용을 제대로 확인하지 않았던 것입니다. 우선 래퍼(wrapper) 하나와 jq 하나부터 시작해 보세요.
launchd / cron으로 Claude Code를 무인 실행하는 메커니즘(래퍼, 모니터링, 자가 복구)은 『Claude Code 완전 자동화 바이블』에 정리되어 있습니다. 캐시나 비용 효율성을 CLAUDE.md 측면에서 다듬고 싶은 분께는 『CLAUDE.md 설계 패턴』을 추천합니다.
도서 목록: https://zenn.dev/joinclass?tab=books
회사 내부에서 비슷한 시스템을 만들고 싶지만 시간이 부족하다면, 합동회사 Join Class에서 중소기업 대상 업무 시스템 개발 및 DX 지원(국내) 서비스를 제공하고 있습니다.
👉 업무 시스템·DX 무료 상담