OpenWiki: la documentación que se mantiene sola
Introducción
Todos conocemos el patrón: el proyecto arranca con un README cuidado, tal vez un par de diagramas, quizás hasta una wiki. Pasan tres sprints, el código cambió por completo, y esa documentación sigue hablando de una arquitectura que ya no existe. Nadie la borra porque "algún día la actualizamos", y nadie la actualiza porque siempre hay algo más urgente. La documentación no muere, simplemente se vuelve mentirosa. Y el equipo de LangChain decidió atacar ese problema con OpenWiki, una CLI que le da a un agente la responsabilidad de escribir y mantener la documentación de tu repositorio.
El problema es mantenerlas
Escribir documentación una vez no es tan difícil. El problema real es la segunda parte: mantenerla sincronizada con un código que cambia todos los días. Cada PR que renombra una función, cada refactor que mueve un módulo, cada endpoint nuevo, es una oportunidad más para que la documentación se desactualice un poco más.
OpenWiki parte de una premisa directa: si un agente ya puede leer tu código, entender tu historial de Git y escribir texto coherente, ¿por qué no delegarle también el trabajo de mantener la wiki al día? No como un generador de docs que corre una vez y ya, sino como un proceso continuo que se ejecuta cada vez que el repositorio cambia.
¿Qué es OpenWiki?
Es un paquete de pnpm que instalas de forma global:
pnpm install -g openwiki
Y que corres dentro de cualquier repositorio:
openwiki --init
La primera vez que lo corres, te pide configurar tu proveedor de inferencia (OpenRouter, Anthropic, OpenAI, Fireworks o Baseten), tu API key y el modelo que quieres usar. Esa configuración se guarda en ~/.openwiki/.env, no en el repositorio, así que no hay riesgo de subir credenciales por accidente.
Con eso resuelto, el agente entra al repositorio, lo explora, y genera documentación inicial dentro de una carpeta openwiki/. Si esa carpeta ya existe, en lugar de generar todo de cero, refresca lo que cambió.
Cómo funciona por dentro
Lo interesante de OpenWiki no es solo que "genera markdown con IA", eso ya lo hace medio internet. Lo interesante es cómo evita los dos problemas típicos de este tipo de herramientas: alucinar contenido y generar ruido innecesario en cada corrida.
Evidencia real de Git, no suposiciones
Antes de que el modelo escriba una sola línea, OpenWiki recolecta evidencia real del repositorio en el proceso host:
git status --shortgit rev-parse HEAD- el historial de commits reciente (o el rango exacto desde la última actualización exitosa, si ya existe metadata previa)
git diff --name-status HEAD
Esa evidencia se le entrega al agente como contexto, en lugar de dejar que "adivine" qué cambió. El agente corre sobre un backend de shell local de DeepAgents, en modo virtual, con acceso de solo lectura al filesystem del repositorio, y con un checkpointer en SQLite (~/.openwiki/openwiki.sqlite) que persiste el hilo de conversación entre corridas.
El snapshot anti-ruido en CI
Este es el detalle que más me gustó del diseño. Después de cada corrida de --init o --update, OpenWiki calcula un hash SHA-256 de todo el contenido de openwiki/ (sin contar el propio archivo de metadata) y lo compara contra el snapshot de antes de correr el agente.
Si el hash no cambió, no se escribe metadata nueva. Es decir, si el agente concluye que no hay nada que actualizar, la corrida no genera un commit vacío ni ensucia el historial. Para un workflow que corre todos los días en CI, esto es la diferencia entre una automatización útil y una que satura tu repositorio de PRs vacíos.
Se integra en tu flujo
OpenWiki no se queda encerrado en su propia carpeta. Al correr --init, también agrega (o refresca) una sección estandarizada en tu AGENTS.md y/o CLAUDE.md, indicándole a tu agente de código que consulte openwiki/ como fuente de contexto. Es decir, la documentación que este agente escribe termina siendo la misma que usan Claude Code, Cursor o cualquier otro agente cuando trabajan en tu repo.
Probándolo en NeoComposer
Para no quedarme solo con la teoría, corrí openwiki --init en NeoComposer, mi cliente de correo terminal-first en Python. El agente exploró el repo y generó esto:
openwiki/
├── quickstart.md
├── architecture/overview.md
├── domain/data-and-templates.md
├── operations/setup.md
└── testing.md
El quickstart.md no es un resumen genérico, apunta a archivos reales del repo:
## Source anchors
- CLI entrypoint: `src/neocomposer/main.py`
- Orchestrator: `src/neocomposer/email_client.py`
- Configuration loader: `src/neocomposer/config_manager.py`
- Contacts manager: `src/neocomposer/contacts_manager.py`
- Templates manager: `src/neocomposer/templates_manager.py`
Y el commit que generó trae su propia justificación, sin que yo escribiera una línea:
docs(openwiki): add repository documentation guide
Add OpenWiki documentation covering NeoComposer architecture, CLI workflows,
domain data, setup, and testing guidance.
Include agent instructions to start from the OpenWiki quickstart and add a
local CodeGraph ignore file to keep transient graph data out of version
control.
También actualizó mi AGENTS.md con la sección estandarizada que mencioné arriba, así que ahora Claude Code arranca leyendo openwiki/quickstart.md antes de tocar código en ese repo.
Visualizador
Además, OpenWiki trae un visualizador web que te permite navegar la documentación generada, con un buscador y un árbol de navegación lateral. Lo que permite ver de un vistazo a la documentación generada y cómo se relaciona con el código real. Para levantarlo, basta con correr:
openwiki visualize
Y mostrará algo como esto:
Automatizarlo con GitHub Actions
Para que la documentación se mantenga sola de verdad, sin que nadie tenga que acordarse de correr openwiki --update, el proyecto trae un workflow listo para copiar:
name: OpenWiki Update
on:
workflow_dispatch:
schedule:
- cron: "0 8 * * *"
permissions:
contents: write
jobs:
update:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- uses: actions/setup-node@v4
with:
node-version: "22"
- name: Install OpenWiki
run: pnpm install --global openwiki
- name: Run OpenWiki
run: openwiki --update --print
env:
OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }}
OPENWIKI_MODEL_ID: z-ai/glm-5.2
LANGSMITH_API_KEY: ${{ secrets.LANGSMITH_API_KEY }}
LANGCHAIN_PROJECT: openwiki
LANGCHAIN_TRACING_V2: "true"
- name: Create OpenWiki update pull request
uses: peter-evans/create-pull-request@v7
with:
add-paths: openwiki
branch: openwiki/update
commit-message: "docs: update OpenWiki"
title: "docs: update OpenWiki"
Todos los días a las 8:00 UTC, el Action corre openwiki --update --print (la variante no interactiva) y, si hubo cambios reales, abre un PR con la documentación al día. Nadie tiene que acordarse de nada. La documentación deja de depender de la disciplina del equipo y pasa a depender de un cron.
Proveedores soportados
OpenWiki no te ata a un solo proveedor de inferencia:
| Proveedor | Uso típico |
|---|---|
| OpenRouter | Proveedor por defecto, con fallback automático entre modelos si hay errores 5xx |
| Anthropic | Cliente directo vía @langchain/anthropic |
| OpenAI | Cliente OpenAI-compatible |
| Fireworks / Baseten | Clientes OpenAI-compatible con baseURL propio |
Si usas OpenRouter (el default), OpenWiki incluso reintenta automáticamente contra una lista de modelos de respaldo si el proveedor principal falla del lado del servidor, sin perder el contexto de la corrida.
El verdadero acierto
Cualquiera puede conectar un LLM a un repositorio y pedirle "genera documentación". El mérito de OpenWiki está en los detalles que casi nadie se molesta en resolver: evidencia de Git real en lugar de alucinaciones, un snapshot que evita PRs vacíos, y una integración explícita con AGENTS.md/CLAUDE.md para que la documentación no viva aislada de las herramientas que ya usas para programar.
No resuelve el problema de raíz de "a nadie le gusta escribir docs", pero sí resuelve el problema práctico de que, aunque a nadie le guste, ahora tampoco tiene que hacerlo nadie.
Conclusión
Desde La Cueva del NeanderTech creemos que la documentación desactualizada no es un problema de falta de voluntad, es un problema de que mantenerla al día compite por tiempo contra features y bugs, y casi siempre pierde. OpenWiki no le pide más disciplina al equipo, le quita el trabajo de encima y se lo da a un agente que sí tiene tiempo todos los días a las 8:00 UTC.
Si mantienes un proyecto donde el README y la wiki llevan meses sin tocarse, vale la pena instalarlo, correr --init una vez, y dejar que el Action haga el resto.
"Code is no more inherently clear than any other form of documentation."
