Los agentes de IA que programan son el nuevo mínimo. Pero un agente metido en tu repo sin contexto se comporta igual que un contratista sin onboarding: vuelve a deducir tus convenciones desde cero, adivina los patrones y entrega código plausible que viola en silencio tres invariantes que nadie llegó a escribir. La solución no es un modelo más listo. Es un wiki escrito para la máquina.
Qué es un wiki para LLMs, y qué no
No es tu Confluence, y tampoco es el README para humanos. Es el contexto que un agente carga antes de tocar tu código: las convenciones, los invariantes, los «nunca hagas X», las decisiones de arquitectura y las rarezas estructurales que un LLM no puede inferir del código. En concreto son los archivos que las herramientas ya buscan —CLAUDE.md, AGENTS.md, .cursorrules en la raíz, un llms.txt para la documentación— más documentos más profundos que el agente trae bajo demanda.
La prueba para saber si algo pertenece ahí es simple: ¿un buen ingeniero que nunca vio este codebase lo entendería mal? Si la respuesta es sí, va al wiki. Si el código ya lo dice, no.
Por qué importa: el agente vale lo que vale su contexto
- Un agente que programa sin grounding falla igual que un RAG sin grounding: seguro, plausible y equivocado. Busca el patrón equivocado porque nunca vio el correcto. También en tu código, la answerability va antes que la recuperación.
- La ventana de contexto es finita y se factura. Volcar el repo entero en cada turno es lento y caro, y casi todo es ruido. Un wiki curado es grounding eficiente: un núcleo pequeño siempre cargado más profundidad bajo demanda. Es el instinto consciente del cache aplicado a tu propio tooling.
- Se acumula. Humanos y agentes leen la misma fuente de verdad. Menos conocimiento tribal y onboarding más rápido, tanto para el empleado nuevo como para el agente nuevo.
Cómo construir uno
- Escribe lo no obvio, nunca lo obvio. El código ya dice qué hace. El wiki dice en qué se equivocaría un LLM: invariantes («nunca llames al store directamente, siempre por el repositorio»), convenciones de nombres, la única restricción rara de la que depende todo lo demás y por qué algo es como es. Repetir lo que el código ya dice solo quema contexto.
- Guárdalo en el repo, versionado junto al código. La documentación que vive en un wiki aparte se pudre el mismo día en que se escribe; la que vive junto al código cambia en el mismo pull request. El agente carga lo que está en el repo, así que ahí es donde tiene que vivir la verdad.
- Estratifícalo según el presupuesto de contexto. Un archivo raíz pequeño que se carga siempre, con las reglas que aplican en todas partes, apuntando a documentos más profundos por área que el agente recupera solo cuando vienen a cuento. La misma disciplina que en cualquier sistema de recuperación: no metas la biblioteca entera en el prompt.
- Genera el mapa, cura las reglas. Autogenera la mitad estructural —el árbol de fuentes, el mapa de módulos, los entry points. Después un humano añade el criterio que una máquina no puede inferir. La mitad generada se mantiene actual; la curada la mantiene correcta.
- Trata lo obsoleto como un bug. Un wiki desactualizado es peor que no tener ninguno: un agente seguirá una regla caduca con total aplomo. Actualiza el wiki en el mismo PR que cambia el comportamiento, y revisa el drift en CI, igual que atraparías cualquier otra regresión.
- Hazlo answerable. Estructúralo para que la parte correcta se pueda encontrar: encabezados claros, un dato en un solo sitio, enlaces entre reglas relacionadas. El agente —y cualquier recuperación por encima de él— necesita localizar la regla relevante, no leerlo todo.
- Mídelo. El wiki es un sistema, así que evalúalo como tal: ¿el agente produce cambios más acordes a tus patrones y con menos reescrituras con él que sin él? Si no puedes saberlo, estás adivinando, y adivinar es justo lo que el eval existe para matar.
Cómo lo usamos nosotros
Mantenemos un wiki para LLMs en nuestros propios repos —un archivo de instrucciones raíz pequeño, un mapa de estructura generado y las reglas escritas a mano que un agente se saltaría— porque construimos con agentes de IA todos los días. Un agente con nuestro contexto produce código que encaja con el sistema; el mismo agente sin él produce código que hay que reescribir. Es la palanca más barata de la ingeniería asistida por IA, y casi nadie la usa a propósito.
Un prompt para construir el tuyo
No hace falta que empieces con un archivo en blanco. Pega esto en un agente que programe, ejecútalo desde la raíz de tu repo y responde a sus preguntas: genera la mitad estructural y se detiene en el criterio que una máquina no puede inferir.
Monta un wiki para LLMs en este repo: el contexto que un agente de IA carga
antes de tocar el código. Objetivo: capturar solo aquello en lo que un agente
se equivocaría, no lo que el código ya dice. Trabaja por fases y detente donde
se indique para pedirme confirmación.
REGLAS: escribe lo no obvio, nunca lo obvio. Todo dentro del repo. Si dudas de
si algo es un invariante real o una suposición, PREGUNTA; no inventes. Una
regla equivocada con aplomo es peor que una regla que falta.
1. MAPA (genera): detecta el stack, los entry points, los comandos de build,
test y ejecución, y un mapa de estructura legible de un vistazo con los
módulos principales. Entrégalo como borrador.
2. EXTRAE (pregúntame): busca invariantes, «nunca hagas X», la única
restricción rara de la que depende todo, convenciones no obvias y trampas
escondidas en el historial de git. Preséntame una lista numerada de
candidatos CON su evidencia, y después DETENTE y déjame confirmar o corregir
antes de escribir ninguna regla.
3. ESCRIBE (estratificado): un archivo raíz pequeño, siempre cargado (CLAUDE.md
o AGENTS.md, usa el que ya exista), con las reglas que aplican en todas
partes, los comandos y punteros a documentos más profundos por área que se
traen bajo demanda. Cada regla: la regla, y debajo una línea de POR QUÉ.
4. VERIFICA: reléelo como un agente sin ningún contexto previo. ¿Cada regla es
localizable, inequívoca y no redundante con el código? Después dame 5
preguntas concretas sobre este codebase que el wiki debería responder de un
salto, y marca las que no pueda. Añade una regla de obsolescencia: este
archivo se actualiza en el mismo PR que cambia el comportamiento que
describe.
Después mídelo: ejecuta una tarea real una vez con el wiki cargado y otra sin él, y compara cuánto respetó cada intento tus convenciones y cuántas reescrituras harían falta antes del merge. Si el wiki no mueve esa aguja, está documentando lo obvio: vuelve al paso 2 y busca las reglas que de verdad muerden.
La IA ya sabe escribir el código. El cuello de botella se movió río arriba, al contexto: a lo que el agente sabe de tu sistema antes de empezar a teclear. El wiki para LLMs es ese contexto, escrito para el lector que ahora hace la mayor parte del trabajo. Constrúyelo como construirías cualquier capa de grounding: en el repo, estratificado, actual, answerable y medido.
El modelo es un commodity. El contexto es tuyo. Así que escríbelo, para la máquina.