Cuando los agentes IA mantienen tu documentación: aciertos del pattern de Karpathy y sus límites en la práctica

Hay un momento en la vida de todo equipo en el que se acepta una verdad incómoda: la documentación está rota. El wiki corporativo que nadie mantiene va perdiendo utilidad mes a mes. El pipeline de RAG que conecta los LLMs a "todo lo que sabemos" responde cada query desde cero, sin acumular. Andrej Karpathy publicó en 2026 un gist corto proponiendo una tercera vía: un LLM Wiki — una base de conocimiento markdown mantenida por agentes IA que compone valor con el tiempo.

El patrón es elegante y, en lo esencial, correcto. Pero cuando lo llevás del uso personal al uso en equipo, emergen decisiones nuevas que el gist no resuelve. Este artículo hace dos cosas: reconoce sus aciertos y describe los cuatro matices que vas a tener que pensar si querés implementarlo con más de una persona escribiendo — humanos, agentes, o ambos.

Por qué la propuesta de Karpathy es correcta

Karpathy articula con precisión el problema central de cómo los LLMs interactúan con documentos hoy. En un pipeline clásico de retrieval-augmented generation (RAG), el modelo recupera chunks relevantes a cada query y genera una respuesta. Funciona. Pero el conocimiento no se construye: cada respuesta re-descubre la síntesis desde cero. Cinco preguntas sobre el mismo tema generan cinco cadenas de razonamiento duplicadas.

Y la alternativa tradicional — el wiki humano — falla por agotamiento. La lectura y el pensamiento no son lo tedioso. Lo tedioso es el bookkeeping: actualizar cross-referencias, mantener resúmenes al día, flagear contradicciones, sostener consistencia en 40 páginas. Los humanos abandonan wikis porque el costo de mantenimiento crece más rápido que el valor que reciben a cambio.

La propuesta de Karpathy sale del lazo: el wiki es un artefacto persistente, pero el bookkeeping lo hace el LLM. El humano cura fuentes, explora, pregunta. El LLM resume, enlaza, archiva, flagea. Un paper nuevo entra al stock de raw sources y el agente toca 10 o 15 páginas del wiki en una sola pasada. El wiki se mantiene porque el costo de mantenimiento se acerca a cero.

La arquitectura que plantea tiene tres capas: raw sources inmutables, un wiki markdown generado por el LLM, y un archivo de schema (CLAUDE.md, AGENTS.md o similar) que le dice al agente cómo está organizado todo. Elegante, minimalista, fundamentalmente correcta.

Principio: El conocimiento útil no se re-deriva en cada query. Se compila una vez y se mantiene al día.

Primer matiz: dónde viven las fuentes

Karpathy ubica los raw sources dentro del mismo repo que el wiki, en subcarpetas separadas (por ejemplo raw/ y wiki/). Para uso personal con Obsidian funciona bien: todo está en un directorio, el Web Clipper pega artículos ahí, la línea entre "lo que leíste" y "lo que concluiste" es clara.

En equipo el modelo se rompe. Las fuentes que consume un equipo son heterogéneas y viven en plataformas distintas: papers en Zotero, threads en Slack, grabaciones en Fireflies u Otter, correos en Gmail, PDFs en Drive. Forzar una réplica local de todo eso en un repo es duplicación sin beneficio, y peor, pretende dar inmutabilidad a algo que maneja otra plataforma.

La salida correcta es aceptar que el wiki layer y el sources layer son sistemas diferentes. El wiki guarda síntesis; las fuentes viven donde nacen. La pieza crítica es la citación: cuando un agente escribe algo sintetizado a partir de material externo, tiene que dejar rastro de qué consultó. Si no, el claim se vuelve folklore — nadie puede verificar de dónde salió ni si sigue vigente.

El patrón recomendado es dual. Por un lado una sección ## Fuentes al final del doc — humano-legible, versionable en git, que rinde en cualquier renderer markdown. Por otro, un campo de metadata estructurada (frontmatter YAML, o una columna JSONB en una DB, o el equivalente en tu stack) con la misma lista parseable por máquina. Dos representaciones de la misma verdad porque sirven a dos consumidores distintos.

