Documentação de artefatos: os documentos que tornam o código gerado por IA passível de revisão

Objetivo

Agentes de IA escrevem código rapidamente, mas não deixam nenhum registro duradouro da intenção — o que o sistema deve fazer, quem tem permissão para fazer o quê, onde estão armazenados os segredos, quais regras são efetivamente verificadas. Sem esse registro, nenhum ser humano (nem nenhum agente de auditoria) pode determinar se o código está seguro para ser liberado. Esta habilidade define o pequeno conjunto de documentos que restaura a revisabilidade.

Esses documentos ficam na pasta /documentation/ e são escritos para dois leitores: um revisor humano e o próximo agente de codificação de IA. Eles representam a parte do “estado pretendido” de toda auditoria posterior — uma revisão de segurança ou desempenho só é válida na medida em que pode comparar o código com a intenção original.

Como o conjunto está organizado

O conjunto não é uma lista fixa — é um pequeno núcleo, além de documentos condicionais que você adiciona apenas quando a capacidade existe.

• Documentos essenciais — todo aplicativo passível de revisão possui esses elementos, portanto, sempre os produza.
• Documentos condicionais — inclua um apenas se o aplicativo realmente tiver essa capacidade. Caso contrário, escreva uma única linha no arquivo architecture.md (“Sem tarefas agendadas — sem cron.md.”) em vez de criar um documento vazio. A revisabilidade vem de um mapa honesto, e “não fazemos X” faz parte desse mapa.
• A maioria dos documentos é gerada por engenharia reversa a partir do código pelo /document-app. A única exceção é o tests.md, que é derivado dos outros documentos pelo /derive-tests — trata-se do mapa de verificação, não de uma descrição de um subsistema.

Seja brutalmente honesto sobre o estado atual, sem cair na paranóia. A tarefa é criar um mapa preciso, não um atestado de boa saúde. Cada documento é curto, repleto de tabelas e marcadores, e ignora a teoria genérica.

Documentos principais

Cada entrada: arquivo · objetivo em uma linha · o que deve abordar · como um revisor o utiliza.

1. architecture.md — o que é o sistema e como ele se integra.

   • Deve abordar: visão geral do produto + premissas-chave; pilha de tecnologias; como a autenticação/sessões/reivindicações fluem de ponta a ponta; os limites de confiança (por exemplo, função do serviço vs. cliente); uma breve lista de riscos conhecidos/suposições (cada item respaldado pela referência ao local onde aparece no código, não uma lista de verificação genérica); um índice de “Documentos Relacionados” com todos os outros documentos produzidos.
   • Uso pelo revisor: o documento raiz — todo o restante é referenciado a partir daqui.

2. flows.md — as jornadas em que as permissões e os efeitos colaterais são efetivamente exercidos.

   • É preciso capturar: cada fluxo de carga como ator + pré-condição + resultado de sucesso; a sequência passo a passo passando por IU → servidor → dados → tarefas → provedores → agentes; a verificação de autorização em cada etapa protegida (qual reivindicação/função/escopo, em qual recurso e o caso esperado de recusa ); as travessias de limites de confiança (navegador → servidor, servidor → provedor, tarefa → aplicativo, agente → ferramenta, webhook → aplicativo); as mudanças de estado e os efeitos colaterais que cada etapa causa (gravações, e-mails enfileirados, tarefas acionadas, chamadas de saída).
   • Uso pelo revisor: a visão em tempo de execução que uma matriz estática de permissões.md não consegue mostrar — onde e em que ordem a autorização é aplicada, e onde ela pode ser ignorada.
   • Regra anti-PRD: um fluxo que não envolva permissões, integridade de dados, efeitos colaterais externos, dinheiro, privacidade ou segurança operacional não tem lugar aqui. Este é um mapa de segurança/operações, não uma especificação de recursos.

3. permissions.md — quem tem permissão para fazer o quê.

   • Deve incluir: funções/reivindicações; de onde o escopo é derivado (token x banco de dados); uma matriz recurso × operação × função; quais tabelas possuem segurança no nível da linha e quais dependem de verificações impostas por código.
   • Uso pelo revisor: a linha de base com a qual uma auditoria de controle de acesso compara o código. O arquivo flows.md mostra isso em ação; esta é a referência estática.

4. variables.md — configuração e segredos, mapeados ao risco.

   • É preciso incluir: uma tabela com Nome · usado por · escopo (servidor/cliente) · fonte · rotação · risco; confirmação explícita de que nenhum segredo está empacotado no lado do cliente; uma lista de verificação pré-entrada em operação.
   • Uso pelo revisor: a superfície de vazamento de segredos/PII e o plano de rotação durante a resposta a incidentes.

