AI 에이전트 토큰 절약 실전 가이드

이전 글에서는 “Compacting conversation…” 이후 답변 품질이 떨어지는 원인을 분석하고, 훅 시스템으로 상태를 보존·복원하는 방법을 다뤘어요.

이 글에서는 한 단계 앞으로 가요. Compacting이 오기 전에 토큰을 아끼는 구조적 방법을 다뤄요.

읽고 나면 다음을 이해할 수 있어요:

• 토큰 비용을 항목별로 파악하는 방법
• 지침 파일을 백과사전이 아니라 목차로 쓰는 이유
• Skill을 Facade 패턴으로 설계해서 시스템 프롬프트를 가볍게 유지하는 방법
• 판단이 필요 없는 로직을 스크립트로 분리하는 패턴
• Sub-agent로 컨텍스트를 격리하는 전략

토큰은 메모리다

Anthropic의 Claude Code 모범 사례 문서는 이렇게 말해요:

Context window fills up fast, and performance degrades as it fills.

전통적인 서버에서는 RAM을 걱정했어요. AI 에이전트에서는 토큰을 걱정해야 해요.

AGENTS.md, Skills 메타데이터, 대화 히스토리, MCP 응답… 이 모든 것이 Context Window에 쌓여요. Claude Opus 4.6과 Sonnet 4.6은 1M 토큰의 컨텍스트 윈도우를 제공하지만, 대규모 코드베이스를 다루다 보면 순식간에 차올라요.

Anthropic Labs의 Harness 설계 글에서는 컨텍스트가 차오르면 모델이 “context anxiety” 를 보인다고 해요. 작업이 남아 있는데도 컨텍스트 한계에 가까워졌다고 판단해서 성급하게 마무리하려는 경향이에요. 토큰을 아끼면 컨텍스트에 여유가 생겨 이 문제를 완화할 수 있어요.

어디서 토큰이 새는가

항목별 토큰 비용을 파악하면 예산을 세울 때 도움이 돼요. Anthropic의 토큰 카운팅 문서에 따르면, 영문 기준 약 3에서 4자당 1토큰, 한글·CJK 문자는 약 1에서 2자당 1토큰을 소비해요. 아래는 이를 바탕으로 한 대략적인 추정이에요:

Toss 팀의 소프트웨어 3.0 시대를 맞이하며에서는 이런 비유를 해요: “지침을 작성한 뒤, Claude에게 ‘이 워크플로우를 실행하면 어떤 파일들을 읽게 될 것 같아?‘라고 물어보세요. 예상보다 많은 파일이 나온다면, 지침을 좁히거나 단계를 나눠야 한다는 신호입니다.” OOM을 예방하듯, 토큰 폭발도 이런 식으로 미리 감지할 수 있어요.

지침 파일: 백과사전이 아니라 목차

AGENTS.md를 단일 진실 소스로

AI 코딩 에이전트마다 지침 파일 형식이 달라요. Claude Code는 CLAUDE.md, Cursor는 .cursor/rules/, OpenCode는 AGENTS.md를 사용하죠. 도구마다 파일을 따로 관리하면 내용이 중복되고, 변경할 때마다 여러 파일을 수정해야 해요.

이 문제를 해결하는 방법은 AGENTS.md를 단일 진실 소스(single source of truth)로 쓰는 것이에요. 모든 프로젝트 컨텍스트를 AGENTS.md에 작성하고, CLAUDE.md는 심볼릭 링크로 만들어서 AGENTS.md를 가리키게 하는 거죠:

# 기존 CLAUDE.md가 있다면 AGENTS.md로 이름 변경
mv CLAUDE.md AGENTS.md
 
# AGENTS.md를 가리키는 심볼릭 링크 생성
ln -s AGENTS.md CLAUDE.md

이렇게 하면 하나의 파일만 관리하면 돼요. Claude Code는 CLAUDE.md(심볼릭 링크)를 통해, Cursor나 OpenCode는 AGENTS.md를 직접 읽어요.

거대한 지침 파일의 문제

OpenAI의 Codex 팀은 Harness Engineering 글에서 “하나의 거대한 AGENTS.md”가 왜 실패하는지 네 가지 이유를 밝혔어요:

