English

Indexa tus docs, no los vuelques

Decenas de docs, un índice, cero saturación de contexto.

Cuando le das a un agente de código una biblioteca de docs de metodología — convenciones de tests, checklists de release, reglas de arquitectura, playbooks de incidentes — el movimiento ingenuo es cargarlos todos en el contexto en cada tarea. Esa es la forma más rápida de reventar el presupuesto de contexto y sepultar el único archivo que importa bajo cincuenta que no. Un índice lo resuelve: el agente lee un mapa diminuto, encuentra el doc correcto y carga solo ese.

Por qué volcarlo todo sale mal

Cada token de contexto cargado compite por la atención del modelo. Mete ochenta documentos y pasan tres cosas a la vez:

• Quema de presupuesto. Gastas casi toda la ventana en docs que la tarea actual nunca tocará, dejando menos espacio para el código, los diffs y el razonamiento reales.
• Dilución de señal. La metodología relevante ahora es un archivo entre muchos. La recuperación dentro del contexto se degrada a medida que crece la pila; el modelo hojea en vez de leer.
• Costo y latencia. Más tokens por turno significa más dinero y respuestas más lentas, en cada petición, se necesitaran los docs o no.

El doc que necesitabas estaba ahí. Simplemente no se escuchaba entre los otros setenta y nueve.

El mecanismo: un índice de tarea a doc

Arma un archivo de índice ligero que mapea una tarea al doc que la cubre. Es una tabla de contenidos, no el contenido. El agente lee el índice primero, empareja la tarea en curso y luego carga el único archivo al que apunta.

# Índice de metodología
Lee esto primero. Carga solo el doc que tu tarea necesita.

| Cuando estás...                | Carga                          |
|--------------------------------|--------------------------------|
| Escribiendo o arreglando tests | testing/conventions.md         |
| Cortando un release            | release/checklist.md           |
| Agregando una migración        | data/migrations.md             |
| Atendiendo un incidente        | ops/incident-playbook.md       |
| Revisando un pull request      | review/pr-standards.md         |

El índice se mantiene lo bastante pequeño como para quedar residente. Cada doc enlazado queda a un solo salto. Este es el mismo principio de la divulgación progresiva (progressive disclosure) en las skills de agentes: expones un punto de entrada corto y difieres el detalle hasta que se pide.

Carga condicional en la práctica

La carga condicional mantiene el contexto de trabajo liviano mientras cada metodología queda alcanzable en el momento en que una tarea la pide. Pagas por lo que usas, no por lo que podrías usar.

Movidas avanzadas

• Mantén el índice plano. Un nivel de mapeo, tarea a doc. Los índices anidados reintroducen el problema de búsqueda que querías eliminar.
• Que las entradas se describan solas. La columna "cuando estás..." debe dejar que el agente empareje por intención, no por adivinar nombres de archivo.
• Un doc por preocupación. Si el índice apunta a un cajón de sastre de 700 líneas, divídelo para que cada archivo enlazado cargue enfocado.
• Versiona el índice con los docs. Cuando un doc se renombra o retira, actualiza el índice en el mismo cambio para que el mapa nunca apunte a un archivo muerto.
• Audita docs sin referencia. Todo lo que no sea alcanzable desde el índice es peso muerto o un enlace roto. Búscalo con grep de forma periódica.

Recursos

• Agent Skills — documentación de Anthropic (progressive disclosure)
• Effective context engineering for AI agents — Anthropic
• Retrieval-augmented generation — paper original (Lewis et al., 2020)
• Model Context Protocol — recursos y descubrimiento de herramientas