계층적 컨텍스트로 AI 에이전트 토큰 절약 | 솔루션

계층적 컨텍스트: 3개의 마크다운 파일이 AI 에이전트 토큰 80%를 절감하는 방법

Claude Code나 Cursor 같은 개발 AI 에이전트는 파일 재독과 프로젝트 탐색에 토큰의 최대 80%를 소비합니다. 문제의 원인은 구조화된 작업 공간 지도가 없기 때문입니다. 해결책은 세 개의 마크다운 파일로부터의 계층적 컨텍스트로, 도구 호출을 10–20배 줄이고 응답 정확도를 높입니다.

문제의 구조: 토큰은 어디로 사라지는가?

"내 봇이 지원하는 결제 수단은 뭐야?"라고 물으면 에이전트는 이런 순환을 거칩니다: 홈 디렉터리에서 grep → 발견된 파일 읽기 → 잘못된 프로젝트 깨달음 → 새 검색 → 서버 SSH 연결. 800토큰 응답을 위해 15+ 도구 호출과 80K+ 토큰을 소모합니다. 예산의 99%가 탐색에, 1%만 답변에 쓰입니다.

이건 특정 에이전트의 버그가 아닙니다—시스템 아키텍처 문제입니다. 모든 AI 코딩 도구(Cursor, Codex, Gemini CLI)는 작업 공간 지도가 없어 매 세션을 "맹목 정찰"로 시작합니다. 15개 프로젝트가 있으면 파일 사냥에 매일 수시간의 컨텍스트가 낭비됩니다.

RAG와 정적 분석이 해결하지 못하는 이유

벡터 데이터베이스(RAG)는 의미적 유사성을 잡지만 코드 구조를 무시합니다. "인증은 어떻게 작동하나요?" 같은 쿼리는 "auth"를 언급한 15개 조각을 반환하지만 middleware.ts → refresh.ts → jwt-config.ts 같은 호출 체인을 보여주지 않습니다. 게다가 RAG는 쿼리당 200–500 ms 지연을 추가하고 인프라(임베딩 서버, 인덱스)가 필요합니다.

Tree-sitter와 정적 분석(예: Hypergrep)은 프로젝트 내 의존성 그래프를 구축합니다. 하지만 "어떤 프로젝트가 Redis를 사용하나요?"나 "VPN 봇은 어디에 배포됐나요?" 같은 질문에는 답할 수 없습니다. 프로젝트당 CLAUDE.md는 내부 작업을 처리하지만 에이전트가 어느 프로젝트를 봐야 할지 모를 때는 도움이 안 됩니다.

계층적 컨텍스트 모델: 레벨 0, 1, 1.5

이 시스템은 세 수준의 추상화를 다룹니다:

Level 0: Karta projectov     — znaet VWithE projecty and servery     (~2KB, vsegda in kontekste)
Level 1: Detali project     — arkhitektura konkretnogo project  (~5KB, by request)  
Level 1.5: Graf koda        — struktura kodovoy database           (optsionalno, Graphify)
Level 2: Iskhodnyy code       — realnye files                   (tolko kogda potrzebny jest)

원리: 에이전트는 바닥에서 위로가 아니라 위에서 아래로 이동합니다. 먼저 지도에서 프로젝트를 식별한 후 아키텍처를 읽고, 특정 파일을 봅니다.

레벨 0: 글로벌 맵

~/.claude/CLAUDE.md(Claude Code용) 또는 동등 위치에 배치:

## Project Map

| Proekt | Put | Witherver | Withtatus |
|--------|------|--------|--------|
| VPN Bot | ~/projects/vpn-bot/ | prod-1:/opt/vpn/ | LIVE |
| Auth Service | ~/projects/auth/ | prod-1 (Docker) | LIVE |

### Withervery
| Imya | IP | Onwartość |
|-----|-----|-----------|
| prod-1 | 178.17.50.45 | Osnovnoy VPS, 3 service |

### Ruleilo
Prezhde than chitat iskhodnyy code — prochitay CLAUDE.md project.

이 파일(~2KB)은 매 세션에서 자동 로드됩니다. 에이전트는 즉시 프로젝트 목록, 위치, 상태를 확인할 수 있습니다.

레벨 1: 프로젝트 CLAUDE.md

각 프로젝트 루트에:

# VPN Bot — CLAUDE.md

## Status: LIVE (prod-1)
Telegram-bot VPN-service. Podpiski cherez Stars and CryptoBot.