1. 컨텍스트는 희소 리소스. 거대한 지침 파일은 작업, 코드, 관련 문서를 복잡하게 만들어서 에이전트가 핵심 제약조건을 놓치기 시작해요.
2. 지침이 너무 많으면 지침이 아님. 모든 것이 “중요”하다면 중요한 것은 아무것도 없어요. 에이전트는 의도적으로 탐색하는 대신 패턴 매칭을 수행하게 돼요.
3. 순식간에 망가짐. 획일적인 거대 매뉴얼은 낡은 규칙들의 무덤이 돼요. 에이전트는 무엇이 여전히 사실인지 알 수 없어요.
4. 확인하기 어려움. 단일 블롭은 기계적 점검(커버리지, 신선도, 교차 연결)에 적합하지 않아서 드리프트가 불가피해요.

Anthropic도 공식 문서에서 CLAUDE.md를 200줄 이하로 유지하길 권장해요. 파일이 길수록 컨텍스트를 더 많이 소비하고, 지시 준수율(adherence)이 떨어진다고요.

목차 패턴: AGENTS.md → docs/

OpenAI Codex 팀의 해법은 단순해요. AGENTS.md를 백과사전이 아니라 목차로 쓰는 것이에요.

AGENTS.md
├── 기술 스택 설명 (50줄)
├── 코딩 컨벤션 (100줄)
├── 23개 안티패턴 상세 설명 (200줄)
├── 빌드/배포 가이드 (50줄)
├── 보안 규칙 (30줄)
└── 커밋 메시지 규칙 (20줄)
→ 매 대화마다 ~2,000 토큰 소비

AGENTS.md (100줄 이하, ~500 토큰)
├── 프로젝트 개요 + 기술 스택
├── 핵심 명령어 (build, test, lint)
└── docs/ 디렉토리 참조 안내
 
docs/
├── architecture.md    → 필요할 때만 참조
├── conventions.md     → 필요할 때만 참조
├── pitfalls.md        → 필요할 때만 참조
└── decisions.md       → 필요할 때만 참조

OpenAI Codex 팀이 실제로 사용하는 구조를 보면 이 패턴이 명확해요. 짧은 AGENTS.md(약 100줄)가 목차 역할을 하고, 실제 지식은 docs/ 디렉토리에 분산돼 있어요:

docs/
├── design-docs/
│   ├── index.md
│   └── core-beliefs.md
├── exec-plans/
│   ├── active/
│   ├── completed/
│   └── tech-debt-tracker.md
├── product-specs/
│   └── index.md
├── references/
│   ├── design-system-reference-llms.txt
│   └── uv-llms.txt
├── FRONTEND.md
├── SECURITY.md
└── RELIABILITY.md

지침 파일에 무엇을 써야 하는가

Anthropic의 Claude Code 모범 사례에 따르면, 지침 파일에는 Claude가 코드를 읽는 것만으로는 알 수 없는 정보를 담아야 해요:

여기서 중요한 점이 하나 더 있어요. 코딩 컨벤션이나 커밋 메시지 형식처럼 기계적으로 검증할 수 있는 규칙은 지침 파일에 장황하게 설명하는 것보다 ESLint, Prettier, commitlint 같은 도구로 자동 검증하는 게 훨씬 효율적이에요. 도구가 자동으로 잡아주는 규칙은 지침 파일에서 제외하면 토큰도 아끼고, 규칙 위반도 확실히 막을 수 있어요.

@ 참조로 필요할 때만 로드

Claude Code에서는 @ 참조로 외부 파일을 필요할 때만 컨텍스트에 로드할 수 있어요. 매번 전체를 인라인으로 삽입하는 게 아니라, 관련 작업을 할 때만 참조하는 거예요. 최대 5단계 재귀 임포트를 지원하므로, docs/ 안의 문서가 다시 다른 문서를 참조하는 것도 가능해요.

.claude/rules/ 디렉토리도 활용할 수 있어요. 파일 경로별로 규칙을 scope 지정하면, 해당 파일을 작업할 때만 규칙이 로딩돼요.

@ 참조가 실제로 토큰을 얼마나 절약하는지 비교해 볼게요:

10번의 대화 중 docs/pitfalls.md가 필요한 건 2–3번이에요. 인라인이면 10번 모두 2,000 토큰을 쓰고, @ 참조면 평균 500 토큰이에요. 대화가 쌓일수록 차이는 더 벌어져요.

Skill 설계: 시스템 프롬프트를 가볍게 유지하기

Toss 팀의 소프트웨어 3.0 시대를 맞이하며에서는 Skill 설계를 전통 아키텍처의 클래스 폭발, 디미터의 법칙, Facade 패턴 등과 연결 지어 설명해요. 여기서는 토큰 절약 관점에서 핵심만 정리할게요.

Skill이 많으면 시스템 프롬프트가 무거워져요

