당사(주식회사 Joinclass)는 Claude Code를 launchd에서 17개 이상의 작업으로 구동하며, 개발, 출판, 마케팅, 영업, 경리, 법무 등 각 부서를 AI 에이전트에게 맡기고 있습니다. Claude는 CLI의 정액 플랜(Max, 월 약 2만 엔)이기 때문에 청구 금액은 늘어나지 않습니다. 그럼에도 불구하고 사용량 상한선에는 도달합니다.
실제로 2026년 11월 15일~16일, 영업 부서의 작업이 주간 사용량 상한에 도달했습니다. 매분 구동하고는 4초 만에 실패하는 동작을 약 1,000회 반복했기 때문입니다. 이 사실을 알게 된 계기는 본문에서 소개할 집계 과정 덕분이었습니다.
본문에서는 claude -p 호출 전체를 하나의 래퍼(자체 경량 LLM 게이트웨이)로 통과시키고, 측정된 비용을 JSON에 쌓아 부서별/작업별 보고서를 생성하는 전 과정을 당사에서 실제로 사용하고 있는 코드를 그대로 소개합니다.
대상 독자: Claude Code를 cron / launchd / CI 등에서 여러 개 구동하여 어떤 작업이 할당량을 차지하고 있는지 알고 싶은 사람
읽고 나면: 래퍼 코드 1개와 집계 스크립트 1개(총 약 150줄)만으로 그날짜 기준으로 월간 사용량 보고서를 만들 수 있습니다.
각 작업(.sh) ──► claude_run <라벨> ──► claude -p --output-format json
│
▼
...
핵심은 라벨 명명 규칙입니다. idle-sales나 dept-dev처럼 '종류-부서' 형태로 지정해 두면, 나중에 정규 표현식 하나로 부서별로 모을 수 있습니다.
모든 작업은 claude를 직접 호출하지 않고, lib/claude-run.sh의 claude_run 함수를 거칩니다. 실제 코드에서 핵심 내용만 추출한 것입니다.
claude_run() {
local label="$1"; shift
claude -p --output-format json \
...
}
호출하는 쪽은 다음과 같이 작성하기만 하면 됩니다.
source "$(dirname "$0") / lib/claude-run.sh"
claude_run idle-sales "오늘의 계획표에 따라 영업 부서 업무를 하나 진행해 줘" > out.md
함정 1: PIPESTATUS
claude ... | python3 record-cost.py
이 종료 코드는 Python의 것이 됩니다. 그대로 두면 Claude가 실패했더라도 rc=0으로 인식되어 작업 모니터링 시스템에서 감지하지 못합니다. 반드시 PIPESTATUS[0]을 우선하여 반환해야 합니다. --output-format json을 사용하면 응답 끝에 다음과 같은 JSON이 반환됩니다(사용할 필드만).
{
"result": "응답 텍스트",
"is_error": false,
...
}
이 데이터를 받아 텍스트는 stdout으로 그대로 흘려보내고, 숫자 정보만 추출하여 누적하는 것이 record-cost.py의 역할입니다. 아래는 실제 코드에서 집계와 관련된 부분만 추출한 것입니다.
DEFAULT_COST_FILE = pathlib.Path(__file__).resolve().parents[1] / "cost-tracker.json"
def main():
label = sys.argv[1]
...
설계 시 주의를 기울인 점은 세 가지입니다.
- JSON이 아니면 통과: CLI의 버전 차이나 오류로 인해 JSON이 반환되지 않더라도, 작업 본래의 출력물(output)은 손상시키지 않습니다.
- 월별 자동 로테이션:
cost-tracker-2026-10.json처럼 전월 파일을 남겨둡니다. 이를 통해 전월과의 비교가 가능합니다.
- 테스트 시 파일 지정: 테스트 과정에서 실제 JSON을 오염시키지 않도록,
COST_FILE을 환경 변수로 대체할 수 있습니다.
함정 2: 상한 초과 메시지는 한 가지가 아니다
처음에는 usage limit만 추출했습니다. 그런데 실제로 반환된 것은 "You've hit your weekly limit"였고, 이를 감지하지 못했습니다. 그래서 hit your .*limit을 추가하여 수정했습니다.
함정 3: total_cost_usd는 정액 플랜에서는 참고 값이다
Max 플랜의 경우 청구 금액이 아니라 'API로 환산하면 얼마인지'를 나타내는 값입니다. 다만, 작업 간 비교 목적으로 사용합니다.
가중치(Weight) 측면에서는 충분히 활용할 수 있습니다. 저희는 금액으로 제한하지 않고, 상한 오류(limit error)만으로 중단시키고 있습니다.
여기부터가 본격적인 집계 내용입니다. 외부 라이브러리는 사용하지 않고 표준 라이브러리만으로 작성했습니다.
#!/usr/bin/env python3
"""cost-tracker.json을 부서별・작업별로 집계합니다. 사용법: cost_report.py [cost-tracker.json]"""
import json
...
실행 방법은 다음과 같습니다.
python3 cost_report.py .company/scripts/cost-tracker.json
# 지난달과 비교하고 싶을 때
python3 cost_report.py .company/scripts/cost-tracker-2026-10.json
저희가 실제로 얻은 결과입니다. 금액 자체는 정액 플랜에서는 의미가 적기 때문에, 비율로 보고 있습니다.
| 부서 | 횟수 | 비율 | 오류율 |
|---|
| common (대화・CEO 대리 등) | 287 | 69.5% | 2.1% |
| ... | | | |
| 작업(Job) | 횟수 | 비율 | 캐시 생성 토큰/회 |
| --- | --- | --- | --- |
| office-chat | 45 | 62.1% | 101,623 |
| idle-dev | 359 | 7.5% | 26,200 |
| idle-publishing | 426 | 5.0% | 29,133 |
| ceo-proxy | 131 | 4.4% | 57,756 |
| idle-sales | 794 | 2.5% | 7,589 |
표를 보고 다음 두 가지에 주목했습니다.
영업부(idle-sales)는 오류율이 74.9%입니다. 게다가 호출 횟수는 가장 많습니다. 1회당 캐시 생성 토큰도 7,589로 극단적으로 적습니다. 이는 '일을 시작하기 전에 상한 오류로 중단되는' 형태입니다. 상한에 도달하여 공회전하는 루프는 여기서 발견했습니다.
- 슬롯의 60%가 단지 45번만 호출된 대화(office-chat)에서 사용되고 있습니다. 1회당 10만 토큰급 캐시를 만들고 있었습니다. 자동 작업을 줄이는 것보다, 대화 세션의 컨텍스트를 가볍게 만드는 것이 효과적입니다.
그 후, 부서를 매분 실행하는 방식을 버리고, 아침에 짜는 일일 계획표대로 움직이도록 변경했습니다(2026-11-16).
COST_FILE
을 임시 파일로 지정하고 더미 JSON을 주입합니다.
export COST_FILE=$(mktemp)
echo '{"result":"ok","total_cost_usd":0.1,"usage":{"cache_creation_input_tokens":100}}' \
| python3 lib/record-cost.py idle-sales
...
확인해야 할 3가지 사항은 다음과 같습니다.
- 첫 번째 줄의 stdout에
ok
만 출력되는지 (텍스트가 그대로 통과되었는지) -
jobs.idle-sales.errors
이 1로 설정되어 있는지 (상한 문구 케이스에서)
logs/.usage-limited
이 생성되었는지
| 증상 | 원인 | 대처 |
|---|
| 집계가 늘지 않음 | 작업(Job)이 claude를 직접 호출함 | grep -rn "claude -p" scripts/로 호출을 찾아내어 모두 claude_run으로 통합합니다. |
부서가 common에 편중됨 | 라벨이 명명 규칙에서 벗어남 | ALIASES에 목적지를 추가하거나, 라벨 이름을 수정합니다. |
| JSON이 손상됨 | 병렬 작업(Parallel Job)이 동시에 쓰기함 | 동시 실행이 많다면 fcntl.flock으로 배타적 접근을 합니다 (저희는 계획표로 직렬화했기에 미도입). |
| 실패해도 작업 모니터링이 울리지 않음 | PIPESTATUS를 확인하지 않음 | Step 1과 같이 claude 측의 종료 코드를 반환합니다. |
'AI가 맡기고 있으니 괜찮겠지'라고 생각하면, 사용량이 소진되어도 알아차릴 수 없습니다. 저희 역시 상한에 도달한 채 매분 계속 실패하던 영업부 작업은 집계표를 만들어 보고 나서야 발견했습니다.
경영의 관점에서 볼 때, AI 활용량은 인건비와 같은 '부서별 가동 비용'입니다. 부서별 비율과 오류율을 월 1회만 봐도, 어디에 투자하고 어디를 중단할지 숫자로 결정할 수 있습니다. 우선 claude_run
함수부터 시작해 보세요.
CLAUDE.md 작성 방법이나 Claude Code의 설정 및 비용 관리에 대해 더 자세히 알고 싶은 분께는 당사의 서적 『CLAUDE.md 설계 패턴』을 추천합니다.
도서 목록: https://zenn.dev/joinclass?tab=books
사내에서 비슷한 구조를 만들고 싶지만 시간이 부족한 경우에는, Join Class LLC에서 중소기업을 대상으로 업무 시스템 개발 및 DX 지원(국내) 서비스를 제공하고 있습니다.
👉 업무 시스템・DX 무료 상담