Docs-as-code ya era la idea correcta antes de todo esto. Pon la documentación en el repo, cámbiala con pull requests, revísala junto al código, pásala por CI. Docs en la misma vía que el código, para que se muevan juntos en vez de derivar hacia una wiki de la que nadie se fía. Si lo hacías, ibas por delante.
Luego cambió el lector. Tus docs ya no los leen solo humanos haciendo onboarding o buscando algo. Los leen agentes, antes de escribir una sola línea, para decidir qué construir y cómo. Ese único cambio convierte el docs-as-code de una disciplina sana en parte del build, y tratarlo como algo menos es como los agentes acaban construyendo lo que no es, con total seguridad.
Docs-as-code, rápido, porque el lector es listo
La mecánica no es lo interesante, así que voy corto. La documentación vive al lado del código que describe. Cambia en el mismo pull request que cambia el código. Un revisor ve los dos diffs juntos. CI puede lintarla, comprobar enlaces, montar el sitio. Nada exótico. Todo el valor está en una sola vía: cuando el código se mueve, el doc está ahí mismo en el mismo cambio, difícil de olvidar.
La alternativa, docs en un sistema aparte que se actualiza cuando alguien se acuerda, es la que se pudre. Todo el mundo ha leído una página de wiki que describe un sistema dos reescrituras por detrás y ha tenido que sacar la verdad del código a ingeniería inversa. Docs-as-code existe para poner ese fallo más difícil.
El lector ahora es una máquina, y hace lo que dicen los docs
Esto es lo que cambió de verdad. Un doc obsoleto le costaba a un humano una hora de confusión antes de mirar el código y sacar la verdad. Molesto, superable, autocorrectivo, porque los humanos desconfían de los docs y verifican.
Un agente no verifica por defecto. Lee tu AGENTS.md, tu CLAUDE.md, tus notas de arquitectura, y los trata como instrucciones. AGENTS.md está emergiendo como convención compartida justo para esto: un sitio predecible donde poner los pasos de setup, las convenciones y las restricciones que un agente debe seguir. Eso es potente y es un arma cargada. Si el fichero dice que el servicio de auth vive en una ruta donde ya no vive, o que usas una librería de la que migraste hace dos meses, el agente no se encoge de hombros ni comprueba. Construye sobre la mentira, con seguridad, a velocidad.
Así que se dieron la vuelta las apuestas. Los docs eran output, algo que producías para humanos después del trabajo. Ahora un trozo de tus docs es input, algo que los agentes consumen antes del trabajo. Un output un poco obsoleto es meramente embarazoso. Un input obsoleto es un defecto que se publica.
Y compone. Un agente lee la ruta equivocada, construye contra ella, y deja atrás código y commits que ratifican el error en silencio. El siguiente agente lee eso como confirmación. Una sola línea obsoleta no se queda en una sola línea obsoleta, siembra un pequeño montón de trabajo que concuerda todo consigo mismo y apunta todo en la dirección equivocada, y deshacerlo cuesta mucho más de lo que habría costado arreglar el doc.
El pipeline de docs pertenece al build
Si los agentes dependen de los docs, entonces mantener los docs verdaderos es asunto del build, no una tarea del equipo de documentación. De ahí salen dos movimientos.
Genera lo que puedas desde el código. Cualquier cosa que se pueda leer del fuente, el mapa de módulos, las rutas, las interfaces públicas, la lista de servicios, debería generarse, no mantenerse a mano. Los hechos mantenidos a mano derivan en cuanto alguien va con prisa. Los hechos generados no pueden mentir sobre el código, porque se leen de él. Es el mismo espíritu que el código como documentación: cuanto más cerca está el doc de la fuente de verdad, menos margen hay para que diverja en silencio.
Frena el build por deriva en el resto. No todo se puede generar. El “porqué”, las restricciones, las decisiones siguen habiendo que escribirlas. Para eso, el build debería fallar cuando un hecho documentado y un hecho real no cuadran. Si un doc dice que un fichero existe y no existe, rompe el build. Si referencia un endpoint que se borró, rompe el build. Ya frenas por los tests. Frena por los docs de los que tus agentes se van a fiar, por la misma razón: para que una afirmación falsa no llegue a producción. Esto es docs-as-code llevado a su conclusión, donde el pipeline de docs corre por la misma vía y falla con el mismo estándar que el código.
Nada de esto pide a nadie escribir más prosa. Le pide al pipeline que deje de permitir que la prosa mienta.
Tus ficheros de reglas son los docs de más apalancamiento que tienes
Ya no todos los docs pesan lo mismo. Un tutorial que se queda obsoleto malgasta la mañana de un recién llegado. Una línea obsoleta en CLAUDE.md o AGENTS.md la ejecuta cada agente en cada run, en silencio, a escala. El radio de daño es completamente distinto, y la prioridad de mantenimiento debería serlo también.
Trato esos ficheros como trato una configuración que va a producción, porque funcionalmente es lo que son. Cada afirmación en ellos es una instrucción sobre la que algún agente actuará sin comprobar. Así que el listón no es “¿esto es más o menos exacto?”. Es “¿estaría cómodo si un agente siguiera esto al pie de la letra a las 2 de la mañana sin nadie mirando?”, que es justo lo que pasa.
Ese reencuadre cambia lo que va dentro. Las aspiraciones vagas y las convenciones a medias son peores que nada, porque un agente no distingue una aspiración de una regla. Las afirmaciones concretas, actuales y verificables se ganan su sitio. Todo lo demás es una mina que te escribiste tú. La disciplina no es escribir más de estos ficheros. Es mantener las pocas líneas que tienen despiadadamente verdaderas, y dejar que el build te pille cuando no lo son.
Vivos, no solo versionados
Unos docs versionados no están automáticamente vivos. Un doc puede estar en el repo, revisado, en CI, y aun así describir un sistema que cambió en un commit que no lo tocó. Docs-as-code pone los docs en la misma vía que el código. No garantiza que se muevan.
Lo que los mueve es una conexión con el código que mantiene los dos en sincronía, para que un cambio en uno saque a la luz la obsolescencia del otro. Esa es la diferencia entre un doc meramente versionado y uno que es documentación viva, docs que dejan de pudrirse porque el sistema nota cuándo ya no cuadran. Y es el mismo motor detrás de un cerebro de producto que se mantiene solo: el conocimiento se actualiza según se mueve el código, en vez de esperar a que un humano se acuerde. La documentación interna de calidad es una de las prácticas que mejor predice si un equipo lleva bien el cambio, y ese “predice” solo se sostiene cuando los docs son verdad, que es justo el problema que el pipeline tiene que resolver.
Dónde encaja PaellaDoc
PaellaDoc construye la conexión que le falta al docs-as-code. Lee tu repo en un grafo de código, decisiones y criterios, lo mantiene al día según se mueve el código, y puede sacar a la luz cuándo un hecho documentado ya no cuadra con el fuente, para que las instrucciones que leen tus agentes sean las que siguen siendo verdad. Los docs dejan de ser algo que mantienes por culpa y se vuelven un input del que el build sí se puede fiar.
Local-first y gratis, sin nube y sin cuenta, contra el repo que ya tienes.
¿Cuál es la línea más obsoleta de tu AGENTS.md que un agente seguiría igualmente? Cuéntame en el foro.
Preguntas frecuentes
¿Qué es docs-as-code?
Tratar la documentación como código fuente: vive en el repositorio, cambia mediante pull requests, se revisa junto al código que describe y pasa por CI. El objetivo es que los docs se muevan por la misma vía que el código, para que cambien juntos en vez de separarse.
¿Cómo cambia la era de los agentes el docs-as-code?
Los docs dejan de ser solo output para humanos y se vuelven input para máquinas. Ficheros como AGENTS.md y CLAUDE.md los leen los agentes para decidir cómo construir. Eso da la vuelta a la prioridad: un doc obsoleto ya no solo confunde a un fichaje nuevo, dirige activamente al agente a construir lo que no es, así que mantenerlos verdaderos pasa a ser asunto del build.
¿El pipeline de docs debería ser parte del build?
Sí, cuando los agentes dependen de los docs. Si las instrucciones pueden separarse del código sin nada que lo detecte, se separarán, y un agente se fiará de la versión desviada. Generar los docs desde el código donde se pueda, y frenar el build cuando lo documentado y lo real no cuadran, es como mantienes el contrato veraz a velocidad de máquina.