Claude Code는 세션 시작 시 등록된 모든 Skill의 이름과 설명을 시스템 프롬프트에 포함해요. Skill 하나당 50에서 200토큰을 차지하므로, 수가 늘어날수록 매 대화의 고정 비용이 증가해요. 예를 들어 Skill이 20개라면, 사용 여부와 관계없이 매번 최대 4,000토큰이 시스템 프롬프트에 고정 할당돼요.

진입점과 상세 지식을 분리하세요

해결 방법은 Skill을 잘게 쪼개는 것이 아니라, 하나의 Skill 안에서 계층을 나누는 것이에요. SKILL.md는 짧은 진입점 역할만 하고, 세부 가이드라인은 하위 파일로 분리해요:

.claude/skills/
└── code-review/
    ├── SKILL.md              # 진입점 — 시스템 프롬프트에 로드
    ├── references/           # Claude가 필요할 때만 읽음
    │   ├── naming-rules.md
    │   ├── security-checklist.md
    │   └── performance-guide.md
    └── scripts/
        └── lint-check.sh     # 판단 불필요한 검사는 스크립트로

Claude는 SKILL.md의 내용만 시스템 프롬프트에 로드하고, references/ 안의 파일은 작업 중 필요하다고 판단될 때만 컨텍스트에 추가해요. 시스템 프롬프트의 고정 비용은 SKILL.md 하나의 크기로 제한되는 거예요.

분리 기준

이 Skill의 설명이 매 세션마다 로드될 가치가 있는가? 대답이 “가끔”이라면, 독립 Skill이 아니라 기존 Skill의 references/에 두는 게 나아요.

결정적 로직을 스크립트로 분리

LLM이 매번 판단할 필요 없는 것

토큰을 아끼는 가장 직관적인 방법은 LLM이 할 필요 없는 일을 LLM에게 시키지 않는 것이에요.

