OpenWiki de LangChain vs cómo documentamos nosotros: dos filosofías del mismo problema

LangChain acaba de sacar OpenWiki: un agente que mantiene viva la documentación de tu repo, todos los días, en segundo plano. Me ha parecido lo bastante bueno como para pararme, mirarlo a fondo, y usarlo de espejo para contar cómo tenemos nosotros resuelto lo mismo dentro de NMC. Comparativa honesta.

TL;DR — Puntos clave

• OpenWiki es una CLI open-source de LangChain que genera la doc de tu repo en Markdown y la mantiene con un GitHub Action diario que abre PRs si la doc diverge del código.
• En NMC usamos una skill de Claude Code que documenta en Notion: tres documentos por audiencia, tres diagramas en Excalidraw+, avisos al equipo y tareas pendientes de humano.
• La diferencia de fondo es el público: OpenWiki sirve a devs en un repo; lo nuestro, a una consultora con clientes y equipos mixtos.
• Le copio dos ideas a OpenWiki: un cron diario que detecte drift y un manifest con el hash del artefacto documentado.
• La tesis compartida: la documentación no puede depender de la disciplina humana. Tiene que actualizarla un agente.

La documentación técnica siempre muere igual

Nace bien. Alguien se sienta un viernes, escribe el README, dibuja el diagrama, deja todo bonito. Y a los tres meses miente. El workflow cambió, el endpoint se movió, el prompt se reescribió, y la doc sigue contando la versión de hace tres meses. Nadie la actualiza porque actualizar docs a mano es lo primero que se cae cuando hay prisa.

LangChain acaba de sacar algo para atacar exactamente ese problema: OpenWiki. Y me ha parecido lo bastante bueno como para pararme, mirarlo a fondo, y usarlo de espejo para contar cómo tenemos nosotros resuelto lo mismo dentro de NMC.

Este artículo es esa comparativa. Honesta. Con lo que OpenWiki hace mejor y con lo que a nosotros nos hacía falta y por eso construimos algo distinto.

Qué es OpenWiki

OpenWiki es una CLI open-source. La instalas en tu repo, eliges un modelo (Sonnet, Opus, GLM, el que quieras) y te genera un directorio openwiki/ con la documentación del proyecto: arquitectura, workflow del agente, mapa de código y un quickstart. Todo en Markdown, todo dentro del repo.

Hasta ahí, nada que no haga cualquier generador de docs con un LLM detrás.

Lo bueno de verdad es otra cosa: el GitHub Action que trae de serie. Cada mañana a las 08:00 UTC corre openwiki --update, un agente compara el estado real del repo con la documentación existente y, si detecta que han divergido, abre un Pull Request con los cambios. La documentación no envejece porque no depende de que un humano se acuerde de tocarla. La mantiene un agente, todos los días, en segundo plano.

Y hay un tercer detalle fino: inyecta en AGENTS.md y CLAUDE.md un prompt para que los agentes que leen tu repo (Claude Code, Cursor, Codex) sepan que existe esa wiki y la usen como fuente de verdad. Cierra el círculo: la doc que mantiene un agente, la consumen otros agentes.

Es un diseño limpio. Si tu equipo son cinco desarrolladores viviendo en un mono-repo en Markdown, instálalo hoy. Resuelve tu problema.

Cómo lo tenemos nosotros

En NMC llevamos meses con una skill de Claude Code que se llama documentador-proyectos. Cuando arranco algo nuevo —un workflow n8n, una web app, una VM con Chatwoot, una integración— la skill se dispara sola y, en la misma sesión de chat, sin que yo salga de Claude Code, hace toda la documentación.

Pero la hace para nuestra realidad, que no es la de cinco devs en un repo. Es la de una consultora: clientes, equipos mixtos, gente no técnica que opera automatizaciones que nunca leerá el código que las mueve.

Esto es lo que produce:

