Oszczędność tokenów agenta AI z kontekstem hierarchicznym | Rozwiązanie

# Hierarchiczny kontekst: jak trzy pliki markdown oszczędzają 80% tokenów agenta AI

Agenci AI do rozwoju, tacy jak Claude Code czy Cursor, zużywają do 80% tokenów na ponowne czytanie plików i nawigację po projektach. Problem tkwi w braku strukturalnej mapy przestrzeni roboczej. Rozwiązanie — hierarchiczny kontekst z trzech plików markdown, który skraca tool calls w 10–20 razy i zwiększa dokładność odpowiedzi.

Anatomia problemu: dokąd znikają tokeny?

Przy zapytaniu „Jakie sposoby płatności obsługuje mój bot?” agent wykonuje cykl: grep po katalogu domowym → czytanie znalezionych plików → zrozumienie błędu projektu → nowe wyszukiwanie → połączenie SSH z serwerem. Na odpowiedź liczącą 800 tokenów zużywa 15+ tool calls i 80K+ tokenów. 99% budżetu idzie na nawigację, 1% — na odpowiedź.

To nie błąd konkretnego agenta, lecz systemowy problem architektury. Wszystkie narzędzia AI do kodu (Cursor, Codex, Gemini CLI) zaczynają każdą sesję od „ślepego rekonesansu”, bo nie mają mapy przestrzeni roboczej. Przy 15 projektach to godziny kontekstu dziennie zmarnowane na szukanie plików.

Dlaczego RAG i statyczna analiza nie rozwiązują problemu

Wektorowe bazy (RAG) wychwytują podobieństwo semantyczne, ale ignorują strukturę kodu. Zapytanie „jak działa uwierzytelnianie?” zwraca 15 fragmentów z wzmianką „auth”, ale nie pokazuje łańcucha wywołań: middleware.ts → refresh.ts → jwt-config.ts. Dodatkowo RAG dodaje 200–500 ms opóźnienia na zapytanie i wymaga infrastruktury (serwer embeddingów, indeks).

Tree-sitter i statyczna analiza (np. Hypergrep) budują graf zależności w projekcie. Ale nie odpowiadają na pytania typu „które projekty używają Redis?” czy „gdzie jest wdrożony VPN-bot?”. CLAUDE.md projektu rozwiązuje zadania wewnętrzne, ale nie pomaga, gdy agent nie wie, w którym projekcie szukać.

Hierarchiczny model kontekstu: poziomy 0, 1 i 1.5

System obejmuje trzy poziomy abstrakcji:

Level 0: Mapa projektów     — zna WSZYSTKIE projekty i serwery     (~2KB, zawsze w kontekście)
Level 1: Szczegóły projektu — architektura konkretnego projektu     (~5KB, na żądanie)  
Level 1.5: Graf kodu        — struktura bazy kodu                  (opcjonalnie, Graphify)
Level 2: Kod źródłowy       — rzeczywiste pliki                    (tylko gdy potrzebne)

Zasada: agent porusza się od góry w dół, a nie od dołu w górę. Najpierw określa projekt na podstawie mapy, potem czyta jego architekturę, na końcu — konkretne pliki.

Level 0: Globalna mapa

Umieszczana w ~/.claude/CLAUDE.md (dla Claude Code) lub podobnym pliku:

## Mapa projektów

| Projekt     | Ścieżka             | Serwer          | Status |
|-------------|---------------------|-----------------|--------|
| VPN Bot     | ~/projects/vpn-bot/ | prod-1:/opt/vpn/| LIVE   |
| Auth Service| ~/projects/auth/    | prod-1 (Docker) | LIVE   |

### Serwery
| Nazwa   | IP           | Przeznaczenie             |
|---------|--------------|---------------------------|
| prod-1  | 178.17.50.45 | Główny VPS, 3 serwisy     |

### Zasada
Przed czytaniem kodu źródłowego — przeczytaj CLAUDE.md projektu.

Ten plik (~2KB) jest automatycznie ładowany w każdej sesji. Agent natychmiast widzi listę projektów, ich lokalizacje i status.

Level 1: CLAUDE.md projektu

W korzeniu każdego projektu:

# VPN Bot — CLAUDE.md

## Status: LIVE (prod-1)
Bot Telegram do usługi VPN. Subskrypcje przez Stars i CryptoBot.

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

