System Design com IA: um guia prático para documentar decisões

Peça a uma ferramenta de IA para “projetar um sistema de pagamentos” e ela pode produzir um documento convincente em minutos. O trabalho mais difícil é estabelecer se os componentes propostos existem, se os requisitos são reais e se o tratamento de falhas corresponde ao contrato da API.

System Design é o planejamento de como as partes de um sistema trabalham juntas. Um bom documento ajuda a equipe a tomar e implementar essas decisões. Ele explica o problema, os limites, as alternativas, o comportamento em caso de falha e as evidências ainda necessárias. A IA pode acelerar pesquisa, elaboração e verificações de consistência; a equipe de engenharia continua responsável pelos requisitos e pelas decisões arquiteturais.

Este guia transforma as práticas de Context Engineering, Harness Engineering e Loop Engineering em um fluxo de documentação. O exemplo contínuo é uma funcionalidade hipotética de exportação de pedidos. Os números e as restrições são ilustrativos, não medições de produção.

1. Comece com um resumo inicial que mostre as dúvidas

Neste exemplo, um job é uma exportação executada em segundo plano; um worker é o processo que a executa. Antes de pedir uma arquitetura, escreva um resumo inicial curto em docs/design/order-export/brief.md:

# Exportação de pedidos

## Objetivo
Permitir que um lojista autenticado exporte os próprios pedidos para um arquivo CSV.

## Requisitos
- R1: somente usuários com permissão de exportação podem solicitar ou baixar uma exportação.
- R2: toda consulta e todo download devem respeitar o isolamento entre comerciantes.
- R3: repetir um envio não pode criar um segundo job dentro de 24 horas.
- R4: os jobs sobrevivem a reinicializações do worker e chegam a um estado terminal visível.
- R5: o acesso ao download expira 24 horas após a conclusão.

## Metas propostas — exigem confirmação das partes interessadas
- Até 100.000 pedidos por exportação.
- Até 20 novos jobs por minuto no pico.
- 95% dos jobs aceitos são concluídos em até 5 minutos nessa carga.

## Restrições existentes
- Reutilizar a autenticação e a plataforma de implantação da aplicação.
- Preferir a infraestrutura existente quando ela atender aos requisitos.

## Fora do escopo
Exportações agendadas, novos formatos de arquivo e relatórios entre comerciantes.

## Perguntas em aberto
- Quais campos podem ser exportados e quais precisam ser ocultados?
- A exportação precisa refletir uma visão consistente dos dados em um instante específico?
- Por quanto tempo os metadados de jobs e os arquivos armazenados devem ser mantidos?

Atribua identificadores estáveis aos requisitos para relacioná-los a decisões e verificações. Mantenha metas separadas de medições observadas. Uma estimativa de capacidade baseada em tamanhos de linha presumidos deve mostrar essas suposições e explicar como medi-las.

Resolva as perguntas que mudam o design antes de considerar o documento pronto para implementação. Por exemplo, a consistência dessa visão dos dados pode alterar a estratégia de consulta, a duração da transação e a carga do banco de dados. A IA não deve escolher silenciosamente uma política de negócio.

2. Escolha o modo da ferramenta e forneça evidências

Uma interface de chat pode funcionar bem para um documento de escopo limitado: anexe o resumo inicial, trechos do código-fonte sem dados sensíveis, contratos existentes e um modelo de documento. Execute localmente as verificações geradas e devolva a saída real. Um assistente conectado ao repositório pode inspecionar arquivos, editar o documento e executar comandos quando o ambiente permitir essas ações.

Use uma ferramenta que a equipe consiga operar com acesso aprovado aos dados. Confira o que ela realmente consegue ler e executar; o modelo não pode verificar um repositório que nunca recebeu. Evite enviar credenciais ou registros de clientes desnecessários como contexto de design.

Comece com um prompt para coletar evidências:

Leia docs/design/order-export/brief.md e inspecione o código relevante,
os contratos de API, as migrações, a configuração de implantação e a documentação operacional.
Ainda não escreva a arquitetura proposta.

Crie evidence.md com:
- Fatos confirmados, cada um vinculado a um caminho e símbolo ou seção da fonte.
- A revisão do repositório inspecionada.
- Fontes conflitantes ou desatualizadas.
- Suposições e perguntas sem resposta, identificadas explicitamente.
- Componentes existentes que poderíamos reutilizar e evidências de suas capacidades.

