Cómo automatizamos nuestra documentación técnica con IA agéntica

La mayoría de las personas toman miles de fotos al año y nunca vuelven a mirar la mayoría de ellas. Popsa ayuda a esas personas a encontrar las que importan y las convierte en algo tangible que realmente conservarán y volverán a ver una y otra vez.

Nuestras aplicaciones móviles ejecutan aprendizaje automático en los dispositivos de los clientes para analizar las fotos (sin subirlas a la nube), seleccionar a las personas y los momentos significativos, y diseñar una composición que cuente la historia. Desde fuera parece sencillo, y esa es la clave.

Detrás de esa simplicidad hay mucha maquinaria, como las aplicaciones para iOS, Android y web; los servicios de backend que permiten gestionar los pagos y el cumplimiento de pedidos, o la infraestructura que administra el procesamiento y la entrega de imágenes en 50 países. Estos sistemas alojan las fotos más personales de los usuarios y procesan sus pagos. Deben seguir siendo fiables y seguros, y no podemos permitir que el conocimiento que tiene el equipo sobre cómo se conecta todo se quede obsoleto.

Ese conocimiento reside en la documentación que explica cómo se conectan los sistemas, cuáles son las convenciones y dónde están los límites en relación al contenido sensible. Es lo que permite a un equipo mantener, proteger y ampliar sistemas complejos sin depender de la única persona que construyó cada elemento. Sin embargo, mantener al día esa documentación es un problema con el que todo equipo de ingeniería ha lidiado en algún momento, incluido el nuestro.

He pasado por suficientes equipos de ingeniería como para conocer el ciclo. Uno de nosotros decide que «esta vez, se hará correctamente el mantenimiento de la documentación». Se dedican a ello grandes esfuerzos. Se crean páginas, se registran convenciones, se dibujan diagramas de arquitectura. A veces, los equipos cambian sistemas enteros (GitHub, Confluence, Coda), creando un nuevo impulso. Durante unas semanas, quizá un par de meses, todo se ve genial.

Luego, se queda obsoleta.

No por desidia del equipo, sino porque el cambio de software no es lineal. Puedes absorber decenas de cambios incrementales sin que la documentación se desvíe mucho, pero luego refactorizas la capa de autenticación, o migras a una nueva estructura de trabajo, o reestructuras una API. La documentación era correcta cuando se escribió, pero el código sigue avanzando. Por ejemplo, acabamos de remodelar nuestra aplicación de iOS de un flujo de navegación lineal a uno basado en pestañas. Tras un cambio de ese calibre, secciones enteras de la documentación pueden describir un sistema que ya no existe. La documentación puede quedarse obsoleta fácilmente.

La mayoría de los ingenieros saben que esto puede ser un problema, pero recientemente nuestro equipo pensó en cómo podríamos solucionarlo concibiendo la documentación como un sistema, y no como una tarea.

La brecha que nunca se ha cerrado

Muchos equipos han intentado solucionar esto antes, por supuesto. Herramientas como Javadoc, Swagger y Doxygen generan documentación directamente desde el código. Son útiles para lo que hacen (referencias de API, firmas de funciones, esquemas de endpoints), pero el resultado resulta procedimental y seco. Te dicen qué recibe y qué devuelve una función, pero no por qué el sistema se diseñó de esa manera, cuáles son las convenciones en uso o cómo encajan las piezas. La documentación que se deteriora es la escrita por humanos, como resúmenes de arquitectura o documentos de convenciones. Esa es la brecha que nunca se ha podido cerrar.

Durante años, ha resultado imposible construir mejores sistemas y, además, actualizar toda la documentación a mano, pero la IA ha cambiado esa ecuación. La brecha entre el deseo que la documentación se mantenga sola y el desarrollo de un sistema para lograrlo por fin se ha cerrado.

Nuestro equipo funciona con rapidez, intercambiando información de forma eficiente, incorporando a los nuevos ingenieros sin generar cuellos de botella y manteniendo a todo el mundo al día sobre cómo funcionan los sistemas. La documentación de alto nivel es lo que hace que eso sea posible. Cuando revisamos la nuestra recientemente, el panorama era familiar para cualquier equipo de ingeniería: una parte era buena, otra describía bases de código de hace meses y, en algunos puntos, había lagunas donde la documentación nunca había existido; el conocimiento solo estaba en la cabeza de los implicados.