# AGENTS.md에 이런 규칙이 있다면...
배포 전에 다음 환경 변수가 설정되었는지 확인하라:
DATABASE_URL (PostgreSQL 연결 문자열, postgresql:// 로 시작),
REDIS_URL (Redis 연결 문자열), API_SECRET_KEY (최소 32자),
SENTRY_DSN (선택, 없으면 에러 추적 비활성화).
누락된 변수가 있으면 배포를 중단하고 알려줘.

이 규칙을 매번 읽고, 이해하고, 적용하는 데 토큰이 쓰여요. 그런데 이건 판단이 필요 없는 결정적(deterministic) 로직이에요.

#!/bin/bash
# scripts/check-deploy-readiness.sh
ERRORS=0
check_var() {
  local name=$1 pattern=$2
  if [ -z "${!name}" ]; then
    echo "MISSING: $name" && ERRORS=$((ERRORS + 1))
  elif [ -n "$pattern" ] && ! echo "${!name}" | grep -qE "$pattern"; then
    echo "INVALID: $name (expected: $pattern)" && ERRORS=$((ERRORS + 1))
  fi
}
check_var DATABASE_URL "^postgresql://"
check_var REDIS_URL "^redis://"
check_var API_SECRET_KEY ".{32,}"
[ $ERRORS -gt 0 ] && echo "$ERRORS issue(s) found" && exit 1
echo "All checks passed"

배포 전 검증: `./scripts/check-deploy-readiness.sh`

LLM 입장에서는 스크립트를 실행하고 결과를 확인하면 끝이에요. 규칙 5줄이 명령어 1줄로 줄어들어요.

스크립트로 분리할 수 있는 것들

판단 기준은 단순해요: 입력이 같으면 출력이 항상 같은가? 그렇다면 스크립트나 도구가 LLM보다 나아요. 더 빠르고, 더 정확하고, 토큰을 0개 써요.

Sub-agent로 컨텍스트 격리

메인 컨텍스트를 보호하세요

Sub-agent는 별도의 컨텍스트 윈도우에서 동작해요. 전통 아키텍처의 스레드 격리와 비슷하죠. 메인 스레드에서 무거운 작업을 하면 UI가 멈추듯, 메인 컨텍스트에서 대규모 탐색을 하면 컨텍스트가 넘쳐요.

사용자: "이 프로젝트의 모든 API 엔드포인트를 찾아서 문서화해줘"
 
→ Claude가 직접 수십 개 파일을 읽음
→ 메인 컨텍스트에 수만 토큰 누적
→ Compacting 트리거

사용자: "이 프로젝트의 모든 API 엔드포인트를 찾아서 문서화해줘"
 
→ Explore Sub-agent가 파일 탐색 (별도 컨텍스트)
→ 결과 요약만 메인 컨텍스트로 반환 (~500 토큰)
→ 메인 컨텍스트는 깨끗하게 유지

Sub-agent가 50개 파일을 읽어도 메인 컨텍스트에는 요약 결과만 들어와요. 50,000 토큰이 500 토큰으로 줄어드는 셈이죠.

언제 Sub-agent를 쓸지 판단하기

Claude Code에서는 Task 도구로 Sub-agent를 생성할 수 있어요. 각 Sub-agent는 독립적인 컨텍스트를 가지므로, 무거운 탐색 작업을 메인 컨텍스트 밖으로 밀어내는 용도로 활용하면 토큰을 크게 절약할 수 있어요.

비용도 줄일 수 있어요. 탐색용 Sub-agent에 model: "haiku"를 지정하면 더 빠르고 저렴한 모델로 읽기 전용 작업을 처리해요. Claude Code의 내장 Explore Sub-agent도 기본적으로 Haiku 모델을 사용해요.

MCP 응답 최적화

MCP(Model Context Protocol)로 외부 시스템에 연결하면 예상치 못한 토큰 폭발이 일어날 수 있어요. DB 쿼리 하나가 10,000행을 반환하면 그대로 컨텍스트에 쌓이거든요.

필터링과 페이지네이션

MCP 서버를 설계할 때는 응답 크기를 제한하세요. MCP 도구의 입력 스키마는 JSON Schema로 자유롭게 정의할 수 있으므로, limit, offset, filter 같은 파라미터를 추가하는 것은 서버 구현의 영역이에요:

// MCP 도구 핸들러
async function listUsers() {
  const users = await db.query('SELECT * FROM users');
  return users; // 10,000행 → ~40,000 토큰
}

// MCP 도구 핸들러
async function listUsers({ limit = 20, offset = 0, filter }) {
  const users = await db.query(
    'SELECT id, name, email FROM users WHERE name LIKE ? LIMIT ? OFFSET ?',
    [`%${filter}%`, limit, offset]
  );
  const total = await db.count('users');
  return { users, total, hasMore: offset + limit < total };
}

응답 형식 최적화

같은 데이터라도 형식에 따라 토큰 차이가 커요:

[
  { "id": 1, "name": "Alice", "email": "alice@example.com", "createdAt": "2024-01-01" },
  { "id": 2, "name": "Bob", "email": "bob@example.com", "createdAt": "2024-01-02" }
]

| id | name | email |
|----|------|-------|
| 1 | Alice | alice@example.com |
| 2 | Bob | bob@example.com |

LLM은 테이블을 잘 이해해요. JSON에서 "name", "email", "createdAt" 같은 키가 매 행마다 반복되는 오버헤드를 테이블로 줄일 수 있어요.

도구 설명도 컨텍스트다

MCP 서버가 제공하는 도구 설명(description) 도 시스템 프롬프트에 로드돼요. 도구가 많을수록 설명이 쌓여요.

Cursor 팀은 이 문제를 Dynamic Context Discovery로 해결했어요. 모든 도구의 상세 설명을 미리 로드하는 대신, 도구 이름만 포함된 소량의 정적 컨텍스트를 제공하고 필요할 때 상세 설명을 조회하는 방식이에요. A/B 테스트 결과, MCP 도구를 호출한 실행에서 총 에이전트 토큰이 46.9% 감소했어요.

MCP 서버를 직접 만든다면, 도구 설명을 간결하게 유지하세요. 긴 설명은 별도 리소스로 분리하고, 에이전트가 필요할 때 조회하게 하는 게 효율적이에요.

대화 습관으로 토큰 아끼기

도구와 설정을 최적화한 뒤에도, 사용자의 대화 습관이 토큰 효율에 큰 영향을 줘요.

구체적으로 지시하세요

이 프로젝트에서 날짜 관련 유틸 함수를 찾아서 고쳐줘
 
→ Claude가 grep, glob으로 파일 탐색 (~5,000 토큰)
→ 여러 후보 중 맥락 파악 (~3,000 토큰)
→ 수정 (~500 토큰)

src/lib/date-utils.ts:42의 formatDate 함수에서
KST 시간대가 적용 안 되는 문제 수정해줘
 
→ 파일 읽기 (~1,000 토큰)
→ 수정 (~500 토큰)

탐색 비용을 사용자가 미리 줄여주면 Claude는 핵심 작업에만 토큰을 쓸 수 있어요.

세션을 적절히 나누세요

하나의 긴 세션에서 모든 걸 하려 하지 마세요. 컨텍스트가 쌓일수록 주의력은 분산되고, 이전 대화를 참조하는 데 토큰이 소비돼요.

Anthropic Labs의 Harness 설계 글은 긴 작업에서 compaction(대화 압축)보다 context reset(컨텍스트 초기화 + 구조화된 핸드오프)이 더 효과적인 경우가 있다고 해요. Compaction은 연속성을 유지하지만 에이전트에게 “깨끗한 시작”을 주지 못해서, context anxiety가 여전히 남을 수 있다는 거예요.

컨텍스트를 오염시키지 마세요

Anthropic은 모범 사례 문서에서 몇 가지 안티패턴에 이름을 붙였어요:

• Kitchen Sink Session: 하나의 세션에서 관련 없는 여러 작업을 혼합하는 것. 컨텍스트가 오염되어 모든 작업의 품질이 떨어져요.
• Infinite Exploration: 범위를 지정하지 않은 “조사해줘” 요청이 수백 개 파일을 읽어서 컨텍스트를 소진하는 것. Sub-agent로 위임하세요.
• Correcting Over and Over: 같은 문제를 2번 이상 교정했다면, /clear 후 더 나은 프롬프트로 재시작하는 게 나아요.

작업 사이에 /clear를 사용하면 컨텍스트를 초기화할 수 있어요. 간단한 질문은 /btw로 하면 대화 히스토리에 추가되지 않아 컨텍스트 성장을 막을 수 있어요.

/compact 타이밍

이전 글에서 다뤘지만, 다시 한번 강조해요. 자동 압축(100%)이 터지기 전에 /compact을 직접 실행하세요. 체감 70–80%에서 실행하면 custom_instructions로 보존 지시를 줄 수 있어요.

/compact TODO 목록, 수정 중인 파일 경로, 현재 작업 맥락을 보존해줘

AGENTS.md에 compaction 지침을 미리 추가해두면, 매번 보존할 항목을 수동으로 지정하지 않아도 돼요.

실전 체크리스트

토큰 절약 전략을 한눈에 정리했어요.

프로젝트 설정 시:

• AGENTS.md를 단일 진실 소스로, CLAUDE.md는 심볼릭 링크로
• AGENTS.md는 200줄 이하로, 상세 규칙은 docs/에 분리
• @ 참조로 필요할 때만 문서 로드
• Skill은 Facade 패턴으로: 진입점 + references/
• 기계적 검증은 ESLint·commitlint 등 도구로, 지침 파일에서 제외
• 반복적인 워크플로우는 스크립트로 캡슐화

작업 중:

• 대규모 탐색은 Sub-agent에게 위임
• 파일 경로와 함수명을 직접 지정
• 관련 없는 작업은 세션을 분리
• 70–80%에서 /compact 직접 실행

정리

토큰 절약은 성능 최적화와 같아요. 메모리 릭을 고치듯 불필요한 컨텍스트 누적을 줄이고, 캐시를 활용하듯 @ 참조와 Progressive Disclosure로 필요한 것만 로드하고, 스레드를 분리하듯 Sub-agent로 컨텍스트를 격리하는 거예요.

이번 글의 전략으로 Compacting 빈도를 줄이고, 그래도 Compacting이 터지면 이전 글의 전략으로 대응하세요. 예방과 대응, 두 가지를 모두 갖추면 AI 코딩 에이전트와의 작업 품질이 확실히 달라질 거예요.

참고 자료

• OpenAI — Harness Engineering — AGENTS.md를 목차로 쓰는 패턴, 문서 기반 지식 관리
• Anthropic — Harness Design for Long-Running Apps — context anxiety, context reset vs compaction
• Anthropic — Claude Code Memory — CLAUDE.md 작성 가이드, @ 참조, .claude/rules/
• Anthropic — Claude Code Best Practices — 컨텍스트 관리 안티패턴과 최적화 전략
• Anthropic — Claude Code Sub-agents — Sub-agent 컨텍스트 격리, 모델 라우팅
• Anthropic — Prompt Caching — cache hit 시 입력 토큰 비용 90% 절감
• Cursor — Dynamic Context Discovery — 동적 컨텍스트 탐색으로 MCP 도구 호출 시 46.9% 토큰 감소
• Toss 팀의 소프트웨어 3.0 시대를 맞이하며 — 레이어드 아키텍처 비유, Skill Progressive Disclosure
• Andrej Karpathy — Software Is Changing (Again) — Software 3.0과 Harness 개념