Diferencie a implementação atual do comportamento desejado.
Não infira garantias de fila, serviço ou provedor pelo nome.
Priorize perguntas cujas respostas mudariam o design.

Em um sistema existente, prefira evidências do código e da implantação a uma descrição plausível. Em um sistema novo, registre decisões das partes interessadas e contratos de dependências externas. Se as fontes divergirem, preserve o conflito até que alguém o resolva.

3. Forneça ao agente instruções concisas do repositório

O formato AGENTS.md oferece um local para instruções do projeto, inclusive comandos e convenções, e permite arquivos aninhados com escopo específico. Confira como sua ferramenta descobre e combina essas instruções. Não presuma que llms.txt, um diretório oculto ou uma variável de ambiente personalizada faça parte de uma hierarquia universal de carregamento.

Mantenha orientações estáveis em AGENTS.md e os requisitos da funcionalidade atual no resumo inicial. Um exemplo pequeno para uma área de trabalho de design:

# Fluxo de documentação de design

- Leia o resumo inicial relevante antes de mudar um design.
- Cite evidências do repositório para afirmações sobre o comportamento atual.
- Identifique explicitamente propostas, suposições e decisões pendentes.
- Preserve os IDs dos requisitos no design e na lista de revisão.
- Reutilize a infraestrutura existente, salvo quando um requisito justificar mudança.
- Explique tratamento de falhas, propriedade de dados e alternativas.
- Execute as verificações documentadas e informe resultados e limites reais.
- Não aprove um design com base apenas em resultados de lint.

## Referências
- Vocabulário de domínio: docs/domain.md
- Requisitos de segurança: docs/security.md
- Modelo de documento de design: docs/design-template.md
- Comandos de validação: tools/README.md

Crie ou corrija esses caminhos de referência para o seu repositório. Um índice curto só é útil se apontar para informações mantidas. Não existe uma quantidade mágica de linhas que garanta bom raciocínio; remova duplicações e coloque procedimentos detalhados onde possam ser carregados quando necessário.

Instruções orientam comportamento. Permissões de acesso a arquivos, restrições de ferramentas e controles de CI impõem limites. Uma frase em Markdown não cria um sandbox.

4. Rascunhe decisões antes de ampliar o documento

Comece com um conjunto pequeno de arquivos:

AGENTS.md
.spectral.yaml
package.json
package-lock.json
docs/design/order-export/
  brief.md
  evidence.md
  design.md
  api.yaml
  diagrams/
    containers.mmd
    retry-sequence.mmd
  adr/
    0001-background-processing.md
  review.md

Adicione artefatos apenas quando ajudarem a responder uma pergunta de design. Uma mudança interna pequena pode precisar de apenas um documento e um diagrama. Uma mudança em uma API pública pode exigir um contrato preciso e um plano de compatibilidade.

Use este prompt para comparar abordagens primeiro:

Usando brief.md e evidence.md, compare a exportação síncrona com um design
de jobs em background que reutilize infraestrutura existente confirmada.

Para cada opção, explique latência, carga do banco, recuperação de falhas,
esforço operacional e custo de implementação. Mostre contas de capacidade
com unidades e suposições. Identifique o que exige protótipo ou medição.

Recomende uma opção de forma condicional aos requisitos declarados.
Registre a recomendação em um ADR proposto com contexto, alternativas,
consequências e condições que levariam a revisá-lo.
Não marque como aprovadas escolhas ainda não resolvidas pelas partes interessadas.

Para uma orientação mais aprofundada sobre decisões arquiteturais e análise de risco, consulte os capítulos 21, “Architectural Decisions”, e 22, “Analyzing Architecture Risk”, de Mark Richards e Neal Ford em Fundamentals of Software Architecture.

Transforme metas de qualidade em cenários de revisão

Trate atributos de qualidade e concessões como direcionadores do design. Substitua pedidos genéricos como “um sistema escalável e confiável” por cenários que nomeiem uma condição, uma resposta observável e uma forma de verificá-la:

