AI 에이전트를 운영한다면, 여러분의 토큰 비용은 소스 코드 안에 존재합니다. 프롬프트(prompts), 도구 설명(tool descriptions), 그리고 매 턴마다 다시 보내는 컨텍스트(context)의 양에 달려 있습니다. 그리고 소스 코드는 풀 리퀘스트(pull requests, PR)를 통해 변경됩니다. 따라서 비용 회귀(cost regression)를 포착할 자연스러운 장소는 버그를 잡는 곳과 동일한 곳입니다. 즉, 머지(merge)되기 전, PR 단계의 CI에서입니다.

저는 이를 비싼 대가를 치르고 배웠습니다. 한때 에이전트에 타이머를 설정했다가 하룻밤 사이에 거의 아무것도 하지 않고 1억 3,600만 개의 토큰을 태워버린 적이 있습니다. 그것은 극적인 결말이었습니다. 일상적인 결말은 더 조용합니다. 200토큰만큼 늘어난 시스템 프롬프트(system prompt), 더 이상 트리밍(trimming)되지 않는 컨텍스트 윈도우(context window), 설명이 800단어에 달하는 새로운 도구 같은 것들 말이죠. 이 중 어느 것도 코드 리뷰(code review)에서는 나타나지 않습니다. 디프(diff)는 괜찮아 보이기 때문입니다. 토큰은 보이지 않습니다.

이 글은 이를 가시화하기 위한 5분짜리 가이드입니다. PR의 토큰 비용 차이(token-cost delta)를 추정하고, 해당 파일들을 PR에 댓글로 남기며, 비용이 설정한 임계값(threshold)을 넘어서면 빌드를 실패하게 만들 수 있는 GitHub Action을 소개합니다.

추가해야 할 단 하나의 파일

이 내용을 .github/workflows/cost-guardrail.yml에 넣으세요:

name: Cost Guardrail
on: [pull_request]

...

이것이 설정의 전부입니다. 계정도 필요 없고, 저장소에 이미 있는 GITHUB_TOKEN 외에 다른 API 키도 필요 없습니다. 차이점을 비교하려면 팁 커밋(tip commit)뿐만 아니라 git 히스토리가 필요합니다.

다음 PR에서 얻게 되는 것

다음은 이 액션의 실제 실행 결과 댓글입니다. 기여자가 에이전트의 system_prompt.txt에 매 턴마다 다시 전송되는 퓨샷(few-shot) 블록을 추가했습니다. 이것은 모형이 아닌 실제 tokenscope 수치입니다. 액션은 푸시(push)할 때마다 동일한 댓글을 업데이트하므로 스레드에 스팸을 남기지 않습니다.

## 🚨 wartzar-bee Cost Guardrail

| Metric             | Value      |
...

가치 있는 정보는 맨 위의 숫자가 아니라, 바로 responsible-files 테이블에 있습니다. 이 테이블은 "청구 금액이 올라갔다"라는 모호한 상황을 "system_prompt.txt가 534 토큰(tokens) 증가했기 때문에 청구 금액이 올라갔다"라는 구체적인 정보로 바꿔줍니다. 이는 리뷰어가 PR(Pull Request)에서 즉각 조치를 취할 수 있는 코멘트가 되며, 인보이스(invoice)를 보고 깜짝 놀라는 상황을 방지합니다. (PR당 발생하는 달러 금액은 작을 수 있습니다. 핵심은 이것이 여러분의 플릿(fleet) 전체에서 매일, 매 턴마다 재전송된다는 점이며, 빌드(build)를 차단하는 기준은 바로 이 퍼센트(%)입니다.)

리포트 전용 모드로 시작하기

도입 첫날부터 빌드를 실패하게 만드는 것은 GitHub Action을 삭제당하는 지름길입니다. 차단하기보다는 측정하는 것부터 시작하세요. 임계값(threshold)을 0으로 설정하면, 빌드를 실패시키지는 않으면서 항상 코멘트만 남깁니다.

- uses: wartzar-bee/ci-guardrail@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
...

실제 PR에서 일주일 동안 실행되도록 두세요. 그러면 여러분의 레포지토리(repo)에서 "정상적인" 변화량(delta)이 어느 정도인지 알 수 있습니다. 예를 들어 +5%는 일상적이지만 +40%는 중단할 가치가 있는 수준일 수 있습니다. 그 후에 이를 반영하는 숫자로 threshold-pct를 설정하고, 추측 대신 의도를 가지고 차단(blocking) 기능을 켜세요.

달러 금액을 맞춤 설정하기

코멘트에는 예상 달러 변화량(dollar delta)이 표시되어, 엔지니어가 아닌 사람이 PR을 읽더라도 상황을 이해할 수 있게 합니다. 기본적으로 1M 토큰당 $3.00의 대략적인 혼합 입력 토큰(input-token) 가격을 사용합니다. 이는 플레이스홀더(placeholder)이므로, 실제 숫자가 반영되도록 사용하는 모델에 맞춰 값을 재정의(override)하세요.

- uses: wartzar-bee/ci-guardrail@v1
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
...

빌드를 차단하는 기준은 퍼센트(%)이지만, 달러 금액은 머지(merge)를 승인하는 사람에게 그 퍼센트의 의미를 확실히 전달하기 위해 존재합니다.

실제 작동 원리

마법 같은 것은 없으며, 어떤 데이터도 외부로 전송되지 않습니다.

1. HEAD 브랜치에서 tokenscope를 실행하여 전체 토큰 사용량(token footprint)을 추정합니다.
2. 베이스(base) 브랜치를 가져와 동일한 스캔을 실행합니다.
3. 차이(delta)를 퍼센트(%)로 계산합니다.
4. 파일별 상세 내역이 담긴 PR 코멘트를 게시(또는 업데이트)합니다. 또한 동일한 표를 Actions 실행 요약(run summary)에도 작성하여, 코멘트를 남길 PR이 없는 push 또는 예약된 실행(scheduled runs) 시에도 확인할 수 있도록 합니다.
5. 차이가 설정된 threshold-pct를 초과하면(단, 임계값이 0보다 큰 경우) 종료 코드(exit code)를 0이 아닌 값으로 반환합니다.

엔진은 오픈 소스 토큰 비용 분석기인 tokenscope이며, Action은 이를 감싸고 있는 가볍고 감사 가능한(auditable) 복합 래퍼(composite wrapper)입니다. 두 가지 모두 MIT 라이선스입니다.

사용해 보기

• Action: github.com/wartzar-bee/ci-guardrail (uses: wartzar-bee/ci-guardrail@v1)
• Marketplace: CI Cost Guardrail
• 단독 엔진 사용: npx @wartzar-bee/tokenscope <your-session.jsonl>

파일 하나를 추가하고 PR을 연 뒤, diff 옆에 토큰 차이(token delta)가 나타나는 것을 확인해 보세요. 머지(merge)되기 전에 800단어 분량의 도구 설명(tool description)을 단 한 번이라도 잡아낸다면, 이미 본전은 뽑은 셈입니다.