1. Crea el proyecto en Notion, no en el repo, con la plantilla oficial del workspace.
2. Genera tres páginas de documentación, una por audiencia.
3. Pinta tres diagramas en Excalidraw+ con paleta Clean UI: visión general, flujo operativo y arquitectura detallada.
4. Publica un aviso en la base de datos de Anuncios, enlazado al proyecto, para que el equipo se entere.
5. Crea las tareas pendientes de humano en la base de datos de Tareas: montar credenciales, hacer el login manual, revisar end-to-end.
6. Para los workflows n8n, baja el JSON crudo, los prompts del LLM y el código de los Code nodes al repo, cada cosa en su archivo, versionado en git.

Todo esto en un solo pase, sin salir del chat.

La comparativa, en una tabla

La arquitectura de nuestra skill, por dentro

Merece la pena bajar un nivel en tres decisiones de diseño, porque son las que marcan la diferencia real con OpenWiki.

Tres audiencias, tres documentos

La skill no genera "una doc". Genera tres, deliberadamente separadas:

• Guía de Uso — Para cualquiera del equipo, sin jerga. El que opera el sistema no necesita saber qué prompt usa el LLM Chain. Necesita saber qué botón toca y qué pasa cuando lo toca.
• Doc Técnica — Para el dev que va a mantenerla. Aquí sí va todo: nodos, prompts, credenciales, ramas de decisión.
• Informe QA — Para saber qué falta por auditar.

La razón de separarlas es simple: si sirves a las tres audiencias con el mismo documento, obligas a que ninguna lo lea. El comercial se pierde en el detalle técnico, el dev se aburre con la explicación de alto nivel, y al final nadie abre el documento. Tres audiencias, tres documentos, cada uno legible para quien va dirigido.

El QA como entidad de primera clase

Esta es probablemente la diferencia más importante y la que menos se ve. La Doc Técnica cuenta lo que el sistema hace. El Informe QA cuenta lo que todavía no hemos probado. Son cosas distintas. Una doc que solo describe el camino feliz miente por omisión: te da confianza sobre partes del sistema que nadie ha validado. Al separar el QA en su propio documento, dejamos explícito el borde entre "esto funciona y lo hemos comprobado" y "esto debería funcionar pero aún no lo hemos verificado". OpenWiki no tiene concepto de esto.

La copia local del workflow

Para cada workflow n8n, la skill baja a git tres cosas: el JSON crudo del workflow, los prompts de cada nodo LLM en archivos separados, y el código de los Code nodes también en archivos propios. ¿Por qué? Porque tener el artefacto versionado me permite hacer git diff entre dos versiones de un workflow, revisar cambios en un Pull Request, y auditar qué cambió sin tener que abrir n8n y comparar a ojo. OpenWiki documenta el repo, pero no tiene concepto de "artefacto operativo" que vive fuera del código fuente y que hay que versionar aparte.

Por qué Notion y no Markdown en el repo

Es la decisión de fondo, y es de negocio, no técnica.

En el repo solo entran los desarrolladores. En Notion entra el equipo, el cliente cuando toca enseñarle algo, y yo desde el móvil un domingo por la tarde cuando quiero revisar el estado de un proyecto sin encender el portátil.

"La documentación importante de una consultora no puede vivir en un sitio donde solo entran cuatro programadores. Tiene que estar donde vive el negocio. Y el negocio vive en Notion."

Un flujo de n8n, además, no se entiende leyendo texto. Se entiende viendo el diagrama: los servicios conectados, las ramas de decisión pintadas, por dónde entra el dato y por dónde sale. Por eso pintamos tres diagramas por proyecto. OpenWiki es solo texto, y para un repo de código puro está bien. Para explicar una automatización a alguien que no lee JSON, no llega.

Qué le copio a OpenWiki

Aquí es donde el ejercicio se vuelve útil de verdad. Porque mirar bien una herramienta ajena siempre te enseña algo del hueco que tienes en la tuya. Y OpenWiki me ha marcado dos, sin vergüenza ninguna en copiarlos:

1. Un cron diario que detecte drift