## Stack
Python 3.11, python-telegram-bot, WireGuard, aiosqlite

## Key Files
- bot/main.py — point input
- bot/payments.py — Stars + CryptoBot processing

## Deploy
- Withervis: vpn-bot.service
- Logi: journalctl -u vpn-bot -f

크기 3–5KB. 에이전트는 프로젝트가 언급되면 이를 읽고 grep 없이 전체 아키텍처를 파악합니다.

레벨 1.5: Graphify (선택)

코드 탐색용:

pip install graphify
cd ~/projects/auth
graphify claude install

코드베이스를 지식 그래프로 변환해 대형 프로젝트에서 호출을 30–50% 절감합니다.

결과: 효율성 측정

동일 조건에서 Haiku(최저가 모델)로 테스트:

• 테스트 1: "프로젝트 A의 아키텍처는?"

맹목 에이전트: 12 도구 호출, 100% 정확도.

계층 구조 사용: 1 도구 호출, 100% 정확도.

• 테스트 2: "어떤 프로젝트가 라이브러리 X를 사용하나요?"

맹목 에이전트: 44 도구 호출, 3개 중 1개 놓침.

계층 구조 사용: 2 도구 호출, 모든 프로젝트 발견.

• 테스트 3: "프로젝트 B는 어디에 배포됐나요?"

맹목 에이전트: 9 도구 호출, SSH 필요.

계층 구조 사용: 0 도구 호출, 컨텍스트에서 답변.

테스트 2가 핵심입니다: 맹목 에이전트는 자원 22배 더 쓰고 잘못된 답변을 줬습니다. 구조화된 컨텍스트는 효율뿐 아니라 정확도도 높입니다.

왜 3개 파일이 RAG를 탐색에서 이길까

• 제로 지연. 마크다운 파일 읽기는 즉시; RAG는 쿼리당 200–500 ms 추가.
• 결정적. 파일 내용을 직접 제어, 리랭커에 의존 안 함.
• 실시간. CLAUDE.md 업데이트는 한 줄; RAG는 전체 재인덱싱 필요.
• 유니버설. 어떤 에이전트(Claude Code, Cursor, Gemini CLI)든 작동, 커스텀 인프라 불필요.
• 확장성. 15 프로젝트 = 15 CLAUDE.md (75KB) + 맵 (2KB) = 77KB vs. 500KB–1MB 원본 파일.

RAG는 의미 문서 검색에 여전히 훌륭하지만, 프로젝트 탐색에는 마크다운 계층 구조가 승리합니다.

보너스: 과거 세션 인덱싱

파서가 세션 로그(.jsonl)와 채팅을 YAML frontmatter가 있는 마크다운으로 변환:

---
title: "Pochinil webhook oplaty"
date: 2026-04-14
project: vpn-bot
topics: ["webhook", "cryptocloud", "cloudflare"]
files_touched: ["payments.py", "webhook.py"]
---

Graphify로 이를 인덱싱하면 에이전트가 재설명 없이 과거 해결책을 찾습니다. 이는 대화 간 지속적 메모리를 만듭니다.

100만 토큰도 만병통치약은 아니다

1M 토큰 컨텍스트 창이라도 문제는 지속됩니다. LLM은 무관한 정보를 더 못 다룹니다("lost in the middle" 현상: 중간 컨텍스트 데이터가 종종 무시됨). 계층적 컨텍스트는 에이전트가 필요한 파일만 올바른 순서로 받게 해 노이즈를 최소화합니다.

10분 만에 구현하기

• ~/.claude/CLAUDE.md에 글로벌 프로젝트 맵 생성 (5분)—프로젝트, 경로, 서버 나열.
• 주요 프로젝트 루트에 CLAUDE.md 추가 (5분)—스택, 주요 파일, 배포 명령 지정.
• 새 에이전트 세션 시작해 프로젝트 물어보기.
• 에이전트가 맹목 검색 없이 답변하는지 확인.

핵심 요점

• AI 에이전트는 탐색에 토큰의 최대 99%를 낭비하고 답변 생성에는 거의 안 씀.
• 3개 파일 마크다운 계층 구조는 도구 호출을 10–20배 줄이고 정확도 향상.
• 레벨 0(글로벌 맵)과 레벨 1(프로젝트 CLAUDE.md)은 프로젝트 간 탐색 해결.
• 인프라 불필요; 어떤 코딩 에이전트든 작동.
• 구조화된 컨텍스트가 파일 및 프로젝트 발견에서 RAG를 이김.

— Editorial Team