## Kluczowe pliki
- bot/main.py — punkt wejścia
- bot/payments.py — obsługa Stars + CryptoBot

## Wdrożenie
- Serwis: vpn-bot.service
- Logi: journalctl -u vpn-bot -f

Rozmiar 3–5KB. Agent czyta go po wzmiance o projekcie i uzyskuje pełną architekturę bez grep.

Level 1.5: Graphify (opcjonalnie)

Do nawigacji w kodzie:

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

Przekształca bazę kodu w graf wiedzy, oszczędzając 30–50% wywołań w dużych projektach.

Wyniki: pomiary efektywności

Testy na Haiku (najtańszy model) w identycznych warunkach:

• Test 1: „Jaka architektura w Projekcie A?”

Ślepy agent: 12 tool calls, 100% dokładność.

Z hierarchią: 1 tool call, 100% dokładność.

• Test 2: „Które projekty używają biblioteki X?”

Ślepy agent: 44 tool calls, przeoczył 1 z 3 projektów.

Z hierarchią: 2 tool calls, znalazł wszystkie projekty.

• Test 3: „Gdzie wdrożony jest Projekt B?”

Ślepy agent: 9 tool calls, wymagał SSH.

Z hierarchią: 0 tool calls, odpowiedź z kontekstu.

Kluczowy jest drugi test: ślepy agent nie tylko zużył 22 razy więcej zasobów, ale dał błędną odpowiedź. Strukturalny kontekst zwiększa nie tylko efektywność, ale i dokładność.

Dlaczego trzy pliki lepsze od RAG do nawigacji

• Zerowe opóźnienie. Czytanie plików markdown jest natychmiastowe, RAG dodaje 200–500 ms na zapytanie.
• Deterministyczność. Kontrolujesz zawartość plików, zamiast polegać na rerankerze.
• Czas rzeczywisty. Aktualizacja CLAUDE.md to jedna linijka, RAG — pełna reindeksacja.
• Uniwersalność. Działa z każdym agentem (Claude Code, Cursor, Gemini CLI), bez niestandardowej infrastruktury.
• Skalowalność. 15 projektów = 15 CLAUDE.md (75KB) + mapa (2KB) = 77KB vs 500KB–1MB surowych plików.

RAG nadal przydaje się do semantycznego wyszukiwania w dokumentacji, ale do nawigacji między projektami hierarchia markdown jest skuteczniejsza.

Bonus: indeksowanie poprzednich sesji

Parser konwertuje logi sesji (.jsonl) i czaty na markdown z YAML frontmatter:

---
title: "Naprawiłem webhook płatności"
date: 2026-04-14
project: vpn-bot
topics: ["webhook", "cryptocloud", "cloudflare"]
files_touched: ["payments.py", "webhook.py"]
---

Po zindeksowaniu takich plików przez Graphify agent odnajduje rozwiązania z poprzednich sesji bez powtarzania wyjaśnień. To tworzy trwałą pamięć między dialogami.

Milion tokenów — nie panaceum

Nawet z oknem kontekstowym 1M tokenów problem nie znika. LLM gorzej radzą sobie z nieistotnymi informacjami (zjawisko „lost in the middle”: dane z środka kontekstu są często ignorowane). Hierarchiczny kontekst gwarantuje, że agent dostaje tylko potrzebne pliki w właściwej kolejności, minimalizując szum.

Jak wdrożyć w 10 minut

• Utwórz globalną mapę projektów w ~/.claude/CLAUDE.md (5 minut) — wypisz projekty, ścieżki, serwery.
• Dodaj CLAUDE.md w korzeń głównego projektu (5 minut) — podaj stack, kluczowe pliki, komendy wdrożenia.
• Uruchom nową sesję agenta i zapytaj o projekt.
• Upewnij się, że agent odpowiada bez ślepego wyszukiwania.

Co ważne

• Agenci AI zużywają do 99% tokenów na nawigację, a nie na generowanie odpowiedzi.
• Hierarchia z trzech plików markdown skraca tool calls w 10–20 razy i zwiększa dokładność.
• Level 0 (globalna mapa) i Level 1 (CLAUDE.md projektu) rozwiązują problem nawigacji międzyprojektowej.
• System nie wymaga infrastruktury i działa z każdym agentem do kodu.
• Strukturalny kontekst jest skuteczniejszy od RAG w zadaniach wyszukiwania plików i projektów.

— Editorial Team