Ahora, como muchos equipos, estamos utilizando cada vez más agentes de codificación por IA en nuestros repositorios, y esos agentes comparten las mismas necesidades. Con documentación de alto nivel, podemos integrar agentes al equipo de la misma manera que incorporamos a los ingenieros: «los sistemas se conectan de tal forma», «las convenciones son estas otras» y «lo que es importante para nosotros es tal y cual». Pero las audiencias, tanto humanas como mecánicas, pueden verse frustradas por el mismo problema: documentación que se escribió una vez y nunca se actualizó.

Humanos y máquinas

Esta segunda audiencia (los agentes de IA) es la responsable de que recientemente hayamos cambiado nuestra forma de ver la documentación. Esta solía ser algo que manteníamos por conveniencia humana; algo percibido como un «extra» que los equipos acababan viéndose forzados a dejar de mantener. Pero con la llegada de los agentes de IA, la documentación se ha convertido en infraestructura.

Al vernos repitiendo convenciones en varios lugares, decidimos centralizar este conocimiento. Ahora, estamos implementando archivos en todos nuestros repositorios principales (AGENTS.md, CLAUDE.md, .cursorrules), cada uno generado a partir de plantillas y con un encabezado que dirige a nuestro repositorio central de documentación.

Cuando un agente de IA empieza a trabajar en cualquier base de código de Popsa, lo primero que ve es un enlace a nuestra documentación viva. Las convenciones, los patrones, el glosario, las decisiones arquitectónicas y, lo que es más importante, el conocimiento del producto. Sin esto, ¿cómo sabría un agente que un PBK-7 es un libro de fotos de tapa dura apaisado mediano o que un TIL-2b es un panel fotográfico negro con acabado brillante?

Esto crea un ciclo muy positivo:

• Los ingenieros hacen el trabajo.

• Los agentes que revisan ese trabajo consumen la documentación para dar un feedback mejor y que tiene en cuenta el contexto del dominio.

• Ese feedback provoca cambios en el código.

• Esos cambios en el código abren solicitudes de extracción para actualizar la documentación, listas para ser revisadas y fusionadas.

La documentación actualizada queda entonces a disposición de la siguiente persona o agente que asuma una tarea. El sistema se retroalimenta y empieza a actualizarse para todos los repositorios. A medida que los nombres de productos, los marcadores de funciones y los eventos de analítica afloran en la documentación central, ese conocimiento pasa a estar disponible para los agentes que trabajan en bases de código totalmente distintas.

Si el equipo de Android lanza una nueva función y un agente revisa la solicitud de extracción equivalente de iOS semanas después, tendrá contexto suficiente para detectar si el nombre de la función no coincide o si los eventos de analítica usan convenciones diferentes. La documentación centralizada se convierte en una memoria compartida de toda la organización, no solo en una referencia para el repositorio sobre el cual fue escrita.

También tenemos en cuenta el coste. Sin una buena documentación, un agente que empieza a trabajar en un repositorio tiene que examinar la base de código desde cero: buscar archivos, leer código fuente y rastrear patrones con el comando grep. Este proceso consume tokens y tiempo en cada interacción. Con una documentación bien cuidada y actualizada, el agente lee un archivo y obtiene toda la información. Mantener los documentos al día reduce el coste por interacción de cada agente que trabaje en la organización.

Cómo funciona

Construimos un flujo. El concepto es sencillo, aunque los detalles requirieron una cuidadosa planificación.

Cuando un ingeniero fusiona código en nuestras bases de código principales (servicios de backend, aplicaciones web, iOS o Android; repositorios de infraestructura como código), se dispara una acción ligera de GitHub Actions. Esta recopila las rutas de los archivos modificados y la referencia del commit, y envía un evento repository_dispatch a nuestro repositorio central de documentación.

En el lado receptor, otro flujo de trabajo recoge el evento y hace algo muy específico:

La clave es que no lo regenera todo. Un archivo de configuración YAML mapea cada repositorio de origen con los archivos de documentación específicos sobre los que puede actuar, junto con patrones glob que definen de qué rutas de archivos se debe hacer un seguimiento. Un cambio en los módulos de Terraform no activará una actualización del documento de estándares de Go, del mismo modo que un cambio en archivos Swift no tocará las convenciones de TypeScript. Solo se examina la documentación que es realmente relevante para el cambio de código.

El flujo de trabajo activa Claude Code con una petición cuidadosamente diseñada. Claude lee la documentación existente, explora el repositorio de origen en el commit exacto que activó la actualización, compara lo que dicen los documentos con lo que realmente hace el código y propone cambios. Por supuesto, también puede informar de que no se necesitan cambios. La propia petición indica claramente lo que Claude debe y no debe hacer: preservar la estructura del documento existente, usar español de España, incluir referencias a rutas de archivos al citar ejemplos, no eliminar contenido que siga siendo preciso o no añadir contenido especulativo. Pedimos «ediciones quirúrgicas» y no «reescrituras totales».