Hoy nuestra skill se dispara conversacionalmente: yo abro Claude Code, arranco algo, y la skill documenta. Pero si tres semanas después toco el workflow y no vuelvo a invocarla, la doc se queda vieja y nadie se entera. Voy a montar un cron local que, cada día, recorra los proyectos activos, compare el estado real (el JSON del workflow en n8n, el código en el repo) con la Doc Técnica de Notion, y si divergen abra una entrada en la DB de Anuncios avisando de que la documentación está desactualizada. Exactamente la idea del GitHub Action de OpenWiki, pero aterrizada en nuestro stack: en vez de abrir un PR en GitHub, abre un aviso en Notion.

2. Un manifest .last-update.json por proyecto

La idea es guardar el hash (SHA) del artefacto que la Doc Técnica describe. Si el SHA del workflow cambia y la doc no se ha tocado, la marcamos como stale. Es un trigger claro, binario, sin ambigüedad: código nuevo + doc vieja = refrescar. Sin depender de que yo me acuerde.

Lo tercero que hace OpenWiki —inyectar en CLAUDE.md el prompt que apunta a la wiki como fuente— ya lo hacemos, pero de forma informal. Voy a formalizarlo con el mismo patrón: dejar explícito en el CLAUDE.md de cada proyecto que la fuente de verdad es la doc de Notion, para que cualquier agente que abra el repo lo sepa.

La tesis que compartimos

Los dos enfoques, el de LangChain y el nuestro, parten de la misma idea. Y creo que es la buena:

La documentación no puede depender de la disciplina humana para mantenerse viva. Tiene que actualizarla un agente.

La disciplina humana falla. Siempre. No por vagancia, sino porque actualizar docs es lo primero que se sacrifica cuando hay que entregar. La única forma de que la documentación siga siendo verdad es sacar al humano del bucle de mantenimiento y meter ahí a un agente que no se cansa, no tiene prisa y corre todos los días.

OpenWiki lo resuelve para un repo de código y un equipo de devs. Nosotros lo resolvemos para una consultora con clientes, equipos mixtos y automatizaciones que operan personas que no leen código. Herramientas distintas, mismo principio. Y por eso, aunque OpenWiki me ha gustado mucho, seguimos con lo nuestro: porque nuestro problema es más ancho que un repo.

---

¿Quieres ver el sistema por dentro?

El detalle completo de cómo montamos el sistema — la arquitectura de la skill, los tres diagramas de ejemplo y el cron de drift cuando esté en producción. Escríbeme y te lo enseño.

Escríbeme

Preguntas frecuentes

¿Qué es OpenWiki de LangChain?

OpenWiki es una CLI open-source de LangChain. La instalas en tu repo, eliges un modelo (Sonnet, Opus, GLM) y genera un directorio openwiki/ con la documentación del proyecto: arquitectura, workflow del agente, mapa de código y un quickstart. Todo en Markdown, todo dentro del repo.

¿Cómo mantiene OpenWiki la documentación actualizada?

Con un GitHub Action que trae de serie. Cada mañana a las 08:00 UTC corre openwiki --update: un agente compara el estado real del repo con la documentación existente y, si detecta que han divergido, abre un Pull Request con los cambios. La doc no envejece porque no depende de que un humano se acuerde de tocarla.

¿Por qué documentar en Notion y no en Markdown en el repo?

Es una decisión de negocio, no técnica. En el repo solo entran los desarrolladores. En Notion entra el equipo, el cliente cuando toca enseñarle algo, y el móvil un domingo por la tarde. La documentación importante de una consultora tiene que estar donde vive el negocio, y el negocio vive en Notion. Además, un flujo de n8n se entiende viendo el diagrama, no leyendo texto.

¿Qué ideas de OpenWiki merece la pena copiar?

Dos: un cron diario que detecte drift entre el estado real del sistema y la documentación (en nuestro stack, abre un aviso en Notion en vez de un PR en GitHub), y un manifest .last-update.json por proyecto con el hash del artefacto documentado. Si el SHA cambia y la doc no se ha tocado, la doc está stale: código nuevo + doc vieja = refrescar.