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.
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.