Característica	Pergunta de design ilustrativa	Evidência proposta
Desempenho	Na combinação de jobs de pico acordada, 95% das exportações aceitas terminam em até cinco minutos, incluindo o tempo na fila?	Teste de carga representativo com percentis de conclusão e idade da fila
Confiabilidade	Se um worker morrer durante o upload do arquivo, o job chega a um estado terminal ou se recupera sem expor um arquivo parcial?	Teste de injeção de falhas e trace de transição de estado
Segurança	Um usuário de outro comerciante consegue inferir ou baixar uma exportação usando o ID do job?	Testes de autorização entre comerciantes para status e download
Operabilidade	A equipe de plantão consegue distinguir se um backlog vem de leituras do banco, workers ou armazenamento de arquivos?	Revisão de dashboard e alertas com falha preparada

São cenários de aceitação propostos; a equipe precisa confirmar as metas e executar verificações contra uma implementação ou protótipo. Peça à IA para ordenar as características mais importantes, descrever o que cada design candidato melhora ou piora e registrar a concessão no ADR. Um processo em segundo plano pode evitar uma requisição HTTP de longa duração e, ao mesmo tempo, adicionar atraso na fila, estado durável e trabalho de recuperação. “Mais escalável” é vago demais para justificar esse custo.

Mapeie termos de domínio e propriedade dos dados

Estabeleça um vocabulário de domínio compartilhado e limites explícitos. Para este exemplo, pergunte a uma pessoa especialista no domínio o que significa um pedido, se pedidos cancelados entram nas exportações e se “conclusão” significa que um arquivo foi criado ou que a pessoa comerciante consegue baixá-lo. Registre as definições acordadas no briefing e use-as de forma consistente na API, nos estados dos jobs, nos diagramas e nos testes.

Desenhe os limites do domínio de pedidos existente antes de criar um “serviço de exportação”. O sistema de pedidos pode ser responsável pelos fatos dos pedidos, enquanto o processamento de exportação é responsável pelo estado dos jobs e pelos arquivos temporários. São limites candidatos, não uma obrigação de dividir implantações ou bancos de dados. Se o worker de exportação ler diretamente uma tabela de pedidos, registre se esse acesso respeita as regras do domínio de pedidos e quais mudanças de schema poderiam quebrá-lo. Uma API de consulta controlada ou um read model específico podem ser adequados quando o acesso direto cria acoplamento inaceitável, mas cada opção adiciona latência e trabalho operacional.

Explicite as concessões sobre propriedade de dados e transações distribuídas. Para a proposta de exportação de pedidos, registre quem é responsável pelos dados dos pedidos, pelo estado do job e pelos metadados do arquivo; depois, rastreie o que acontece quando o registro do job é confirmado no banco, mas a publicação na fila falha. Prefira um caminho recuperável que a plataforma existente consiga oferecer. Se a proposta introduzir um broker, outbox ou serviço separado, explique por que um processo de trabalho mais simples ou um executor de tarefas apoiado no banco não atende aos requisitos. Registre no ADR os componentes extras e a falha que resolvem.

Revise a linguagem de domínio e os limites em brief.md e design.md.
Liste termos cujo significado difere entre produto, API e armazenamento.
Para cada item de dados, nomeie quem é responsável pela fonte autoritativa e quem pode ler.
Rastreie falhas entre cada gravação durável e efeito colateral downstream.
Compare o design mais simples com infraestrutura existente à divisão proposta,
incluindo acoplamento, consistência, recuperação e operação.
Sinalize questões pendentes de propriedade e política de negócio para revisão humana.

Depois, amplie a proposta selecionada para incluir estas seções:

Seção	O que o revisor deve aprender
Status, pessoa responsável e escopo	Quem é responsável pela proposta e o que ela altera
Requisitos e evidências	Quais fatos, metas e incógnitas a orientam
Contexto e limites	Quem usa o sistema e de que ele depende
Design proposto	Responsabilidades, propriedade dos dados e interações
Contratos e modelo de dados	Requisições, respostas, estados, restrições e evolução
Comportamento em caso de falha	Timeouts, retries, duplicações, sucesso parcial e recuperação
Atributos de qualidade	Premissas de capacidade, latência, segurança, confiabilidade e custo
Operação e entrega	Métricas, alertas, entrada em produção, reversão e migração
Alternativas e decisões	Por que a escolha serve e a que se renuncia
Verificação e perguntas em aberto	Evidências necessárias antes da implementação ou release

Faça uma estimativa de capacidade

Use estimativas aproximadas para expor suposições antes de um design detalhado e peça à IA que mostre as unidades em cada etapa. Suponha, apenas neste exercício, que todos os 20 jobs de pico contenham 100.000 pedidos e cada linha CSV serializada tenha em média 2 KB:

