AI 에이전트가 우리 CLI를 호출할 때 토큰이 79% 줄어든 이유

이 글이 해당되는 팀

Terraform, CloudFormation 같은 IaC 도구를 쓰면서 Claude Code나 Cursor 같은 AI 코딩 에이전트를 도입한 팀이라면 이 글이 직접 해당된다. CLI 도구를 내부적으로 운영하거나, 외부 CLI를 AI 에이전트의 서브프로세스로 호출하는 워크플로우가 있다면 특히 그렇다.

필요한 건 Claude API 접근 권한과 대상 CLI 도구뿐이다. 비용 면에서는 Claude Opus 기준으로 실험 몇 회에 수 달러 수준이면 충분하다.

---

Before: AI 에이전트가 CLI를 "사람처럼" 쓰면 생기는 일

우리 팀이 처음 Claude Code를 인프라 리뷰 워크플로우에 붙였을 때, 에이전트는 CLI 출력을 그대로 받아서 파이썬 파서를 즉석에서 짰다. "태깅 정책을 위반하는 고유 리소스 수를 세라"는 질문 하나에, 에이전트는 JSON을 파싱하는 코드를 작성하고, 실행하고, 결과를 해석하는 과정을 반복했다.

Infracost 팀의 벤치마크 결과를 보면 이 문제가 얼마나 심각한지 알 수 있다. 동일한 질문에 대해 도구 없이 raw CLI 출력만 받은 Claude는 $3.51을 소비하고 25턴 제한에 걸려 결국 답을 내지 못했다. 우리 팀도 비슷한 경험을 했다. 에이전트가 jq 파이프라인을 여러 번 시도하고, 실패하고, 다시 파이썬 코드를 쓰는 과정에서 토큰이 눈에 띄게 쌓였다.

문제의 본질은 간단하다. CLI가 사람을 위해 설계된 포맷으로 출력을 내보내면, 에이전트는 그걸 이해하기 위해 추가 작업을 수행하고, 그 과정에서 토큰이 낭비된다.

---

After: CLI에 에이전트용 경로를 하나 추가하면

Infracost 팀이 적용한 핵심 아이디어는 두 가지다. 첫 번째는 SKILL.md 파일을 통해 에이전트에게 CLI 사용법을 미리 알려주는 것이고, 두 번째는 --llm 플래그로 에이전트 친화적인 출력 포맷을 별도로 제공하는 것이다.

# .claude/skills/infracost-scan.md

## infracost-scan 사용 지침

인프라 비용 분석 시 반드시 `--llm` 플래그를 사용할 것.
이 플래그는 토큰 효율적인 출력 포맷을 활성화한다.

### 기본 사용법
infracost breakdown --path . --format json --llm

### 필터링이 필요한 경우 CLI 플래그를 직접 사용할 것
# jq로 후처리하지 말고:
infracost breakdown --path . --filter-tags "env=prod" --llm

### 출력 해석
- cost_diff: 월간 비용 변화량 (USD)
- violation_count: 정책 위반 리소스 수

이 SKILL.md가 .claude/skills/ 디렉토리에 있으면 Claude Code가 자동으로 로드한다. 에이전트는 CLI를 어떻게 써야 하는지 처음부터 알고 시작하기 때문에 탐색 비용이 크게 줄어든다.

두 번째 핵심은 "Predicate Pushdown"이다. 에이전트가 shell에서 jq로 필터링하게 두지 말고, CLI 자체가 필터를 받아서 이미 걸러진 결과를 돌려주는 구조다.

# 나쁜 예: 에이전트가 shell에서 필터링 (토큰 낭비)
infracost breakdown --path . --format json \
  | jq '.resources[] | select(.tags.env == null)'

# 좋은 예: CLI가 직접 필터링해서 돌려줌
infracost breakdown --path . --filter-missing-tags --llm

이 조합으로 같은 질문에 $0.25, 정확한 답변을 얻었다. 도구 없이 실패한 $3.51과 비교하면 92% 비용 절감이다.

---

우리 팀 내부 CLI에 동일 원리를 적용한 방법

우리는 내부 배포 CLI에 같은 원리를 적용했다. 사람용 출력과 에이전트용 출력을 분리하고, SKILL.md로 사용 가이드를 제공했다.

# deploy_cli/formatters.py

def format_output(data, mode="human"):
    if mode == "llm":
        # 에이전트용: 핵심 필드만, 간결한 구조
        return {
            "status": data["deployment_status"],
            "service_count": len(data["services"]),
            "failed_services": [
                s["name"] for s in data["services"]
                if s["status"] == "failed"
            ],
            "cost_delta_usd": data.get("estimated_cost_delta")
        }
    else:
        # 사람용: 색상, 테이블, 전체 정보
        return render_human_table(data)

# CLI에 플래그 하나 추가
deploy-cli status --env prod --llm
deploy-cli diff --branch main --filter-failures --llm

도입 후 내부 에이전트 워크플로우에서 Claude 토큰 사용량이 약 60% 줄었다. 더 중요한 건 에이전트가 실패하는 케이스가 눈에 띄게 줄었다는 것이다. 탐색에 쓰이는 시간이 줄고 실제 작업에 집중할 수 있게 됐다.

---

팀 도입 시 현실적인 조언

"왜 CLI를 AI용으로 따로 만들어야 하냐"는 반발이 나올 수 있다. 이 때 쓸 수 있는 한 줄 논리는 이거다: "에이전트가 우리 도구를 잘못 쓰면 우리 API 비용이 늘고, 에이전트가 틀린 답을 낸다."

혼자 실험할 때는 --llm 플래그 하나 추가하는 것만으로 효과를 확인할 수 있다. 팀 전체로 확대할 때는 SKILL.md를 공유 설정 저장소에 넣고 표준화하는 게 중요하다. 개인마다 다른 방식으로 CLI를 쓰면 벤치마크도 안 되고, 에이전트 동작이 예측 불가능해진다.

---

함정과 한계

--llm 출력 포맷을 한 번 내보내면 하위 호환성 부담이 생긴다. 에이전트가 특정 필드명에 의존하도록 학습되면, 필드명을 바꾸는 순간 에이전트 워크플로우가 깨진다. 사람용 CLI는 조금 바뀌어도 사람이 금방 적응하지만, 에이전트는 그렇지 않다.

또한 SKILL.md가 길어질수록 그 자체가 토큰 소비 요인이 된다. 핵심 사용법과 주의사항만 담고, 예제는 최소화하는 게 좋다. 우리는 처음에 SKILL.md를 너무 상세하게 썼다가, 에이전트가 관련 없는 섹션을 참조하면서 오히려 혼란을 일으킨 적이 있다.

마지막으로, 이 접근법은 에이전트가 CLI를 반복적으로 호출하는 워크플로우에서만 의미 있다. 에이전트가 CLI를 한두 번만 쓴다면 굳이 별도 포맷을 만들 필요 없다.

---

오늘 퇴근 전에 해볼 수 있는 한 가지

팀에서 가장 많이 쓰는 CLI 도구 하나를 골라라. 그 출력 중에서 에이전트가 처리하기에 불필요하게 복잡한 부분(색상 코드, 테이블 헤더, 사람을 위한 안내 문구)을 찾아라. 그리고 --llm 플래그 하나를 추가해서 JSON 또는 간결한 key=value 포맷으로만 출력하는 경로를 만들어봐라. 배포나 리뷰 없이, 로컬에서 30분이면 된다.

태그: Claude, AI에이전트, CLI최적화, 토큰절감, Infracost

※ 본 글은 정보 제공 목적이며 특정 제품·서비스의 추천이 아닙니다.