5. tests.md — o mapa de verificação: quais regras documentadas são efetivamente verificadas, quais são apenas propostas e quais não são verificadas por nada.

   • Deve incluir, em três seções claramente separadas para que o mapa não apresente um resultado falsamente positivo:
     • Cobertura existente — testes que estão no repositório atualmente, cada um vinculado à regra à qual se refere (para que o mapa reflita a realidade, não uma lista de desejos).
     • Testes propostos — casos recomendados ainda não escritos, marcados por tipo de teste (unidade/integração automatizada · em produção supervisionada · revisão manual).
     • Lacunas — regras documentadas sem qualquer verificação, classificadas de acordo com o que sua violação expõe.
   • Cada linha contém: caso de uso → regra → comportamento esperado (incluindo o caso de negação/negativo) → fonte de evidência (documentação + código) → status (existente / proposto / nenhum). Também indica quais verificações são exigidas pela CI e bloqueiam as fusões para o branch principal.
   • Uso pelo revisor: a forma operacional de “documentado == implementado” — mostra se cada regra mencionada nos outros documentos está de fato validada por um teste atualmente, se é apenas proposta ou se não foi verificada.
   • Produzido por /derive-tests (não por /document-app), pois é derivado dos outros documentos e do conjunto de testes existente, em vez de ser extraído de um subsistema.

Documentos condicionais (incluir apenas quando o recurso existir)

6. emails.md — todas as notificações que o sistema envia. Incluir apenas se o aplicativo enviar e-mails transacionais ou automatizados.

   • Deve capturar: o caminho fila → processador → provedor; modelos e as variáveis que eles aceitam; comportamento de repetição/recuo; onde procurar quando um envio falha.
   • Uso pelo revisor: identificar entradas não validadas nos modelos e limites de exposição de informações de identificação pessoal (PII).

7. cron.md — todas as tarefas agendadas e como operá-las com segurança. Incluir apenas se houver tarefas agendadas ou em segundo plano.

   • Deve incluir: uma tabela de inventário (tarefa → programação → função → segredos → limites → nova tentativa); como cada tarefa permanece idempotente; como as chamadas internas se autenticam; onde verificar as últimas execuções.
   • Uso pelo revisor: identificar gatilhos falsificáveis e tarefas em segundo plano sem limites.

8. seo.md — como um aplicativo de página única lida com SEO e visualizações em redes sociais. Inclua apenas se houver rotas públicas/indexáveis ou voltadas para bots.

   • Deve incluir: a abordagem de pré-visualização (meta estática / pré-renderização / HTML de borda); uma tabela rota → necessidades de SEO → apenas dados públicos; como os metadados dinâmicos são sanitizados; roteamento para bots versus humanos.
   • Uso pelo revisor: detectar violações da regra “somente dados públicos” e injeção de metadados em rotas para bots.

9. automation.md — agentes incorporados e outros caminhos de automação. Inclua apenas se o aplicativo incorporar agentes de IA, fluxos de trabalho de LLM, chamadas de ferramentas, webhooks ou automação externa.

   • É necessário registrar, por automação/agente: gatilho + responsável + se é executado automaticamente ou somente após aprovação; as entradas que ele pode ler e as ferramentas/APIs exatas que pode chamar (a superfície da ferramenta é, por si só, uma barreira de proteção rígida); onde reside o direcionamento (o prompt) em comparação com as barreiras de proteção rígidas não relacionadas ao prompt; o contrato de saída de volta para o aplicativo (esquema, validação, tratamento de falhas); efeitos colaterais de responsabilidade do aplicativo versus sugestões de responsabilidade do agente; e os controles — etapas de aprovação, registro de auditoria/linha do tempo, limites de taxa, novas tentativas, interruptor de emergência.
   • Uso pelo revisor: torna visíveis os caminhos ocultos de automação e traça a linha divisória entre o que um agente propõe e o que o aplicativo impõe — a superfície de maior risco em aplicativos modernos desenvolvidos com IA.

Notas

• Cada documento produzido adiciona uma referência a si mesmo no arquivo architecture.md, na seção “Documentos relacionados”, para que o conjunto permaneça localizável.
• Ignore qualquer documento condicional que não se aplique e indique isso em uma única linha, em vez de inventar conteúdo.
• Mantenha exemplos e modelos prontos fora desses documentos — eles descrevem este sistema, não o método geral.
• O arquivo de contexto operacional do agente (CLAUDE.md / AGENTS.md) é um artefato diferente — instruções derivadas desses documentos, não da documentação do sistema. Ele é gerado na etapa de transferência pelo /ship-check, não aqui.
• O `tests.md` é gerado pelo comando `/derive-tests`; os demais são gerados pelo comando ` /document-app`.
• Não inclua uma linha de “data de atualização”; o histórico do arquivo é a fonte de verdade.