Cálculo	Resultado ilustrativo	O que indica
20 jobs/min × 100.000 linhas/job	2 milhões de linhas/min, ou cerca de 33.000 linhas/s	Carga de chegada no pico se todos os jobs tiverem o tamanho máximo
100.000 linhas/job × 2 KB/linha	Cerca de 200 MB/job	Tamanho aproximado da saída sem compressão
20 jobs/min × 200 MB/job	Cerca de 4 GB/min, ou 67 MB/s	Vazão contínua necessária apenas para acompanhar esse pico hipotético
33.000 linhas/s × 2 KB/linha	Cerca de 67 MB/s	Conferência cruzada do cálculo de saída

São números de planejamento, não medições da capacidade do banco ou do armazenamento. Escape de CSV, compressão, cabeçalhos, amplificação de leitura, arquivos temporários, consultas concorrentes e novas tentativas podem alterar a carga real. A meta de percentil 95 em cinco minutos também não pode ser comprovada com um cálculo de vazão média. Meça uma exportação representativa, uma máxima e exportações concorrentes usando o banco e o armazenamento de arquivos existentes. Registre distribuição do tamanho das linhas, tempo de consulta, taxa de serialização, espera na fila e tempo total de conclusão antes de escolher a concorrência dos processos de trabalho.

Experimente uma pergunta de sensibilidade: se somente um em cada dez jobs chegar a 100.000 linhas, quanto muda a taxa de saída esperada e o sistema ainda aguenta a chegada simultânea de vários jobs máximos? Isso diferencia capacidade típica do pico que o design precisa absorver.

5. Gere contratos e diagramas a partir das mesmas decisões

Use nomes estáveis no texto, nos schemas de API e nos diagramas. O modelo C4 oferece visões de contexto, containers, componentes e código; use os níveis úteis para seu público. Uma visão de container descreve aplicações e armazenamentos de dados, não necessariamente containers Docker. Para outras orientações sobre diagramas, consulte o capítulo 23, “Diagramming Architecture”, de Fundamentals of Software Architecture.

Na exportação de pedidos, primeiro estabeleça os atores, a API, o job store, o worker e o file store necessários à proposta. Marque como propostas as partes que ainda não existem. Uma visão de sequência pode então expor uma falha especialmente importante:

O documento deve combinar o diagrama com uma tabela de responsabilidades e falhas. Isso permite que revisores encontrem rapidamente um caminho de recuperação sem responsável:

Componente proposto	Responsabilidade e estado sob sua propriedade	Comportamento em caso de falha a decidir e testar
Export API	Autorizar requisições; criar jobs e registros de idempotência com escopo no job store	Se a gravação falhar, retornar erro sem afirmar que o job existe; se a resposta se perder após o commit, um retry encontra o mesmo job
Job store	Manter estado durável, propriedade do comerciante, lease ou claim e metadados do resultado	Detectar trabalho abandonado e torná-lo elegível para retry limitado; definir como claims conflitantes são resolvidos
Worker	Ler dados autorizados do comerciante e produzir um arquivo para um job reclamado	Em caso de crash, liberar ou expirar o claim; impedir download de arquivo incompleto; limitar falhas repetidas
File store	Manter a saída concluída até o prazo de retenção	Uma falha de upload deixa o job incompleto; uma falha de exclusão fica visível para limpeza e alerta

Essas linhas descrevem responsabilidades candidatas, não evidências de que esses componentes já existam no repositório. Um design que adicione uma fila também deve dizer se o registro de tarefas ou a fila é a fonte oficial para recuperação. Peça à IA que rastreie falhas antes e depois de cada gravação durável e, em seguida, verifique se uma nova tentativa pode criar arquivos duplicados ou expor saída parcial. O capítulo 11, “Work Queue Systems”, de Brendan Burns em Designing Distributed Systems é um complemento útil para padrões de fila e processos de trabalho.