Algunos detalles sobre cómo todo funciona en conjunto: el repositorio de documentación no hace sondeos ni programa tareas. Los repositorios de origen envían eventos cuando hay cambios, lo que significa que cualquier repositorio nuevo puede participar simplemente añadiendo un pequeño flujo de notificación y una entrada en el archivo de configuración. Solo se ejecuta una actualización de documentación por repositorio de origen a la vez. Si dos solicitudes de extracción se fusionan en rápida sucesión, la segunda actualización espera a que la primera termine en lugar de descartarse; además, Claude puede devolver NO_CHANGES_NEEDED y el flujo simplemente se cierra limpiamente. No todos los cambios de código tienen efecto sobre las convenciones documentadas, y el sistema lo tiene en cuenta como es debido.

Un detalle que nos gusta especialmente es que, durante el desarrollo, Bugbot de Cursor (un revisor de código de IA) detectó seis errores en la implementación inicial del flujo. Una IA revisando el código que se usaría para ejecutar otra IA. ¡Una especie de juego de espejos!

Hemos puesto el flujo a tu disposición como código abierto para que puedas adaptarlo a tus propios repositorios.

Revisar, no autorizar a ciegas

Aunque nos entusiasma cualquier cosa que nos ayude a ir más rápido, supervisamos y probamos estas herramientas detenidamente. El flujo de documentación automática abre una solicitud de extracción, lo que significa que los ingenieros pueden revisarla, comprobar si los cambios propuestos reflejan realmente lo que pasó en el código y evaluar la verosimilitud: «¿Es esto lo que el código hace realmente ahora?». Nuestro equipo puede aprobar, solicitar cambios u optar por cerrarla. El paso de revisión humana mantiene a los ingenieros al mando: seguimos siendo conscientes de cómo evoluciona la documentación, y nos mantenemos al día de las convenciones. Seguimos a cargo de la base de conocimientos aunque no hagamos el trabajo pesado de mantenerla.

En la era de la IA, así es como planteamos cada vez más la división del trabajo:

Construir el sistema y revisar el resultado es trabajo del ingeniero. La parte intermedia y repetitiva es trabajo de la IA. Leer un documento con la lista de cambios en el código fuente, determinar qué secciones de la documentación se ven impactadas, escribir los párrafos actualizados, ejecutar el linter, abrir la solicitud de extracción... ese es el «trabajo engorroso» y la IA es tremendamente buena en esta parte.

El patrón subyacente

Aunque construimos esto para mejorar la calidad de la documentación, nos topamos con un patrón que se extiende a toda la categoría del trabajo de ingeniería. Piensa en las tareas que todo equipo acepta que son importantes pero que nadie quiere asumir:

• Mantener la coherencia de la cobertura de las pruebas a medida que el código evoluciona.

• Mantener entradas en el registro de cambios que realmente describan lo que se ha modificado.

• Validar que los contratos de la API sigan ajustándose a sus implementaciones.

• Auditar las versiones de las dependencias.

• Actualizar los registros de decisiones de arquitectura.

Todas ellas comparten la misma estructura: hay un estado actual y un estado deseado, y el trabajo consiste en comparar ambos y proponer actualizaciones. Leer el estado actual, leer la fuente de verdad, determinar las diferencias y generar un cambio específico para la revisión humana. Ese es un patrón que la IA maneja bien, y el coste, tras la configuración, es casi cero.

Esto nos devuelve al punto de partida. Los clientes confían a Popsa sus fotos más personales y sus recuerdos de las personas y lugares que más les importan. Los sistemas detrás de esa experiencia deben ser comprendidos, mantenidos y protegidos, no solo por quienes los construyeron, sino por todos los que trabajen en ellos después. La documentación es lo que hace que eso sea posible y, por primera vez, tenemos una forma de mantenerla al día sin que se convierta en el segundo trabajo de alguien.

El resultado es un equipo que pasa menos tiempo manteniendo el conocimiento y más tiempo optimizando la experiencia: mejor selección, mejor privacidad y mejores productos. Los ingenieros se centran en el trabajo que realmente importa a las personas, y no en todo el trabajo de mantenimiento subyacente.

Para eso servía el sistema. No por la documentación en sí, sino por la libertad que ganamos para construir algo digno de los recuerdos que la gente nos confía.