Agentic docs: la evolución natural de jsdocs
JSDocs prometía documentación que vivía junto al código. Falló por culpa del humano. La IA finalmente cumple esa promesa — y agrega algo nuevo.
JSDocs prometió, hace dos décadas, documentación que vivía pegada al código. Si tocabas la función, tocabas su doc. Sonaba bien.
Falló por la misma razón que falla todo doc escrito a mano: el humano miente. No por mala fe — por cansancio, prisa, o porque “esto lo cambio después y actualizo la doc”. Después nunca llega. El equipo crece, el contrato deriva, los comentarios mienten y nadie confía en ellos.
La IA puede, por primera vez, romper ese ciclo. Pero no como muchos piensan.
El cambio: de declaración a observación
JSDocs era declarativo. El developer decía: “esta función recibe
user_id: string y devuelve User”. Eso era todo el contrato. Si el
código hacía otra cosa, la doc seguía diciendo lo primero.
Lo que llamamos agentic docs es observacional. Un agente lee el código real, los tests que pasan, los call sites, y los diffs recientes. Genera la doc desde lo que el código hace, no desde lo que alguien declaró que iba a hacer.
La diferencia se nota cuando alguien sube un PR que cambia el comportamiento sin tocar el comentario. JSDocs te deja con doc obsoleta. Agentic docs detecta el drift y lo marca.
Cómo se ve en la práctica
Concretemos. Lo que un agente decente produce hoy, sin curaduría humana, en una pasada sobre un repo de tamaño mediano:
- Mapas de flujo en Mermaid generados leyendo el código. No diagramas decorativos — diagramas que reflejan exactamente cómo fluye la lógica entre módulos, con qué condiciones, en qué orden.
- Snippets reales del repo embebidos donde aportan claridad. No pseudocódigo, no ejemplos inventados — el código real que ilustra el punto que está documentando.
- Explicación de alto nivel de cada módulo: para qué existe, qué responsabilidad tiene, de qué depende, qué consume y produce.
- Cross-references entre archivos: cuando un endpoint llama a un service que llama a un repo, la doc lo enlaza.
Tiempo: segundos por módulo, minutos para todo un codebase. Eso ya es 10-100x más rápido que el dev senior que documenta a mano — y con mejor precisión, porque el agente no se cansa ni se distrae ni decide que “esa parte no la documento porque ya la conozco”.
El loop que sí funciona: merge hooks
La pieza que vuelve esto sostenible es el hook de merge. Cada PR pasa por un step que:
- Identifica los bloques de código que cambiaron
- Encuentra la documentación afectada (porque la genera desde el mismo código, sabe el mapping)
- Regenera solo lo afectado, no todo
- Levanta un PR adicional (o updates en el mismo) con los cambios de doc propuestos
Cuando el PR de código se mergea, la doc actualizada se mergea también. La doc deja de envejecer. Deja de mentir. Deja de ser opcional.
El efecto secundario más valioso
Una vez que tu doc se genera observando el código, aparece un superpoder: detectar la distancia entre intent y comportamiento.
Tu ADR dice “autenticación con JWT, sin sessions”. El código tiene un endpoint que cachea en una session table para evitar pegarle a la DB en cada request. Ambas cosas son razonables — pero alguien tomó una decisión silenciosa en algún PR olvidado.
Agentic docs te lo dice: “el código actual diverge del ADR. ¿Actualizamos el ADR, o revertimos el código?”. Ese momento — donde la doc te obliga a tomar una decisión consciente — es donde aparece el valor real.
En nuestros proyectos lo usamos para mantener agenticmx-operator-docs/
co-vivo con el repo. Cuando un ADR dice una cosa y el código hace otra,
el agente lo levanta. Antes esa fricción aparecía meses después, en una
review de arquitectura. Ahora aparece en el PR.
Lo que no es agentic docs
Para evitar confusiones:
- No es generar tutoriales largos con un LLM. Eso son docs decorativas; envejecen como cualquier texto humano.
- No es un endpoint
/docsque ejecuta un LLM al vuelo cada vez. Caro, lento, no versionado. - Sí es un pipeline (commit hook, CI step, agente en background) que re-deriva los docs desde el código y los commitea o levanta un PR.
La pieza nueva es que el agente puede mantener consistencia entre múltiples artefactos que antes vivían desconectados: README, ADRs, API reference, changelog, comentarios inline. Cuando uno cambia, propone los cambios coordinados en los otros.
Hacia dónde
Lo que viene no son docs más bonitas. Son docs que no mienten y que te avisan cuando tu intent y tu código divergen. Esa es la evolución real de jsdocs, y por primera vez es viable.
Si en tu equipo están perdiendo la batalla con docs que envejecen mal, conversemos — abrimos el chat aquí mismo.