Ahorro de Tokens de Agentes IA con Contexto Jerárquico | Solución

## Contexto Jerárquico: Cómo Tres Archivos Markdown Ahorran el 80% de los Tokens de los Agentes de IA

Los agentes de desarrollo de IA como Claude Code o Cursor gastan hasta el 80% de sus tokens releyendo archivos y navegando por proyectos. El problema radica en la falta de un mapa estructurado del espacio de trabajo. La solución es el contexto jerárquico de tres archivos markdown, que reduce las llamadas a herramientas en 10–20 veces y mejora la precisión de las respuestas.

Anatomía del Problema: ¿Dónde Se Van los Tokens?

Cuando se le pregunta «¿Qué métodos de pago soporta mi bot?», el agente pasa por un ciclo: grep en el directorio principal → lectura de archivos encontrados → darse cuenta de que es el proyecto equivocado → nueva búsqueda → conexión SSH al servidor. Para una respuesta de 800 tokens, quema 15+ llamadas a herramientas y 80K+ tokens. El 99% del presupuesto se va en navegación, el 1% en la respuesta.

Esto no es un error en un agente específico: es un problema de arquitectura sistémica. Todas las herramientas de codificación con IA (Cursor, Codex, Gemini CLI) inician cada sesión con una «reconocimiento a ciegas» porque les falta un mapa del espacio de trabajo. Con 15 proyectos, esto se convierte en horas de contexto desperdiciado diariamente en la búsqueda de archivos.

Por Qué RAG y el Análisis Estático No lo Resuelven

Las bases de datos vectoriales (RAG) capturan similitud semántica pero ignoran la estructura del código. Una consulta como «¿cómo funciona la autenticación?» devuelve 15 fragmentos que mencionan «auth», pero no muestra la cadena de llamadas: middleware.ts → refresh.ts → jwt-config.ts. Además, RAG añade 200–500 ms de latencia por consulta y requiere infraestructura (servidor de embeddings, índice).

Tree-sitter y el análisis estático (p. ej., Hypergrep) construyen gráficos de dependencias dentro de un proyecto. Pero no pueden responder preguntas como «¿qué proyectos usan Redis?» o «¿dónde está desplegado el bot VPN?». Un CLAUDE.md por proyecto maneja tareas internas, pero no ayuda cuando el agente no sabe en qué proyecto buscar.

Modelo de Contexto Jerárquico: Niveles 0, 1 y 1.5

El sistema cubre tres niveles de abstracción:

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)

Principio: el agente se mueve de arriba hacia abajo, no de abajo hacia arriba. Primero identifica el proyecto desde el mapa, luego lee su arquitectura y después archivos específicos.

Nivel 0: Mapa Global

Colocado en ~/.claude/CLAUDE.md (para Claude Code) o equivalente:

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

Este archivo (~2KB) se carga automáticamente en cada sesión. El agente ve instantáneamente la lista de proyectos, ubicaciones y estado.

Nivel 1: CLAUDE.md del Proyecto

En la raíz de cada proyecto:

# 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

Tamaño 3–5KB. El agente lo lee cuando se menciona el proyecto y obtiene la arquitectura completa sin grep.

Nivel 1.5: Graphify (Opcional)

Para navegación de código:

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

Convierte la base de código en un grafo de conocimiento, ahorrando 30–50% de llamadas en proyectos grandes.

Resultados: Medidas de Eficiencia

Pruebas realizadas en Haiku (modelo más barato) en condiciones idénticas:

• Prueba 1: «¿Cuál es la arquitectura del Proyecto A?»

Agente ciego: 12 llamadas a herramientas, 100% precisión.

Con jerarquía: 1 llamada a herramientas, 100% precisión.

• Prueba 2: «¿Qué proyectos usan la librería X?»

Agente ciego: 44 llamadas a herramientas, perdió 1 de 3 proyectos.

Con jerarquía: 2 llamadas a herramientas, encontró todos los proyectos.

• Prueba 3: «¿Dónde está desplegado el Proyecto B?»

Agente ciego: 9 llamadas a herramientas, requirió SSH.

Con jerarquía: 0 llamadas a herramientas, respuesta del contexto.

La Prueba 2 es crítica: el agente ciego no solo usó 22x más recursos, sino que dio una respuesta incorrecta. El contexto estructurado mejora no solo la eficiencia, sino la precisión.

Por Qué Tres Archivos Superan a RAG para Navegación

• Cero latencia. Leer archivos markdown es instantáneo; RAG añade 200–500 ms por consulta.
• Determinístico. Tú controlas el contenido de los archivos, sin depender de rerankers.
• Tiempo real. Actualizar CLAUDE.md toma una línea; RAG necesita reindexación completa.
• Universal. Funciona con cualquier agente (Claude Code, Cursor, Gemini CLI), sin infraestructura personalizada.
• Escalable. 15 proyectos = 15 CLAUDE.md (75KB) + mapa (2KB) = 77KB vs. 500KB–1MB de archivos crudos.

RAG sigue siendo genial para búsqueda semántica de documentos, pero para navegación de proyectos, la jerarquía markdown gana.

Extra: Indexación de Sesiones Pasadas

El analizador convierte registros de sesiones (.jsonl) y chats a markdown con frontmatter YAML:

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

Indexar estos vía Graphify permite al agente encontrar soluciones pasadas sin reexplicar. Esto crea memoria persistente entre diálogos.

Un Millón de Tokens No es la Solución Definitiva

Incluso con una ventana de contexto de 1M tokens, el problema persiste. Los LLM manejan peor la información irrelevante (fenómeno «perdido en el medio»: datos en medio del contexto a menudo ignorados). El contexto jerárquico asegura que el agente obtenga solo los archivos necesarios en el orden correcto, minimizando el ruido.

Cómo Implementarlo en 10 Minutos

• Crea un mapa global de proyectos en ~/.claude/CLAUDE.md (5 minutos): lista proyectos, rutas, servidores.
• Añade CLAUDE.md a la raíz de tu proyecto principal (5 minutos): especifica stack, archivos clave, comandos de despliegue.
• Inicia una nueva sesión de agente y pregunta sobre un proyecto.
• Confirma que el agente responde sin búsqueda a ciegas.

Lecciones Clave

• Los agentes de IA desperdician hasta el 99% de tokens en navegación, no en generación de respuestas.
• Una jerarquía markdown de tres archivos reduce las llamadas a herramientas 10–20x y mejora la precisión.
• Nivel 0 (mapa global) y Nivel 1 (CLAUDE.md del proyecto) resuelven la navegación interproyectos.
• No se necesita infraestructura; funciona con cualquier agente de codificación.
• El contexto estructurado supera a RAG para descubrimiento de archivos y proyectos.

— Editorial Team