sequenceDiagram
    accTitle: Retry de envio de exportação após perda da resposta
    accDescr: A API confirma um job e seu registro de idempotência, mas o cliente não recebe a resposta. Um retry com o mesmo comerciante, chave e payload retorna o job existente.
    participant U as Cliente comerciante
    participant A as Export API
    participant D as Job store
    U->>A: POST export com chave de idempotência
    A->>A: Autenticar e autorizar comerciante
    A->>D: Persistir atomicamente job e chave com escopo
    D-->>A: Job confirmado
    Note over U,A: Resposta se perde antes de chegar ao cliente
    U->>A: Repetir com a mesma chave e payload
    A->>A: Autenticar e autorizar comerciante
    A->>D: Buscar chave com escopo do comerciante e hash do payload
    D-->>A: Job existente
    A-->>U: Retornar identificador do job existente

Esta é uma interação proposta, não uma prova de implementação funcional. O design também precisa abordar envios concorrentes, falha de transação, expiração da chave e reutilização da mesma chave com payload diferente. Se houver um broker, explique como um job confirmado fica disponível após um crash entre o commit no banco e a publicação da mensagem.

Gere o contrato da API considerando essas decisões:

Rascunhe api.yaml e atualize design.md em conjunto.
Defina o comportamento do envio, da consulta de status e do download autorizado.
Especifique autenticação, escopo do comerciante, escopo e expiração da chave de
idempotência, comportamento para mesma chave com payload diferente, estados do
job e respostas de erro.

Use os mesmos identificadores e nomes de estado em todos os artefatos.
Documente como jobs duráveis são descobertos e repetidos após falha do worker.
Sinalize decisões ausentes em vez de inventar garantias do provedor.
Mantenha o documento como proposta até que os critérios de revisão sejam atendidos.

Para R5, “a URL assinada expira” não basta. O design precisa impedir que uma nova URL seja emitida depois do prazo de acesso ao job e impedir que uma URL já emitida ultrapasse esse prazo. Exclusão de arquivos e retenção de metadados são políticas distintas que precisam ser resolvidas.

Revise a API do ponto de vista de quem a usa

Um arquivo OpenAPI pode descrever requisições válidas e ainda deixar os clientes sem saber o que fazer depois. O contrato deve evoluir sem surpreender clientes que usam a API, e o design precisa identificar os clientes que usam a API, quem é responsável pela API e como as mudanças são gerenciadas. Aplique estas verificações à API de exportação antes da implementação:

Situação do cliente	Pergunta que o design precisa responder
Envio é aceito, mas a resposta se perde	O cliente consegue repetir com segurança usando a mesma chave e payload com escopo do comerciante, recebendo o ID do job original?
A chave é reutilizada com parâmetros diferentes	Qual resposta de erro estável informa ao cliente que a requisição conflita com o envio original?
Job está na fila, em execução, concluído ou falhou definitivamente	Quais estados, timestamps, links para resultados e detalhes de erro o cliente pode observar? Quais estados são terminais?
Cliente consulta com muita frequência ou o serviço está sobrecarregado	Que rate limit ou orientação de retry é retornada e como o cliente deve responder?
Arquivo está pronto ou o acesso expirou	Como o cliente distingue um resultado pendente, um download expirado e um job que não tem permissão para visualizar?

Especifique esses casos em api.yaml com exemplos representativos de requisições e respostas. Confirme códigos de status, headers e formatos de erro conforme as convenções existentes do repositório, em vez de deixar que a IA os escolha de memória. O cliente deve conseguir implementar um fluxo completo, do envio ao download, usando o contrato e os exemplos, inclusive o tratamento de falhas.

Nomeie os clientes que usam a API e a equipe responsável pela API. Antes de mudar um contrato publicado, compare a especificação candidata à versão anterior e revise mudanças semânticas: remover um campo ou mudar o significado de um estado de job pode quebrar um cliente mesmo quando os dois arquivos passam no lint. Adicionar um campo opcional à resposta costuma ser mais fácil de absorver, mas o comportamento real dos clientes que usam a API ainda importa. Registre como os clientes afetados serão notificados, migrados e finalmente retirados de uma versão antiga quando uma mudança incompatível for necessária.

Quando houver implementação, teste a implementação da API com as interações das quais os clientes reais dependem. Testes de contrato feitos do ponto de vista do cliente ou dados de teste equivalentes de requisição e resposta podem verificar novas tentativas, estado, download e erros no CI. Mantenha também um teste de ponta a ponta pequeno para a jornada completa de exportação. Spectral verifica as regras de descrição configuradas; nem ele nem um teste de contrato aprovado comprovam isolamento de dados e recuperação.

