Documentación como código: documentación técnica sincronizada con las versiones
Cómo las prácticas de documentación como código ayudan a mantener la documentación técnica del Reglamento de IA al ritmo de cada cambio en el código.
Conclusiones clave
- 1.Los proveedores de sistemas de IA de alto riesgo deben mantener actualizada la documentación técnica (artículo 11, apartado 1).
- 2.La documentación como código mantiene la documentación técnica bajo control de versiones, junto al código.
- 3.Algunas partes pueden generarse a partir del código y de los datos del pipeline. Las decisiones que requieren criterio necesitan personas.
- 4.El control de versiones muestra qué cambió y cuándo, no que el contenido sea correcto.
La obligación recae en los proveedores de sistemas de IA de alto riesgo. Se aplica a quienes los introducen en el mercado de la UE o los ponen en servicio, según el artículo 2, apartado 1, letra a). El anexo IV enumera lo que debe contener la documentación. El anexo III es la lista de usos de alto riesgo del Reglamento, como la selección de personal. El anexo I afecta a la IA en productos sujetos a la normativa de seguridad de la UE. La sección A del anexo I enumera normas de productos, como las de juguetes y productos sanitarios. La sección B enumera otras normas de productos. Para los sistemas del anexo III, la obligación se aplica desde el 2 de diciembre de 2027. Para los sistemas de la sección A del anexo I, se aplica desde el 2 de agosto de 2028 (Reglamento (UE) 2026/1744). Los sistemas introducidos en el mercado o puestos en servicio antes de esas fechas se rigen por el artículo 111, apartado 2. Esta disposición fue sustituida por el Reglamento (UE) 2026/1744. Salvo los sistemas del artículo 111, apartado 1, solo quedan cubiertos si, desde la fecha aplicable, sufren cambios significativos en su diseño. Para sistemas destinados a autoridades públicas, el artículo 111, apartado 2, exige adoptar las medidas necesarias para cumplir para el 2 de agosto de 2030.
Para los sistemas de alto riesgo vinculados a productos de la sección B del anexo I, el artículo 2, apartado 2, limita las disposiciones aplicables. Solo se aplican el artículo 6, apartado 1 (clasificación), y los artículos 102 a 112 (disposiciones finales). También se aplica el artículo 60a (pruebas en condiciones reales fuera de los espacios de pruebas). Los artículos 57 a 59 tratan de los espacios controlados de pruebas para la IA. Solo se aplican en la medida en que esas normas integren los requisitos del Reglamento sobre IA de alto riesgo. El artículo 11 no figura entre ellas.
Las obligaciones del proveedor figuran en el artículo 16. Incumplirlas puede costar hasta 15 millones de EUR o, para una empresa, el 3 % del volumen de negocios anual mundial (artículo 99, apartado 4). Se aplica la cifra más alta. Para las microempresas, pequeñas y medianas empresas (pymes, artículo 3, punto 14a), se aplica la más baja (artículo 99, apartado 6).
Con la documentación como código, los cambios se revisan en pull requests y cada versión se vincula a una release. Siguiente paso: compruebe, con la tabla de abajo, cuáles de los nueve puntos del anexo IV puede generar a partir de su repositorio.
Por qué se desfasan los documentos que están fuera del repositorio
Los documentos en archivos de Word, PDF o wikis están separados del código que describen.
Un documento puede describir una versión antigua
La actualización es trabajo manual
Qué significa la documentación como código en la práctica
La documentación como código aplica prácticas de ingeniería de software a la documentación técnica:
Control de versiones
La documentación técnica está en el mismo repositorio Git que el código. Cada cambio es un commit con autor, fecha y diff, de modo que puede asociar una versión del documento a una versión del código.
Generación siempre que sea posible
Algunas secciones pueden generarse a partir del código, como muestra la tabla de abajo. Las secciones que requieren criterio las escriben personas.
Comprobaciones en el pipeline
Su equipo puede escribir una regla de pipeline que haga fallar un pull request cuando cambia el modelo pero no la sección correspondiente del documento. El Reglamento no lo exige.
Paquetes de release
Cada release agrupa los documentos con la versión del software, de modo que puede obtener la documentación que correspondía a una release concreta.
La generación ayuda más en unos puntos del anexo IV que en otros
La generación ayuda algo en 4 de los 9 puntos del anexo IV, poco en 4 y nada en 1. Las dos columnas de la derecha son nuestra valoración, no la del Reglamento.
Las pymes y las SMC (pequeñas empresas de mediana capitalización, artículo 3, punto 14b) pueden presentar los elementos del anexo IV de forma simplificada. Así lo establece el artículo 11, apartado 1, en la redacción del Reglamento (UE) 2026/1744. Quienes lo hagan deben usar el formulario simplificado que la Comisión debe establecer. La cuantía más baja de la multa también se aplica a las SMC (artículo 99, apartado 6a).
| Punto del anexo IV | Enfoque posible | Ayuda de la generación |
|---|---|---|
| 1. Descripción general del sistema de IA | Nombres y versiones a partir del manifiesto, el README y los metadatos de la release | En parte |
| 2. Elementos del sistema y de su proceso de desarrollo | Descripciones de la arquitectura y del pipeline a partir del código; la justificación del diseño la redactan personas | En parte |
| 3. Seguimiento, funcionamiento y control | Cifras de exactitud a partir de los resultados de las pruebas; limitaciones y medidas de supervisión humana redactadas por personas | En parte |
| 4. Adecuación de las métricas de rendimiento | Métricas de los pipelines de evaluación; el argumento de que son adecuadas lo redactan personas | Poco |
| 5. Sistema de gestión de riesgos (artículo 9) | Registro de riesgos como archivo versionado; el análisis de riesgos lo hacen personas | Poco |
| 6. Cambios pertinentes a lo largo del ciclo de vida | El historial de Git y el registro de cambios dan la lista en bruto; el proveedor selecciona los cambios pertinentes | En parte |
| 7. Normas aplicadas | Una lista mantenida en el repositorio | Poco |
| 8. Copia de la declaración UE de conformidad | La declaración firmada, almacenada junto con la versión publicada | Ninguna |
| 9. Sistema de vigilancia poscomercialización (artículo 72) | El plan como documento versionado; los datos de seguimiento proceden de la operación | Poco |
Ejemplo de estructura: archivos de documentación junto al código
Esta estructura es un ejemplo, no una estructura obligatoria.
your-ai-system/
├── src/
├── docs/
│ └── compliance/
│ ├── annex-iv/
│ │ ├── 01-general-description.md
│ │ ├── 02-development-process.md
│ │ └── ...
│ ├── risk-register.yaml
│ └── oversight.md
├── tests/
│ └── docs/
└── .github/
└── workflows/
└── docs-check.ymlUn pipeline puede comprobar los documentos en cada pull request
Escanear: analizar el código
Un paso de análisis puede usar una herramienta que detecte en el código los patrones habituales de los marcos de ML. Los envoltorios personalizados y el código ofuscado pueden pasar desapercibidos.
Generar: actualizar los borradores
El pipeline reconstruye las secciones generadas a partir de los datos actuales, de modo que el diff muestra qué ha cambiado en los documentos.
Validar: comprobar que esté completo
Las reglas comprueban que existan las secciones requeridas y que contengan el contenido exigido. Comprobar el contenido no es comprobar que sea verdad: las personas revisan la exactitud.
Informar: mostrar el resultado en el pull request
El pull request muestra qué comprobaciones se han superado y cuáles han fallado, de modo que quien revisa ve el efecto sobre la documentación antes de fusionar el cambio.
El texto plano permite revisar línea a línea, y la protección de ramas resguarda el historial
Las pull requests muestran las líneas cambiadas
Proteger el historial
Lectura relacionada
Fuentes y referencias
- Regulation (EU) 2024/1689 (EU AI Act) — artículos 2, 3, 11, 16, 43 y 99 y anexos I, III y IV (anexo IV: nueve puntos de documentación técnica).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — fechas de aplicación (artículo 113) y cambios en los artículos 2, apartado 2, 3, 11, apartado 1, 99 y 111, apartado 2, y el nuevo artículo 60a.
- GitHub Docs — About protected branches — las reglas de protección de ramas determinan si los colaboradores pueden hacer un force push en una rama.
- Pro Git — Viewing the Commit History — el historial de commits muestra cada commit con su autor, fecha y mensaje; con la opción de parche muestra el diff.
Preguntas frecuentes
¿Qué es la documentación como código para la documentación del Reglamento de IA?
La documentación como código mantiene la documentación técnica bajo control de versiones, la modifica mediante pull requests y genera partes de ella en un pipeline. El objetivo es que la documentación técnica coincida con el sistema tal como se publica.
¿Por qué se desfasan los documentos que están fuera del repositorio?
Los archivos de Word y los PDF están separados del código, así que un cambio en el código no los actualiza. Alguien debe actualizarlos, porque el artículo 11, apartado 1, exige mantener actualizada la documentación técnica.
¿Cumple la documentación como código el anexo IV?
Ninguna práctica cumple por sí sola el anexo IV. El anexo IV fija el contenido en nueve puntos. La documentación como código ayuda a mantener ese contenido actualizado y trazable. El proveedor debe garantizar que el sistema cumple los requisitos del capítulo III, sección 2, entre ellos el artículo 11 (artículo 16, letra a)).
¿Qué herramientas se usan para la documentación como código?
Puede combinar Git, archivos Markdown o YAML y un pipeline de CI para las comprobaciones y la generación. Un escáner o generador puede producir las secciones derivadas del código.
¿Con qué frecuencia debe actualizarse la documentación técnica de IA?
El artículo 11, apartado 1, exige elaborar la documentación técnica antes de que el sistema se introduzca en el mercado o se ponga en servicio, y mantenerla actualizada. El artículo 11, apartado 1, no fija un intervalo concreto. Nuestra sugerencia es revisarla con cada versión y tras cualquier cambio en el modelo, en los datos de entrenamiento o en la finalidad prevista. Una modificación sustancial exige una nueva evaluación de la conformidad (artículo 43, apartado 4). Una modificación sustancial es un cambio posterior a la introducción del sistema en el mercado o a su puesta en servicio. La primera evaluación de la conformidad no lo preveía ni lo planificaba. Afecta al cumplimiento de los requisitos para los sistemas de IA de alto riesgo del capítulo III, sección 2, o cambia la finalidad prevista (artículo 3, punto 23). Una evaluación de la conformidad es el proceso que demuestra si se cumplen esos requisitos (artículo 3, punto 20).
Scanara prepara pruebas a partir de sus repositorios
Scanara lee sus repositorios de GitHub conectados y ejecuta análisis basados en reglas de patrones habituales de IA y aprendizaje automático. Puede pasar por alto código no estándar. Por separado, genera borradores de documentación a partir de plantillas y de sus respuestas en las evaluaciones, como pruebas para su trabajo de cumplimiento. Usted decide la clasificación.