Si eso suena a trabajo duplicado, pensalo así: la metadata estructurada es lo que te permite, más adelante, detectar que una fuente se actualizó, y por lo tanto los docs que la citan deberían revisarse. Ese uso compensa el costo.

Principio: La inmutabilidad de las fuentes nace de no tocarlas, no de copiarlas. Citar es suficiente.

Segundo matiz: el grafo explícito que los LLMs no necesitan

En un wiki markdown hay dos grafos superpuestos. Uno es el explícito: los links [texto](./otro.md) que un humano ve cuando abre el archivo. El otro es el semántico: la proximidad entre docs que los embeddings capturan.

Los agentes no necesitan el explícito. Navegan por similarity — "dame los 5 chunks más relevantes a esta query" es un índice vectorial, no un seguimiento de links. Los humanos sí lo necesitan: cuando alguien abre el repo en GitHub u Obsidian, los links explícitos son lo que convierten documentos aislados en una red navegable.

Cuando es el LLM el que escribe el wiki, ese grafo explícito se degrada en silencio. El agente agrega un nuevo doc y olvida linkearlo desde los docs relacionados. Agrega un link de A hacia B pero olvida el backlink de B hacia A. Seis meses después tenés 80 docs, de los cuales solo 20 están bien conectados, y nadie lo notó porque el agente seguía respondiendo preguntas sin problema vía embeddings.

La solución es tratar el grafo explícito como un producto aparte y auditarlo activamente. Tres señales útiles a computar:

• Huérfanos: docs sin links entrantes ni salientes. Ningún humano los encuentra navegando.
• Unidireccionales: docs con solo incoming o solo outgoing. Señal de que falta un backlink.
• Pares semánticamente cercanos sin link: docs con alta similarity vectorial pero sin link markdown entre ellos. Candidatos reales al cross-linking que el agente no vio.

Los tres son queries baratas si materializás el grafo en una tabla aparte (origen, destino, anchor, heading de la sección donde vive el link). El costo de mantenerla es marginal comparado con re-indexar embeddings, y el valor para los humanos del equipo es alto.

Principio: El grafo explícito no es un subproducto del grafo semántico. Es una vista distinta, con un consumidor distinto, y merece su propia disciplina de salud.

Tercer matiz: dos agentes escribiendo al mismo tiempo

En el setup personal de Karpathy hay un único agente tocando el wiki, generalmente con supervisión humana directa en la misma ventana. Los write conflicts son imposibles: solo hay un escritor.

En equipo, el modelo se rompe inmediatamente. Un agente está resumiendo una reunión mientras otro ingesta un paper; ambos tocan el doc arquitectura.md en secciones distintas. Sin coordinación, el último commit gana. Cinco minutos de análisis se sobrescriben en silencio. Nadie detecta la pérdida hasta días después cuando un tercero nota "esto antes decía otra cosa".

El patrón recomendado es viejo y sólido: optimistic locking por content hash. Antes de escribir una sección, el agente lee la versión actual y recibe un hash. Al escribir, pasa ese hash como expected_version. Si la versión actual en el servidor no coincide — porque otro agente escribió entre medio —, el sistema responde version_mismatch con la versión actual y deja que el agente reconcilie en vez de sobrescribir.

Es el mismo patrón que usan sistemas distribuidos desde hace décadas:

• En CouchDB y Cloudant, cada documento lleva un _rev que debés mandar al actualizar.
• En DynamoDB, hacés ConditionExpression sobre un atributo de versión.
• En PostgreSQL, UPDATE ... WHERE version = :expected y chequeás rowcount.
• En Redis, WATCH + MULTI/EXEC aborta la transacción si la clave cambió.
• En HTTP REST, ETag + If-Match.
• En git, git push rechaza un push no fast-forward.

Cambia la forma, no la idea. Y es la diferencia entre "wiki de uno" y "wiki de varios". Muchos proyectos LLM-wiki open source no lo implementan — sirve bien al autor solo y se rompe en la adopción en equipo.

Principio: La colaboración entre agentes exige las mismas disciplinas de concurrencia que entre humanos. Quizás más, porque los agentes escriben más rápido.