Atue como um cliente comerciante que integra com esta API de exportação.
Leia api.yaml e o design sem inventar comportamentos não documentados.
Percorra envio, perda de resposta e retry, polling, job com falha,
download bem-sucedido e acesso expirado. Para cada etapa, mostre a
requisição, a resposta esperada e a próxima ação do cliente. Liste ambiguidades
com a localização no contrato. Em seguida, compare o contrato proposto com
a última versão publicada e sinalize mudanças que poderiam afetar os clientes conhecidos da API.

6. Automatize verificações estruturais

Use ferramentas locais ao repositório e com versões fixadas para tornar a validação reproduzível. Na área de trabalho de design, instale os pacotes escolhidos uma vez, revise as versões resolvidas e inclua no controle de versão o arquivo de dependências e o arquivo que fixa suas versões:

npm install --save-dev --save-exact @stoplight/spectral-cli @mermaid-js/mermaid-cli

Registre uma versão compatível do Node e as dependências de navegador exigidas pelo Mermaid CLI. Execuções posteriores devem usar npm ci. Esses comandos pertencem ao repositório com os artefatos de design; não são pré-requisitos para escrever Markdown em um chat.

O Spectral exige um ruleset. Crie .spectral.yaml:

extends: ["spectral:oas"]

Execute arquivos explícitos usando as ferramentas locais:

./node_modules/.bin/spectral lint docs/design/order-export/api.yaml \
  --ruleset .spectral.yaml --fail-severity=warn

mkdir -p build/design
./node_modules/.bin/mmdc \
  -i docs/design/order-export/diagrams/containers.mmd \
  -o build/design/containers.svg
./node_modules/.bin/mmdc \
  -i docs/design/order-export/diagrams/retry-sequence.mmd \
  -o build/design/retry-sequence.svg

O Mermaid CLI renderiza definições de diagramas em arquivos como SVG. Mantenha a saída renderizada para inspeção visual: rótulos podem se sobrepor ou ficar ilegíveis mesmo quando a renderização funciona. Confira se todos os diagramas exigidos foram processados.

Use um prompt de correção delimitada após uma falha:

Corrija a falha de validação anexada no artefato indicado.
Preserve os requisitos acordados e explique qualquer mudança no contrato.
Não desabilite regras apenas para fazer a verificação passar.
Execute a mesma verificação novamente e informe seu código de saída
e as descobertas restantes.
Pare após três tentativas de correção sem sucesso e informe o impedimento.

Três tentativas são um orçamento de exemplo. Escolha um valor adequado à tarefa. Preserve a saída original da ferramenta, incluindo arquivo, regra e localização; não invente número de linha nem diagnóstico quando o validador não os fornecer.

7. Revise semântica separadamente de sintaxe

Um resultado de lint comprova apenas o que as regras configuradas verificaram. Uma renderização comprova que o diagrama pôde ser gerado. Nenhum dos dois prova isolamento, recuperação, capacidade ou correção de negócio.

Mantenha uma tabela de rastreabilidade em review.md:

Requisito	Evidência no design	Verificação ainda necessária
R1: Permissão de exportação	Autorização descrita nas três operações	Testes de envio e download com papel negado
R2: Isolamento entre comerciantes	Verificações de propriedade em jobs, consultas e downloads	Testes com IDs e downloads de outros comerciantes
R3: Deduplicação do envio	Chave com escopo e unicidade, comparação do payload e criação atômica	Retries concorrentes e testes de perda de resposta
R4: Processamento durável	Estados do job, lease do worker, limite de retries e caminho de recuperação	Injeção de crash antes e depois da criação do arquivo
R5: Prazo de acesso	Autorização de download e limites de duração da URL	Testes no horário-limite e de URLs emitidas anteriormente

Antes da implementação, esses são testes planejados. Marque-os como executados somente quando houver uma implementação ou protótipo e resultados registrados.

Peça à IA uma rodada separada de crítica:

Revise o briefing, as evidências, o design, a API, o ADR e os diagramas em conjunto.
Encontre contradições, afirmações sem suporte e fluxos de falha ausentes.
Para cada constatação, cite a seção do artefato e o requisito afetado.
Explique um cenário concreto em que o design proposto falhe.
Não reescreva nem aprove a proposta. Retorne achados priorizados
e as evidências ou decisões necessárias para resolvê-los.

