La documentación técnica es como la verdura del proyecto: todo el mundo sabe que hay que comerla, nadie la quiere preparar. READMEs que se quedaron en la versión 1.0, wikis con secciones que ya no existen y un onboarding que depende de que la persona senior tenga ganas de explicar por quinta vez lo mismo. El resultado: el conocimiento crítico vive en la cabeza de tres personas, y cuando se van, se llevan el manual.

La buena noticia es que los agentes de IA pueden resolver este problema de raíz. No hablo de generar documentación genérica que nadie lee, sino de construir un sistema donde las docs se actualizan solas, al mismo ritmo que el código. En este artículo te muestro cómo.

El problema: la documentación siempre llega tarde

Vamos a ser honestos: la documentación técnica sufre de tres males crónicos.

Está desactualizada. El código cambia cada día, pero los docs se actualizan cuando alguien se acuerda. Ese desfase convierte la documentación en una fuente de errores: la persona nueva lee que la función recibe tres parámetros, pero en el código ya son cuatro.

Está dispersa. README en el repo, wiki en Confluence, comentarios en el código, especificaciones en Google Docs, respuestas en Slack. La información existe, pero nadie sabe dónde buscarla. Y quien la encuentra, no sabe si sigue vigente.

Nadie quiere mantenerla. Escribir docs es una tarea de baja recompensa inmediata. Los PRs de features pasan review; los PRs de documentación quedan en “lo reviso después”. Y después nunca llega.

El resultado es un impuesto silencioso: cada vez que alguien necesita una respuesta, paga con tiempo de interrupción de un compañero. Multiplicado por un equipo de diez, son horas de contexto perdidas por semana.

La solución: agentes que documentan mientras desarrollas

Los agentes de IA cambian la ecuación porque eliminan el costo de escribir. No se trata de “pedirle a ChatGPT que escriba la doc”, sino de integrar la generación de documentación al flujo de desarrollo, donde la información está fresca: en el PR, en el commit, en el diff.

El principio es simple: la documentación debe generarse en el mismo momento en que el código cambia, con el código como fuente de verdad. El agente lee el diff, entiende qué cambió y actualiza las secciones afectadas. Sin esperar a que un humano se acuerde.

Esto no reemplaza el criterio humano sobre el porqué de las decisiones, pero sí elimina el 80% del trabajo mecánico: actualizar firmas de funciones, reflejar cambios de comportamiento, mantener los ejemplos de uso al día.

Herramientas para montar tu pipeline de auto-docs

Hay varias formas de implementarlo, de menos a más ambiciosas:

1. Agentes en tu editor. Claude Code, Cursor y GitHub Copilot ya pueden generar y actualizar docs desde el contexto del proyecto. El truco está en el prompt: pídele que actualice el README o los docstrings cada vez que termines una tarea, no solo cuando se lo pidas explícitamente. Un AGENTS.md bien escrito le da el contexto de estilo y estructura de tu repo.

2. Agentes en CI. GitHub Actions y GitLab CI pueden ejecutar un agente en cada PR mergeado. El agente compara el diff contra la documentación existente, detecta discrepancias (una función que cambió su firma, una variable de entorno nueva, un endpoint agregado) y genera un PR de documentación automáticamente. Tú solo lo revisas y lo apruebas.

3. Auto-docs con generación de código. Herramientas como MkDocs, Sphinx o Docusaurus se combinan con agentes que extraen docstrings, comentarios y anotaciones de tipos para construir la referencia de API casi sin intervención. El agente se encarga de lo que esas herramientas no saben: redactar la narrativa y conectar los ejemplos con la realidad del código.

4. Documentación viva con agentes de lectura. Un agente que indexa tu código, tus ADRs y tus guías, y que responde preguntas del equipo con citas a la fuente. Cuando la documentación está al día y conectada, un asistente tipo RAG sobre tu propia base de conocimiento es sorprendentemente útil. La automatización mantiene los docs frescos; el RAG los hace consultables.

El flujo de trabajo que funciona

Basado en lo que hemos visto funcionar en proyectos reales, este es el flujo que recomiendo:

  1. Define el contrato. Antes de automatizar, decide qué documentación existe y quién la consume: README para usuarios del repo, guías para el equipo, referencia API para integradores. Cada audiencia tiene su archivo y su estilo.
  2. Convierte las docs en código. Mueve lo que vive en wikis sueltas al repositorio, en formato Markdown, junto al código que describen. Si no está en el repo, el agente no puede mantenerla.
  3. Configura el agente de PRs. Crea un workflow en CI que, ante cada merge, genere un PR de documentación con los cambios detectados. Empieza por los archivos de mayor rotación: README, guías de instalación, changelog.
  4. Revisa, no redactes. El equipo revisa los PRs de docs como revisa los de código. El agente propone; el humano aprueba. Así el criterio se mantiene, pero el esfuerzo mecánico desaparece.
  5. Mide. Rastrea la antigüedad de tus archivos de documentación (última modificación vs. último cambio del código que describen). El objetivo: que ninguna guía tenga más de unos días de desfase.

Lo que los agentes todavía no hacen bien

Vale la pena ser honesto sobre los límites. Un agente de documentación no sabe lo que el equipo decidió en esa reunión de arquitectura, ni por qué se eligió una solución extraña que parece un error. El porqué sigue siendo territorio humano. Por eso la receta completa combina dos cosas: automatización para el qué (lo que cambió) y hábitos de equipo para el porqué (ADRs, comentarios de decisión, notas de diseño).

Tampoco esperes que el agente escriba documentación de calidad para un código caótico. Garbage in, garbage out: si el código es ilegible, la doc generada será ilegible con esteroides. La automatización amplifica lo que ya existe; no lo repara.

Cierra la brecha de conocimiento

La documentación técnica no tiene que ser el pendiente eterno del sprint. Con agentes que la generan en el momento del cambio, una estructura de archivos que viven junto al código y un flujo de revisión ligero, puedes cerrar la brecha entre lo que el código hace y lo que el equipo sabe.

Empieza por algo chico: un workflow de CI que actualice el README de tu repo principal con cada merge. En una semana vas a notar la diferencia, y en un mes el onboarding de tu equipo va a dejar de depender de la memoria de las personas con más antigüedad.

Sigue explorando estos temas en el blog de DojoFullStack: ahí encontrarás más guías sobre agentes de código, automatización y desarrollo de software. Y si quieres llevar estas prácticas a tu equipo de forma estructurada, en DojoFullStack formamos desarrolladores que dominan la ingeniería potenciada por IA.