Cuarto matiz: el lint no es una operación, son varias

Karpathy describe el lint como un pass periódico: "pedile al LLM que busque contradicciones entre páginas, claims obsoletos, docs huérfanos, conceptos sin página dedicada, cross-references faltantes, gaps de data que podrían llenarse con búsqueda web". En un párrafo es simple. En la práctica, cada uno tiene costo, cadencia y disparador distintos.

Meter todo esto bajo un solo tool "lint" invocado manualmente es una simplificación que no sobrevive al crecimiento. Conviene separarlo en buckets que se computan independientemente, con cadencias distintas: los baratos en cada query, los caros en background.

Para el caso más caro (contradicciones), el riesgo es que el costo explota con el tamaño del wiki. Sin controles, comparar cada par de chunks da O(N²) llamadas a un LLM. Con 1000 docs y cinco chunks cada uno, son 12 millones de pares. Insostenible.

Tres controles que mantienen el costo lineal:

1. Top-K vecinos por chunk en vez de "todos los pares con similarity alta". Cada chunk chequea solo sus 3 vecinos más cercanos. El costo crece lineal en número de chunks, no cuadrático.
2. Delta mode: solo re-chequear pares que involucran chunks editados desde la última corrida. En steady state el costo escala con la velocidad de edición, no con el tamaño total.
3. Budget cap por tenant: un techo de calls al mes. Si se alcanza, pausa y prioriza re-verificar hallazgos existentes de alta severidad. Garantiza costos predecibles.

Con estos tres controles, un wiki de 10.000 docs que nadie edita cuesta casi lo mismo que uno de 50 muy activo. La explosión combinatoria desaparece. Y si tenés tracking de sources bien hecho (primer matiz), "stale claims" se resuelve prácticamente gratis usando las fechas de retrieval.

Principio: Los features caros se diseñan con límites desde el día uno. Optimizar tarde es más costoso que limitar temprano.

Checklist antes de implementar el patrón en tu equipo

Si decidís ir por el pattern de Karpathy adaptado a equipos, estos son los ejes a pensar desde el inicio:

1. ¿Dónde viven las fuentes y cómo las cita el agente al escribir? ¿Tenés representación dual, humano-legible y estructurada?
2. ¿Cómo detectás y reportás docs huérfanos, unidireccionales, y pares semánticamente cercanos sin link? ¿El grafo explícito está materializado en una tabla que podés consultar?
3. ¿Qué mecanismo de concurrencia usás cuando dos agentes — o un agente y un humano — pueden editar el mismo doc? ¿Estás en optimistic locking o en "el último gana"?
4. ¿Separaste el lint en buckets con costos y cadencias distintas? ¿Tenés budget caps para los features LLM-pesados?

Ninguno es una decisión arquitectónica grande. Todos son detalles pequeños que, omitidos, vuelven al wiki ingobernable en 3 a 6 meses de crecimiento.

Una nota desde la trinchera

Nosotros llegamos a estos matices como un equipo que trabaja con agentes IA a diario y necesitaba una base de conocimiento compartida entre personas y agentes. El wiki local tradicional — un Obsidian en la máquina de cada uno, sincronizado a medias por Drive — se nos quedó chico rápido. No podíamos garantizar que todos veíamos la misma versión, ni auditar qué había escrito quién sin pedir permisos, ni evitar que dos agentes en paralelo se pisaran al resumir distintas partes de una reunión larga.

Construimos Blenau para resolver exactamente los cuatro matices descritos acá, en un producto que cualquier equipo en la misma situación puede adoptar: una capa de wiki compartida donde el git del equipo sigue siendo la fuente de verdad, con la auditoría automatizada en los cuatro ejes, locking optimista entre agentes, y tracking de fuentes incorporado desde el inicio. Si preferís implementar tu propia versión del patrón, el gist original de Karpathy sigue siendo un excelente punto de partida — y los cuatro matices de este artículo son las piezas que vas a terminar agregando igual.

La infraestructura de conocimiento compartido siempre fue un problema humano. Lo que cambió es quién hace el bookkeeping, y todo lo que eso te obliga a repensar.