Los agentes de IA que programan son el nuevo mínimo común. Pero un agente metido en tu repo sin contexto se comporta exactamente como un contratista sin onboarding: re-deriva tus convenciones desde cero, adivina los patrones, y entrega código plausible que en silencio viola tres invariantes que nadie escribió nunca. La solución no es un modelo más inteligente. Es un wiki escrito para la máquina.
Qué es un wiki para LLMs — y qué no
No es tu Confluence, y no es el README para humanos. Es el contexto que un agente carga antes de tocar tu código: las convenciones, los invariantes, el "nunca hagas X", las decisiones de arquitectura y la rareza estructural que un LLM no puede inferir del código mismo. 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 de si algo pertenece ahí es simple: ¿un buen ingeniero que nunca vio este codebase lo entendería mal? Si sí, va al wiki. Si el código ya lo dice, no.
Por qué importa: el agente es tan bueno como su contexto
- Un agente que programa sin fundamentación es el mismo modo de fallo que un RAG sin fundamentación — seguro, plausible, equivocado. Busca el patrón equivocado porque nunca vio el correcto. La answerability viene antes que la recuperación para tu código también.
- La ventana de contexto es finita y se factura. Volcar todo el repo en cada turno es lento y caro, y la mayor parte es ruido. Un wiki curado es la fundamentación eficiente — un núcleo pequeño siempre cargado más profundidad bajo demanda. (El instinto consciente del cache, aplicado a tu propio tooling.)
- Se acumula. Humanos y agentes leen la misma fuente de verdad. Menos conocimiento tribal, onboarding más rápido — para el nuevo empleado y el nuevo agente por igual.
Cómo construir uno
- Escribe lo no obvio, no lo obvio. El código ya dice qué hace. El wiki dice 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 todo depende, y por qué algo es como es. Repetir lo que el código ya dice solo quema contexto.
- Mantenlo en el repo, versionado con el código. La documentación en un wiki aparte se pudre el día que se escribe; la documentación junto al código cambia en el mismo pull request. El agente carga lo que está en el repo — así que ahí tiene que vivir la verdad.
- Estratifícalo para el presupuesto de contexto. Un archivo raíz pequeño que se carga siempre — las reglas que aplican en todos lados — apuntando a documentos más profundos por área que el agente recupera solo cuando son relevantes. La misma disciplina que cualquier sistema de recuperación: no metas toda la biblioteca en el prompt.
- Genera el mapa, cura las reglas. Auto-genera la mitad estructural — el árbol de fuentes, el mapa de módulos, los entry points. Después un humano agrega el criterio que una máquina no puede inferir. La mitad generada se mantiene actual; la mitad curada lo hace correcto.
- Trata la obsolescencia como un bug. Un wiki obsoleto es peor que ninguno: un agente seguirá una regla desactualizada con total confianza. Actualiza el wiki en el mismo PR que cambia el comportamiento, y revisa la deriva en CI — igual que atraparías cualquier otra regresión.
- Hazlo answerable. Estructúralo para que la porción correcta sea encontrable: encabezados claros, un dato por lugar, enlaces entre reglas relacionadas. El agente (y cualquier recuperación sobre él) necesita ubicar la regla relevante, no leer todo.
- Mídelo. El wiki es un sistema, así que evalúalo como uno: ¿el agente produce cambios más en-patrón y con menos reescrituras con él que sin él? Si no puedes saberlo, estás adivinando — y adivinar es justo lo que la evaluación 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 de otro modo pasaría por alto — 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 tenemos que reescribir. Es el apalancamiento más barato en la ingeniería asistida por IA, y casi nadie lo hace deliberadamente.
Un prompt para construir uno
No tienes que empezar de un archivo en blanco. Pega esto en un agente que programa, ejecútalo desde la raíz de tu repo, y responde sus preguntas — genera la mitad estructural y se detiene en el criterio que una máquina no puede inferir.
Configura un wiki para LLMs en este repo — el contexto que un agente de IA carga
antes de tocar el código. Objetivo: capturar solo lo que un agente se
equivocaría, no lo que el código ya dice. Trabaja por fases y detente para mi
input donde se marca.
REGLAS: escribe lo no obvio, nunca lo obvio. Mantenlo en el repo. Cuando dudes si
algo es un invariante real o una suposición, PREGUNTA — no inventes. Una regla
equivocada con confianza es peor que una faltante.
1. MAPA (genera): detecta stack, entry points, comandos de build/test/run, y un
mapa de estructura skimmable de 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 todo depende, convenciones no obvias, y gotchas en el historial
de git. Presenta una lista numerada de candidatos CON evidencia, luego 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 esté) con las reglas que aplican en todos lados + los
comandos + punteros a documentos más profundos por área traídos bajo demanda.
Cada regla: la regla, luego una línea de POR QUÉ.
4. VERIFICA: re-lee como un agente con cero contexto — ¿cada regla es encontrable,
inequívoca, no redundante con el código? Luego dame 5 preguntas concretas sobre
este codebase que el wiki debería responder ahora en un salto, y marca las que
no pueda. Agrega una regla de obsolescencia: actualiza este archivo en el mismo
PR que cambia el comportamiento que describe.
Después mídelo: corre una tarea real una vez con el wiki cargado y otra sin él, y compara qué tan bien cada una siguió tus convenciones y cuántas reescrituras necesitarías antes del merge. Si el wiki no mueve esa aguja, está documentando lo obvio — vuelve al paso 2 y encuentra las reglas que de verdad muerden.
La IA ya puede escribir el código. El cuello de botella se movió aguas arriba — al contexto, a lo que el agente sabe de tu sistema antes de empezar a tipear. 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 fundamentación: 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.