지난해 한 팀이 금요일에 "작은 프롬프트 개선(small prompt improvement)"을 배포했습니다. 월요일이 되자 그들의 Claude 청구 금액이 40% 급증했습니다. 리뷰 과정에서 아무도 이를 발견하지 못했습니다. 변경 사항(diff)은 괜찮아 보였기 때문입니다. 토큰은 눈에 보이지 않았습니다.

우리는 이 현상의 극단적인 사례에 대해 자율 에이전트 스튜디오를 운영하며 1억 3,600만 개의 토큰을 소모했습니다 — 비용을 약 90% 절감한 방법에서 작성한 바 있습니다. 그것은 통제 불능 상태의 에이전트였습니다. 하지만 대부분의 비용 회귀(cost regressions)는 극적이지 않습니다. 200개의 토큰이 늘어난 프롬프트, 더 이상 트리밍(trimming)되지 않는 컨텍스트 윈도우(context window), 설명이 800단어에 달하는 새로운 도구 같은 것들입니다. 이것들은 청구서가 도착할 때까지 조용히 누적됩니다.

우리는 우리가 가졌으면 좋았을 가드레일(guardrail)을 직접 만들었습니다.

기능

**wartzar-bee/ci-guardrail**은 다음과 같은 기능을 수행하는 GitHub Action입니다:

1. 사용자의 PR 브랜치와 베이스(base) 브랜치에서 @wartzar-bee/tokenscope를 실행합니다.
2. 토큰 비용 차이(token-cost delta)를 계산합니다.
3. PR에 차이값과 비용 상승을 주도하는 주요 파일들을 보여주는 댓글을 게시합니다.
4. 선택적으로 비용이 임계값(threshold)을 초과하면 **빌드를 차단(blocks the build)**합니다.

회귀(regression)가 포착되었을 때 PR 댓글은 다음과 같이 보입니다:

## 🚨 wartzar-bee Cost Guardrail

| Metric          | Value      |
...

이 댓글은 **멱등성(idempotent)**을 가집니다. 즉, 푸시(push)할 때마다 제자리에서 업데이트되어 스팸을 생성하지 않습니다.

설정 없는 구축 (Zero-config setup)

저장소에 파일 하나만 추가하세요:

# .github/workflows/cost-guardrail.yml
name: Cost Guardrail
on: [pull_request]
...

그게 전부입니다. API 키도 필요 없고, 외부 서비스도 필요 없습니다. GITHUB_TOKEN이 유일한 비밀 값(secret)이며, 이는 모든 저장소에 이미 존재합니다.

보고 전용 모드 (Report-only mode)

아직 빌드를 차단할 준비가 되지 않았나요? threshold-pct: 0으로 설정하세요:

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

차단 장치 없이 가시성(visibility)만 확보할 수 있습니다. 준비가 되면 차단 장치를 추가하세요.

정적 분석(static analysis)만으로 충분한 이유 (현재로서는)

이 액션(action)은 에이전트 코드(프롬프트, 컨텍스트 설정, 도구 정의)에 대한 정적 분석(static analysis)인 tokenscope scan을 사용합니다. 에이전트를 직접 실행하지 않습니다. 즉, 다음과 같은 특징을 가집니다:

• 빠름 (Fast) — LLM 호출 없이 몇 초 만에 실행됩니다.
• 안전함 (Safe) — 읽기 전용이며, 부작용(side effects)이 없습니다.
• 결정론적 (Deterministic) — 동일한 코드에 대해 매번 동일한 추정치를 제공합니다.

트레이드오프(tradeoff): 이 방식은 런타임 비용(runtime cost, 대화 기록이나 도구 출력 등에 따라 달라짐)이 아닌 구조적(structural) 토큰 비용을 추정합니다. 프롬프트 수정 및 설정 변경으로 인한 회귀(regression)를 포착하는 데 있어서는 정적 분석만으로도 실제 사례의 대부분을 잡아낼 수 있습니다. 라이브 샌드박스 실행(Live sandbox execution)은 향후 로드맵에 포함되어 있습니다.

그 이면에 있는 패턴

1억 3,600만 토큰 소모에 대한 사후 분석(postmortem) 결과, 거의 모든 비용 사고에서 나타나는 세 가지 근본 원인을 확인했습니다:

1. 기준점(baseline) 부재 — 팀이 무엇이 "정상"인지 알지 못하므로, 회귀가 발생해도 이를 인지할 수 없습니다.
2. 차단 장치(gate) 부재 — 누군가 문제를 발견하더라도, 잘못된 변경 사항을 차단할 메커니즘이 없습니다.
3. 원인 파악(attribution) 불가 — 청구 금액이 급증했을 때, 어떤 파일이나 설정이 원인인지 아무도 알지 못합니다.

CI 가드레일(guardrail)은 이 세 가지를 모두 해결합니다. PR(Pull Request)별 기준점을 설정하고, 선택적인 차단 장치를 제공하며, 정확히 어떤 파일이 책임이 있는지 보여줍니다.

사용해 보기

이 액션은 지금 바로 사용할 수 있습니다. 저장소는 wartzar-bee/ci-guardrail 에 있으며, 위의 워크플로우(workflow)를 복사하면 2분 이내에 실행할 수 있습니다.

예외적인 상황(edge case)을 발견하거나 접근 방식에 대해 논의하고 싶다면, 이슈(issue)를 생성하거나 @wartzarbee를 통해 저희를 찾아주세요.

wartzar-bee는 비용 효율적인 자율 에이전트(autonomous agents)를 구축합니다. @wartzar-bee/tokenscope는 저희의 오픈 소스 토큰 분석 도구이며, 월간 설치 수가 약 90건에 달하며 계속 성장하고 있습니다.