Documentación que se mantiene actualizada: el agente propone, tu equipo aprueba

La documentación se desactualiza por una razón poco interesante: el código cambió y actualizarla no era tarea de nadie. El README describe la configuración del año pasado. El manual operativo tiene un paso que ya no existe. El registro de decisión de arquitectura era correcto el día en que se escribió y nunca volvió a tocarse. Los ingenieros dejan de confiar en la documentación, el conocimiento se traslada a tickets, hilos de chat y la memoria de una persona, y cada cambio tarda más en revisarse y se vuelve más difícil de operar.

El código sigue siendo la fuente de verdad. El problema es mantener fiel a la realidad todo lo que lo describe — y esa es una tarea que un agente puede asumir, siempre que una persona tenga la última palabra.

El diseño que funciona

Trata la documentación como un sistema con entradas, salidas y un control de aprobación, y asigna el ciclo a un agente:

• Detectar desfases. Comparar la documentación con lo que realmente cambió: el código, la especificación de la API, la configuración, los pull requests integrados esta semana. Un documento que menciona un flag eliminado está desactualizado; también lo está un manual operativo cuyos comandos ya no coinciden con el script de despliegue.
• Preparar la actualización. READMEs, manuales operativos, guías de incorporación, documentación de integración, registros de decisiones de arquitectura. El borrador cita sus fuentes — el commit, la especificación, el diff — para que quien lo revise pueda comprobarlas en lugar de confiar en el texto.
• Escribir las notas de versión a partir de los commits. Resúmenes de cambios vinculados a los tickets y pull requests que los produjeron, sin reconstruirlos de memoria el día del lanzamiento.
• Ejecutar las comprobaciones. Compilaciones de documentación, comprobaciones de enlaces, linters y las pruebas que ejecuten los ejemplos — en CI, antes de que una persona vea el borrador.
• Abrir un pull request. Con los cambios propuestos, las fuentes utilizadas y una lista breve de revisión. El agente propone; el equipo aprueba, rechaza o comenta; cada cambio se puede rastrear hasta una revisión.

Ese último paso es la clave del diseño. Nada llega a la rama principal sin que una persona lo lea, lo que permite que la documentación detecte desfases con intensidad sin quedar equivocada en producción.

El mismo ciclo, más allá de la documentación

Una vez que el agente puede leer el repositorio, ver qué cambió y abrir un pull request revisable con evidencia, la documentación es la primera de varias tareas de mantenimiento que puede asumir:

• Actualizaciones de dependencias que siguen siendo revisables. Una actualización propuesta con el registro de cambios resumido, los puntos de llamada afectados enumerados y la ejecución de pruebas adjunta — para que quien la revise entienda el impacto antes de integrarla.
• Reportes de errores que llegan con una reproducción. Una reproducción mínima, una prueba que falle y capture el problema, una corrección propuesta y el manual operativo actualizado si cambió el comportamiento.
• Inventarios de sistemas que coinciden con la realidad. Qué servicios existen, quién es responsable de ellos y de qué dependen — regenerados a partir de lo que está en funcionamiento en lugar de una página de wiki.

Todos tienen la misma característica: el agente lee y prepara el borrador, la persona decide y la evidencia acompaña al pull request.

Qué no debería decidir el agente

No debería decidir qué es importante. Puede decirte que un documento se desactualizó; no puede decirte si ese documento importa. No debería escribir el "por qué" en un registro de decisión de arquitectura — la justificación, las alternativas consideradas, el compromiso aceptado — porque eso requiere criterio, y una justificación generada parece convincente pero no significa nada. El agente prepara el "qué"; una persona escribe el "por qué".

Y no debería integrar cambios. El día que se elimina el control de aprobación de la documentación, esta pasa a ser la opinión del agente sobre el sistema en lugar de la del equipo.

Por dónde empezar

Un repositorio, un tipo de documento. Los manuales operativos suelen ser el mejor punto de partida: se desactualizan más rápido, el desfase es peligroso y "¿este comando todavía funciona?" es algo que un agente puede comprobar en lugar de adivinar. Si los pull requests que abre merecen aprobarse durante un mes, amplía el alcance. Si no, habrás aprendido algo sobre el repositorio, no sobre el agente.