Économie des Jetons d'Agent IA avec Contexte Hiérarchique | Solution

Contexte hiérarchique : Comment trois fichiers Markdown économisent 80 % des tokens des agents IA

Les agents IA de développement comme Claude Code ou Cursor dépensent jusqu'à 80 % de leurs tokens à relire des fichiers et à naviguer dans les projets. Le problème vient du manque d'une carte structurée de l'espace de travail. La solution est un contexte hiérarchique à partir de trois fichiers markdown, qui réduit les appels d'outils de 10 à 20 fois et améliore la précision des réponses.

Anatomie du problème : Où partent les tokens ?

Quand on lui demande « Quels modes de paiement mon bot supporte-t-il ? », l'agent passe par un cycle : grep dans le répertoire principal → lecture des fichiers trouvés → réalisation que c'est le mauvais projet → nouvelle recherche → connexion SSH au serveur. Pour une réponse de 800 tokens, il consomme 15+ appels d'outils et plus de 80 000 tokens. 99 % du budget part en navigation, 1 % en réponse.

Ce n'est pas un bug d'un agent spécifique — c'est un problème d'architecture systémique. Tous les outils de codage IA (Cursor, Codex, Gemini CLI) commencent chaque session par une « reconnaissance à l'aveugle » car ils manquent d'une carte de l'espace de travail. Avec 15 projets, cela se transforme en heures de contexte gaspillées quotidiennement à chasser les fichiers.

Pourquoi RAG et l'analyse statique ne résolvent pas le problème

Les bases de données vectorielles (RAG) capturent la similarité sémantique mais ignorent la structure du code. Une requête comme « comment fonctionne l'authentification ? » renvoie 15 fragments mentionnant « auth » mais ne montre pas la chaîne d'appels : middleware.ts → refresh.ts → jwt-config.ts. De plus, RAG ajoute 200 à 500 ms de latence par requête et nécessite une infrastructure (serveur d'embeddings, index).

Tree-sitter et l'analyse statique (par ex. Hypergrep) construisent des graphes de dépendances au sein d'un projet. Mais ils ne peuvent pas répondre à des questions comme « quels projets utilisent Redis ? » ou « où le bot VPN est-il déployé ? ». Un CLAUDE.md par projet gère les tâches internes mais n'aide pas quand l'agent ne sait pas dans quel projet regarder.

Modèle de contexte hiérarchique : Niveaux 0, 1 et 1,5

Le système couvre trois niveaux d'abstraction :

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)

Principe : l'agent avance de haut en bas, pas de bas en haut. D'abord il identifie le projet à partir de la carte, puis lit son architecture, puis les fichiers spécifiques.

Niveau 0 : Carte globale

Placé dans ~/.claude/CLAUDE.md (pour Claude Code) ou équivalent :

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

Ce fichier (~2 Ko) se charge automatiquement à chaque session. L'agent voit instantanément la liste des projets, emplacements et statuts.

Niveau 1 : CLAUDE.md du projet

À la racine de chaque projet :

# 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

Taille 3 à 5 Ko. L'agent le lit quand le projet est mentionné et obtient l'architecture complète sans grep.

Niveau 1,5 : Graphify (optionnel)

Pour la navigation dans le code :

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

Convertit la base de code en graphe de connaissances, économisant 30 à 50 % des appels dans les gros projets.

Résultats : Mesures d'efficacité

Tests effectués sur Haiku (modèle le moins cher) dans des conditions identiques :

• Test 1 : « Quelle est l'architecture du Projet A ? »

Agent aveugle : 12 appels d'outils, 100 % de précision.

Avec hiérarchie : 1 appel d'outil, 100 % de précision.

• Test 2 : « Quels projets utilisent la bibliothèque X ? »

Agent aveugle : 44 appels d'outils, a raté 1 projet sur 3.

Avec hiérarchie : 2 appels d'outils, a trouvé tous les projets.

• Test 3 : « Où le Projet B est-il déployé ? »

Agent aveugle : 9 appels d'outils, SSH requis.

Avec hiérarchie : 0 appel d'outil, réponse depuis le contexte.

Le test 2 est critique : l'agent aveugle n'a pas seulement utilisé 22 fois plus de ressources mais a donné une mauvaise réponse. Le contexte structuré améliore non seulement l'efficacité mais aussi la précision.

Pourquoi trois fichiers battent RAG pour la navigation

• Zéro latence. Lire des fichiers markdown est instantané ; RAG ajoute 200 à 500 ms par requête.
• Déterministe. Vous contrôlez le contenu des fichiers, pas de dépendance aux rerankers.
• Temps réel. Mettre à jour CLAUDE.md prend une ligne ; RAG nécessite une réindexation complète.
• Universel. Fonctionne avec n'importe quel agent (Claude Code, Cursor, Gemini CLI), pas d'infrastructure personnalisée.
• Évolutif. 15 projets = 15 CLAUDE.md (75 Ko) + carte (2 Ko) = 77 Ko contre 500 Ko–1 Mo de fichiers bruts.

RAG reste excellent pour la recherche sémantique dans les docs, mais pour la navigation dans les projets, la hiérarchie markdown l'emporte.

Bonus : Indexation des sessions passées

Le parseur convertit les logs de sessions (.jsonl) et chats en markdown avec frontmatter YAML :

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

Indexer cela via Graphify permet à l'agent de retrouver des solutions passées sans réexplication. Cela crée une mémoire persistante à travers les dialogues.

Un million de tokens n'est pas une solution miracle

Même avec une fenêtre de contexte de 1 M de tokens, le problème persiste. Les LLM gèrent mal les infos non pertinentes (phénomène « lost in the middle » : les données au milieu du contexte sont souvent ignorées). Le contexte hiérarchique assure que l'agent n'obtient que les fichiers nécessaires dans le bon ordre, minimisant le bruit.

Comment implémenter en 10 minutes

• Créer une carte globale des projets dans ~/.claude/CLAUDE.md (5 minutes) — lister projets, chemins, serveurs.
• Ajouter CLAUDE.md à la racine de votre projet principal (5 minutes) — spécifier stack, fichiers clés, commandes de déploiement.
• Démarrer une nouvelle session d'agent et poser une question sur un projet.
• Vérifier que l'agent répond sans recherche à l'aveugle.

Enseignements clés

• Les agents IA gaspillent jusqu'à 99 % de leurs tokens en navigation, pas en génération de réponses.
• Une hiérarchie markdown en trois fichiers réduit les appels d'outils de 10 à 20 fois et améliore la précision.
• Niveau 0 (carte globale) et niveau 1 (CLAUDE.md du projet) résolvent la navigation inter-projets.
• Aucune infrastructure requise ; fonctionne avec n'importe quel agent de codage.
• Le contexte structuré bat RAG pour la découverte de fichiers et de projets.

— Editorial Team