Documentação como código: documentação técnica sincronizada por versão
Como as práticas de documentação como código ajudam a manter a documentação técnica da Lei de IA em linha com cada alteração do código.
Principais Conclusões
- 1.Os fornecedores de sistemas de IA de risco elevado têm de manter atualizada a documentação técnica (artigo 11.º, n.º 1).
- 2.A documentação como código mantém a documentação técnica em controlo de versões, junto ao código.
- 3.Partes podem ser geradas a partir do código e de dados do pipeline. As decisões que exigem juízo precisam de pessoas.
- 4.O controlo de versões mostra o que mudou e quando, não que o conteúdo esteja correto.
A obrigação aplica-se aos fornecedores de sistemas de IA de risco elevado. Aplica-se a quem os coloca no mercado da UE ou em serviço, nos termos do artigo 2.º, n.º 1, alínea a). O anexo IV enumera o que a documentação tem de conter. O anexo III é a lista de utilizações de risco elevado do regulamento, como o recrutamento. O anexo I abrange a IA em produtos sujeitos à legislação de segurança da UE. A secção A do anexo I enumera legislação de produtos, como a dos brinquedos e dos dispositivos médicos. A secção B enumera outra legislação de produtos. Para os sistemas do anexo III, a obrigação aplica-se a partir de 2 de dezembro de 2027. Para os sistemas da secção A do anexo I, aplica-se a partir de 2 de agosto de 2028 (Regulamento (UE) 2026/1744). Os sistemas colocados no mercado ou em serviço antes dessas datas regem-se pelo artigo 111.º, n.º 2, na redação do Regulamento (UE) 2026/1744. Salvo os sistemas do artigo 111.º, n.º 1, só ficam abrangidos se, a partir da data aplicável, sofrerem alterações significativas na sua conceção. Para os sistemas destinados a autoridades públicas, o artigo 111.º, n.º 2, exige as medidas necessárias ao cumprimento até 2 de agosto de 2030.
Para os sistemas de risco elevado ligados a produtos da secção B do anexo I, o artigo 2.º, n.º 2, limita as disposições aplicáveis. Aplicam-se apenas o artigo 6.º, n.º 1 (regras de classificação), e os artigos 102.º a 112.º (disposições finais). Aplica-se também o artigo 60a (testes em condições reais fora dos ambientes de teste). Os artigos 57.º a 59.º tratam dos ambientes de teste da regulamentação da IA. Aplicam-se apenas na medida em que essa legislação integre os requisitos do regulamento para a IA de risco elevado. O artigo 11.º não consta dessa lista.
As obrigações do fornecedor constam do artigo 16.º. O incumprimento pode custar até 15 milhões de EUR ou, para uma empresa, 3 % do volume de negócios anual mundial (artigo 99.º, n.º 4). Aplica-se o montante mais elevado. Para as microempresas e as pequenas e médias empresas (PME, artigo 3.º, ponto 14a), aplica-se o montante mais baixo (artigo 99.º, n.º 6).
Com a documentação como código, as alterações são revistas em pull requests e cada versão fica associada a uma release. Próximo passo: verifique, com o quadro abaixo, quais dos nove pontos do anexo IV pode gerar a partir do seu repositório.
Porque se desviam os documentos fora do repositório
Os documentos em ficheiros Word, PDF ou wikis estão separados do código que descrevem.
Um documento pode descrever uma versão antiga
A atualização é trabalho manual
O que significa a documentação como código na prática
A documentação como código aplica práticas de engenharia de software à documentação técnica:
Controlo de versões
A documentação técnica fica no mesmo repositório Git que o código. Cada alteração é um commit com autor, data e diff, para que possa associar uma versão do documento a uma versão do código.
Geração sempre que possível
Algumas secções podem ser geradas a partir da base de código, como mostra a tabela abaixo. As secções que exigem juízo são escritas por pessoas.
Verificações no pipeline
A sua equipa pode escrever uma regra de pipeline que reprova um pull request quando o modelo muda mas a secção correspondente do documento não. O regulamento não a exige.
Pacotes de release
Cada release agrupa os documentos com a versão do software, para que possa produzir a documentação que correspondia a uma dada release.
A geração ajuda mais em alguns pontos do anexo IV do que noutros
A geração ajuda um pouco em 4 dos 9 pontos do anexo IV, pouco em 4 e nada em 1. As duas colunas da direita são a nossa avaliação, não a do regulamento.
As PME e as pequenas empresas de média capitalização (SMC, artigo 3.º, ponto 14b) podem apresentar os elementos do anexo IV de forma simplificada. Isto decorre do artigo 11.º, n.º 1, na redação do Regulamento (UE) 2026/1744. Quem o fizer tem de usar o formulário simplificado que a Comissão deve estabelecer. O montante de coima mais baixo aplica-se também às SMC (artigo 99.º, n.º 6a).
| Ponto do anexo IV | Abordagem possível | A geração ajuda |
|---|---|---|
| 1. Descrição geral do sistema de IA | Nomes e versões do manifesto, do README e dos metadados da release | Em parte |
| 2. Elementos do sistema e do seu processo de desenvolvimento | Descrições da arquitetura e do pipeline a partir do código; a justificação da conceção é escrita por pessoas | Em parte |
| 3. Monitorização, funcionamento e controlo | Valores de exatidão a partir dos resultados dos testes; limitações e medidas de supervisão humana escritas por pessoas | Em parte |
| 4. Adequação das métricas de desempenho | Métricas dos pipelines de avaliação; o argumento de que são adequadas é escrito por pessoas | Pouco |
| 5. Sistema de gestão de riscos (artigo 9.º) | Registo de riscos como ficheiro versionado; a análise de riscos é feita por pessoas | Pouco |
| 6. Alterações relevantes ao longo do ciclo de vida | O histórico do Git e o registo de alterações dão a lista em bruto; o fornecedor seleciona as alterações relevantes | Em parte |
| 7. Normas aplicadas | Uma lista mantida no repositório | Pouco |
| 8. Cópia da declaração UE de conformidade | A declaração assinada, guardada com a release | Nenhuma |
| 9. Sistema de acompanhamento pós-comercialização (artigo 72.º) | O plano como documento versionado; os dados de acompanhamento vêm das operações | Pouco |
Exemplo de estrutura: ficheiros de documentação junto ao código
Esta estrutura é um exemplo, não uma estrutura obrigatória.
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.ymlUm pipeline pode verificar os documentos em cada pull request
Análise: analisar a base de código
Um passo de análise pode usar uma ferramenta que deteta no código os padrões de frameworks de ML habituais. Wrappers personalizados e código ofuscado podem passar despercebidos.
Gerar: atualizar os rascunhos
O pipeline reconstrói as secções geradas a partir dos dados atuais, pelo que o diff mostra o que mudou nos documentos.
Validar: verificar a completude
As regras verificam se as secções exigidas existem e contêm o conteúdo exigido. Uma verificação de conteúdo não é uma verificação de veracidade: as pessoas revêem a exatidão.
Reportar: mostrar o resultado no pull request
O pull request mostra que verificações passaram ou falharam, para que o revisor veja o impacto na documentação antes de a alteração ser integrada.
O texto simples permite rever linha a linha, e a proteção do ramo resguarda o histórico
As pull requests mostram as linhas alteradas
Proteger o histórico
Leitura Relacionada
Fontes e Referências
- Regulation (EU) 2024/1689 (EU AI Act) — artigos 2.º, 3.º, 11.º, 16.º, 43.º e 99.º e anexos I, III e IV (anexo IV: nove pontos da documentação técnica).
- Regulation (EU) 2026/1744 — Digital Omnibus on AI — datas de aplicação (artigo 113.º) e alterações aos artigos 2.º, n.º 2, 3.º, 11.º, n.º 1, 99.º e 111.º, n.º 2, e ao novo artigo 60a.
- GitHub Docs — About protected branches — as regras de proteção de ramos definem se os colaboradores podem fazer um force push num ramo.
- Pro Git — Viewing the Commit History — o histórico de commits lista cada commit com autor, data e mensagem; com a opção de patch mostra o diff.
Perguntas frequentes
O que é a documentação como código para a documentação da Lei de IA?
A documentação como código mantém a documentação técnica em controlo de versões, altera-a através de pull requests e gera partes dela num pipeline. O objetivo é que a documentação técnica corresponda ao sistema tal como foi publicado.
Porque se desviam os documentos fora do repositório?
Os ficheiros Word e PDF estão separados do código, pelo que uma alteração ao código não os atualiza. Alguém tem de os atualizar, porque o artigo 11.º, n.º 1, exige que a documentação técnica seja mantida atualizada.
A documentação como código satisfaz o anexo IV?
Nenhuma prática satisfaz o anexo IV por si só. O anexo IV fixa o conteúdo em nove pontos. A documentação como código ajuda a manter esse conteúdo atual e rastreável. O fornecedor tem de assegurar que o sistema cumpre os requisitos do capítulo III, secção 2, entre os quais o artigo 11.º (artigo 16.º, alínea a)).
Que ferramentas se usam para a documentação como código?
Pode combinar o Git, ficheiros Markdown ou YAML e um pipeline de CI para verificações e geração. Um scanner ou gerador pode produzir as secções que se podem derivar do código.
Com que frequência se deve atualizar a documentação técnica de IA?
O artigo 11.º, n.º 1, exige que a documentação técnica seja elaborada antes de o sistema ser colocado no mercado ou colocado em serviço, e mantida atualizada. O artigo 11.º, n.º 1, não fixa um intervalo. Sugerimos revê-la a cada release e após qualquer alteração ao modelo, aos dados de treino ou à finalidade prevista. Uma modificação substancial exige uma nova avaliação da conformidade (artigo 43.º, n.º 4). Uma modificação substancial é uma alteração posterior à colocação no mercado ou em serviço que a primeira avaliação da conformidade não previa nem planeava. Afeta o cumprimento dos requisitos para os sistemas de IA de risco elevado do capítulo III, secção 2, ou altera a finalidade prevista (artigo 3.º, ponto 23). Uma avaliação da conformidade é o processo que demonstra se esses requisitos são cumpridos (artigo 3.º, ponto 20).
O Scanara prepara evidências a partir dos seus repositórios
O Scanara lê os seus repositórios GitHub ligados e executa análises baseadas em regras para padrões comuns de IA e de aprendizagem automática. Pode não detetar código fora do padrão. Em separado, gera rascunhos de documentação a partir de modelos e das suas respostas nas avaliações, como evidências para o seu trabalho de conformidade. A classificação é decidida por si.