Úspora tokenů AI agenta s hierarchickým kontextem | Řešení

# Hierarchický kontext: jak tři markdown soubory ušetří 80 % tokenů AI agenta

AI agenti pro vývoj, jako Claude Code nebo Cursor, utrácí až 80 % tokenů na opakované čtení souborů a navigaci v projektech. Problém spočívá v chybějící strukturované mapě pracovního prostoru. Řešení — hierarchický kontext ze tří markdown souborů, který snižuje tool calls o 10–20krát a zvyšuje přesnost odpovědí.

Anatomie problému: kam mizí tokeny?

Při dotazu „Jaké způsoby platby podporuje můj bot?“ agent provádí cyklus: grep v domovské složce → čtení nalezených souborů → uvědomění si chyby v projektu → nové hledání → SSH připojení k serveru. Na odpověď o 800 tokenech utratí 15+ tool calls a 80K+ tokenů. 99 % rozpočtu jde na navigaci, 1 % na odpověď.

To není chyba konkrétního agenta, ale systémový problém architektury. Všechny AI nástroje pro kód (Cursor, Codex, Gemini CLI) začínají každou relaci „slepým průzkumem“, protože nemají mapu pracovního prostoru. S 15 projekty se to mění v hodiny kontextu denně strávené hledáním souborů.

Proč RAG a statická analýza problem neřeší

Vektorové databáze (RAG) zachytí sémantickou podobnost, ale ignorují strukturu kódu. Dotaz „jak funguje autentizace?“ vrátí 15 fragmentů s výskytem „auth“, ale neukáže řetězec volání: middleware.ts → refresh.ts → jwt-config.ts. Navíc RAG přidává 200–500 ms zpoždění na dotaz a vyžaduje infrastrukturu (embedding-server, index).

Tree-sitter a statická analýza (např. Hypergrep) staví graf závislostí uvnitř projektu. Ale neodpovídají na otázky jako „jaké projekty používají Redis?“ nebo „kde je nasazen VPN-bot?“. CLAUDE.md na projekt řeší vnitřní úkoly, ale nepomáhá, když agent neví, v jakém projektu hledat.

Hierarchický model kontextu: úrovně 0, 1 a 1.5

Systém pokrývá tři úrovně abstrakce:

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)

Princip: agent se pohybuje shora dolů, ne zdola nahoru. Nejprve určí projekt podle mapy, pak přečte jeho architekturu, poté konkrétní soubory.

Level 0: Globální mapa

Umístěte do ~/.claude/CLAUDE.md (pro Claude Code) nebo analogického souboru:

## 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.

Tento soubor (~2KB) se automaticky načte v každé relaci. Agent okamžitě vidí seznam projektů, jejich umístění a stav.

Level 1: CLAUDE.md projektu

V kořeni každého projektu:

# 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

Velikost 3–5KB. Agent ho přečte při zmínce projektu a získá plnou architekturu bez grep.

Level 1.5: Graphify (volitelně)

Pro navigaci uvnitř kódu:

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

Převede kódovou bázi do grafu znalostí, ušetří 30–50 % volání ve velkých projektech.

Výsledky: měření efektivity

Testy provedeny na Haiku (nejlevnější model) za stejných podmínek:

• Test 1: „Jaká je architektura projektu A?“

Slepý agent: 12 tool calls, 100% přesnost.

S hierarchií: 1 tool call, 100% přesnost.

• Test 2: „Jaké projekty používají knihovnu X?“

Slepý agent: 44 tool calls, propustil 1 z 3 projektů.

S hierarchií: 2 tool calls, našel všechny projekty.

• Test 3: „Kde je nasazen projekt B?“

Slepý agent: 9 tool calls, vyžadoval SSH.

S hierarchií: 0 tool calls, odpověď z kontextu.

Klíčový je druhý test: slepý agent nejen utratil 22krát více zdrojů, ale dal i chybnou odpověď. Strukturovaný kontext zvyšuje nejen efektivitu, ale i přesnost.

Proč jsou tři soubory lepší než RAG pro navigaci

• Nulové zpoždění. Čtení markdown souborů je okamžité, RAG přidává 200–500 ms na dotaz.
• Determinismus. Vy kontrolujete obsah souborů, nespoléháte se na re-ranker.
• Real-time. Aktualizace CLAUDE.md vyžaduje jednu řádku, RAG plnou reindexaci.
• Univerzálnost. Funguje s jakýmkoli agentem (Claude Code, Cursor, Gemini CLI), bez potřeby vlastní infrastruktury.
• Škálovatelnost. 15 projektů = 15 CLAUDE.md (75KB) + mapa (2KB) = 77KB oproti 500KB–1MB syrových souborů.

RAG zůstává užitečný pro sémantické hledání v dokumentaci, ale pro navigaci mezi projekty je markdown hierarchie efektivnější.

Bonus: indexace minulých relací

Parser převádí logy relací (.jsonl) a chaty do markdown s YAML frontmatter:

---
title: "Počinil webhook platby"
date: 2026-04-14
project: vpn-bot
topics: ["webhook", "cryptocloud", "cloudflare"]
files_touched: ["payments.py", "webhook.py"]
---

Po indexaci takových souborů přes Graphify agent najde řešení z minulých relací bez opakovaných vysvětlení. To vytváří persistentní paměť mezi dialogy.

Milion tokenů není lék na vše

I s kontextovým oknem 1M tokenů problém nezmizí. LLM horší zpracovávají irelevantní informace (fenomén „lost in the middle“: data ze středu kontextu se často ignorují). Hierarchický kontext zaručuje, že agent dostane jen potřebné soubory v správném pořadí a minimalizuje šum.

Jak implementovat za 10 minut

• Vytvořte globální mapu projektů v ~/.claude/CLAUDE.md (5 minut) — vypíšte projekty, cesty, servery.
• Přidejte CLAUDE.md do kořene hlavního projektu (5 minut) — uveďte stack, klíčové soubory, příkazy nasazení.
• Spusťte novou relaci agenta a položte otázku o projektu.
• Ověřte, že agent odpovídá bez slepého hledání.

Co je důležité

• AI agenti utrácí až 99 % tokenů na navigaci, ne na generování odpovědí.
• Hierarchie ze tří markdown souborů snižuje tool calls o 10–20krát a zvyšuje přesnost.
• Level 0 (globální mapa) a Level 1 (CLAUDE.md projektu) řeší problém navigace mezi projekty.
• Systém nevyžaduje infrastrukturu a funguje s jakýmkoli agentem pro kód.
• Strukturovaný kontext je efektivnější než RAG pro úkoly hledání souborů a projektů.

— Editorial Team