Uma nova revisão pode encontrar inconsistências, mas outro modelo também pode repetir os erros do autor. Peça à equipe de engenharia responsável que revise as decisões e envolva as equipes de segurança, operações ou produto quando os requisitos delas forem afetados. Registre explicitamente as concessões aceitas.

Em fluxos repetidos de documentos de design, um avaliador tipado como a primitiva Score do Jev, da TypeSafe pode acrescentar um sinal consistente de qualidade semântica. Inclua o briefing aprovado, os requisitos, a tabela de rastreabilidade, o design, a API, o ADR, o código-fonte dos diagramas ou descrições textuais e os resultados das verificações realmente executadas. Avalie dimensões como clareza, cobertura de requisitos, rastreabilidade de evidências e prontidão operacional separadamente, com níveis concretos como 0–4. Mantenha etapas obrigatórias de lançamento e aprovação da pessoa responsável fora de qualquer nota ponderada; um documento bem apresentado não compensa um requisito pendente nem a falta de verificação. Consulte o padrão de avaliação com modelos de Loop Engineering para ver salvaguardas ao avaliar resultados de tarefas.

Torne a prontidão operacional revisável

O modelo de documento de System Design pede sinais operacionais nomeados, responsáveis, etapas obrigatórias de lançamento e etapas de entrada em produção. Para este exemplo, adicione uma lista compacta a review.md e substitua os exemplos por decisões da equipe:

Item de revisão	Evidência solicitada antes do lançamento	Responsável ou decisão necessária
Meta de conclusão	Teste de carga mostrando percentis de conclusão dos jobs na taxa de chegada e combinação de tamanhos de linha acordadas	Produto confirma a meta; equipe do serviço mede
Saúde da fila	Painel com a exportação mais antiga na fila, jobs por estado, contagem de novas tentativas e falhas terminais; limites de alerta ligados ao impacto para usuários	Equipes do serviço e de plantão acordam os limites
Isolamento e acesso	Testes de IDs de jobs de outros comerciantes, downloads, acesso expirado e redação de logs	Segurança e responsáveis pelo serviço revisam
Recuperação	Testes de crash em torno do commit do job, claim, upload do arquivo e conclusão; procedimento de replay documentado	Equipe do serviço demonstra recuperação
Entrada em produção e reversão	Lançamento para público limitado, condição de parada, etapas de reversão e limpeza de jobs/arquivos criados durante uma falha	Responsável pelo release aprova a sequência

O nome de um alerta não é evidência operacional. Registre seu limite, janela de medição, responsável e ação do roteiro de execução. Gere cenários de falha para inspeção, especialmente retries e falhas parciais, e compare cada mecanismo proposto com os contratos reais do sistema.

8. Mantenha evidências e aprovação separadas

Para documentos ocasionais, uma lista de verificação e o log do CI são suficientes. Se isso se tornar um fluxo repetido, adicione um executor pequeno de validação com identificadores fixos de verificações, argumentos de comando, diretório de trabalho, timeouts e saída retida. Evite executar strings arbitrárias de shell obtidas de arquivos de tarefa gerados.

Acompanhe separadamente a verificação estrutural e a revisão de design. Um registro pode incluir revisão candidata, hashes dos artefatos, versões de ferramentas, resultados das verificações, perguntas pendentes e decisão do revisor. Qualquer mudança no artefato deve invalidar as evidências antigas correspondentes.

Um executor que grava passing em um arquivo JSON que o agente pode editar fornece registro administrativo, não um limite de aprovação imposto. Se uma etapa de controle for importante, imponha-a pelo CI controlado e pelas permissões de revisão. Execute código candidato de validação com privilégios restritos e revise mudanças nas regras com o mesmo cuidado aplicado a mudanças no documento.

Use um prompt final de entrega:

Resuma os artefatos alterados e as decisões propostas.
Liste comandos realmente executados, seus resultados e as localizações das evidências.
Separe verificações estruturais, testes comportamentais e revisão humana.
Liste suposições pendentes com responsáveis e próximas ações.
Informe se o documento é um rascunho ou está pronto para revisão de design.
Não alegue aprovação, prontidão para implementação ou implantação sem evidências.

Quando um requisito mudar, atualize seu contrato, diagramas, registro de decisão e plano de verificação na mesma revisão. O documento cumpre seu papel quando uma pessoa engenheira futura consegue rastrear uma decisão até sua justificativa, identificar o que continua incerto e verificar se a implementação ainda a respeita.