Capítulo 13 — Arquitetura de Evidência

Quando podemos dizer que uma mudança está pronta?

Em desenvolvimento tradicional, é comum ouvir:

“funciona na minha máquina”;
“os testes passaram”;
“o PR parece bom”;
“subiu em staging”;
“não apareceu erro”.

Cada frase pode conter alguma evidência.

Nenhuma, sozinha, prova prontidão.

Em sistemas agênticos, isso fica ainda mais importante porque a velocidade de produção pode ultrapassar a capacidade humana de inspecionar tudo em detalhe.

Hassan trata confiança em escala como um problema de evidência verificável sobre especificação, restrições, testes, runtime e rastreabilidade, em vez de depender de execução determinística passo a passo. ¹

A tese deste capítulo é:

ready é um estado demonstrado por evidência suficiente, não uma sensação de plausibilidade.

Evidence obligation

Antes de começar uma tarefa, deveríamos saber que prova será exigida no final.

No método deste livro, isso se chama Evidence Obligation.

Ela responde:

o que precisa ser verdadeiro?
como isso será verificado?
qual artefato comprova?
quem aceita?
qual risco continua aberto?
que evidência de recovery existe?

No nosso método, Evidence Obligation é parte da Spec e acompanha a mudança até a entrega.

Da Spec ao proof

A relação ideal é:

Requirement
  ↓
Acceptance criterion
  ↓
Check
  ↓
Evidence
  ↓
Decision

Quando não existe essa ligação, encontramos dois anti-patterns.

Evidence without requirement

Há muitos logs, testes e relatórios, mas ninguém sabe o que eles provam.

Requirement without evidência

Existe uma promessa textual, mas nenhum mecanismo demonstra que foi cumprida.

Arquitetura de evidência conecta os dois lados.

Seis camadas

O método deste livro organiza evidência em seis camadas:

Evidência pré-código
Evidência de implementação
Evidência de merge
Evidência de entrega
Evidência de runtime
Evidência de recuperação

Isso é método deste livro.

1. Evidência pré-código

Antes do código, precisamos registrar:

intenção;
domínio;
invariants;
restrições;
acceptance criteria;
risco;
autonomia;
boundaries.

Essa camada prova que existe algo verificável para construir.

Sem isso, o agente pode produzir uma implementação tecnicamente correta para um problema mal definido.

2. Evidência de implementação

Durante a implementação, evidências podem incluir:

unit tests;
integration tests;
type checks;
lint;
static analysis;
schema validation;
contract tests;
security checks;
generated artifacts;
benchmark quando relevante.

McEntire distingue gates mecânicos, que avaliam artefatos contra especificações reproduzíveis, de revisão consultiva, que depende de julgamento e pode variar entre avaliadores. ²

Nem toda verificação precisa de humano.

E nem todo julgamento pode ser reduzido a check automático.

Mechanical gate

Um gate mecânico responde perguntas como:

compila?
schema é válido?
teste passa?
migration aplica?
lint está limpo?
contrato quebrou?

O gate deve ser executável, repetível, observável e associado a uma condição explícita.

Verification theater

Um pipeline pode ter dezenas de checks e ainda provar pouco.

Exemplos:

testes que não cobrem o fluxo modificado;
lint apresentado como evidência de correção;
coverage sem qualidade de assertions;
snapshot aceito automaticamente;
teste gerado pelo mesmo agente sem challenge independente;
CI verde com etapas importantes marcadas optional.

Chamamos isso de verification theater.

Mais checks não equivalem automaticamente a mais confiança.

Evidence quality

No método deste livro, avaliamos evidência por:

Relevance;
Independence;
Reproducibility;
Freshness;
Provenance;
Integrity;
Coverage.

Essa taxonomia é método deste livro.

3. Evidência de merge

Código completo não é necessariamente merge-ready.

Hassan descreve Merge-Readiness Pack como um bundle estruturado de evidências que conecta critérios de sucesso a verificações, resultados, rationale, riscos e audit trail. ³

O revisor não deveria reconstruir a história da mudança manualmente a partir de chat, diff, logs dispersos, commits, CI e comentários.

A evidência precisa chegar organizada.

Scope-to-proof map

No nosso EVIDENCE.md, cada critério pode apontar para a prova correspondente.

Criterion	Check	Result	Evidence
pagamento idempotente	integration test	PASS	run #882
schema backward-compatible	contract check	PASS	artifact/schema-diff.json
sem novo secret em repo	secret scan	PASS	CI security job
rollback disponível	rollback drill	PASS	release evidência

EVIDENCE.md

O artefato central deste capítulo é EVIDENCE.md.

Estrutura proposta:

# Evidence

## Change
- id
- revision
- owner
- risk tier

## Evidence Obligation
- criterion
- required proof
- acceptance authority

## Pre-code
## Implementation
## Merge
## Delivery
## Runtime
## Recovery

## Open Risks
## Exceptions
## Decision
## Provenance

EVIDENCE.md não precisa conter todos os dados brutos.

Ele pode funcionar como índice.

4. Evidência de entrega

Passar no PR não prova que o software chegou corretamente ao ambiente seguinte.

Evidência de entrega pode incluir:

build artifact;
image digest;
SBOM;
CI result;
migration plan;
staging verification;
deployment metadata;
release version;
signature/checksum;
approval gate.

A questão aqui é:

o que foi verificado é exatamente o que foi entregue?

Artifact identity

Sem identidade clara, podemos testar uma coisa e publicar outra.

Por isso, evidência de entrega precisa ligar:

commit
  ↓
build run
  ↓
image digest
  ↓
release id
  ↓
runtime instance

Essa cadeia é provenance operacional.

Readiness é uma leitura da evidência, não um estado único

Hassan distingue estados como code-complete, merge-ready e integration-ready; eles não são equivalentes porque exigem evidências diferentes. ⁴

No método deste livro, readiness é uma interpretação do evidência bundle naquele ponto do lifecycle, não um rótulo absoluto.

Exemplos:

code complete — a implementação pretendida existe;
merge ready — evidência suficiente para entrar na linha principal;
delivery ready — artifact identificado e promoção preparada;
runtime validated — comportamento real observado;
recovery ready — caminho de retorno ou mitigação demonstrável.

O capítulo não define como cada transição é executada. Isso será responsabilidade de Gates, Review e Delivery.

5. Evidência de runtime

Alguns defeitos só aparecem em execução real.

Evidência de runtime pode incluir:

health;
readiness;
logs;
metrics;
traces;
error rate;
latency;
saturation;
business KPIs;
canary comparison;
synthetic checks.

A pergunta muda de “o deploy terminou?” para “o sistema está se comportando dentro dos limites esperados?”.

Expected vs observed

Evidência de runtime exige comparação.

Não basta registrar um valor. Precisamos saber baseline, threshold, janela, segmento, versão e contexto.

Observability não é automaticamente evidência. Logs e métricas viram evidência quando correspondem a uma pergunta e são interpretados contra um critério.

6. Evidência de recuperação

Uma mudança de alto risco não está completamente pronta se ninguém sabe como desfazê-la.

Adkins et al. mostram que eliminar completamente a possibilidade de rollback cria risco de confiabilidade, pois uma atualização defeituosa pode impedir retorno a um estado conhecido como bom. ⁵

Evidência de recuperação pode incluir:

rollback command;
rollback artifact;
backup;
restore test;
feature flag;
previous release;
runbook;
recovery drill.

“Tem rollback” não é evidência.

Melhor é registrar comando testado, ambiente, tempo medido, dependências verificadas e resultado.

Evidence cresce com risco

O princípio editorial deste capítulo é:

evidência cresce com risco, autonomia e blast radius.

Mudanças pequenas podem exigir poucas provas. Mudanças de API, migrations, auth ou produção crítica precisam de evidência mais ampla e independente.

Essa proporcionalidade é método deste livro.

Evidence Budget

Exigir o máximo de prova para qualquer mudança paralisa o fluxo. Exigir pouco demais aumenta risco.

Podemos definir um Evidence Budget por risk tier.

R0

diff;
basic check.

R1

tests;
lint;
revisão.

R2

integration;
contracts;
rollout evidência.

R3

security;
staging;
explicit approval;
runtime monitoring;
recovery drill.

O modelo exato varia por organização.

Provenance é parte da evidência

Evidence sem origem verificável perde força. Para artefatos relevantes, precisamos conseguir reconstruir versão, ferramenta, input, momento e resultado suficientes para ligar a prova à mudança correta.

Aqui, provenance responde de onde veio a evidência. No Capítulo 15, Git e revisão mostrarão como essa evidência participa da decisão e vira memória operacional.

Evidence graph

Em vez de pensar em documentos isolados, podemos pensar em grafo:

Intent
  ↓
Spec
  ↓
Criterion
  ↓
Check
  ↓
Evidence
  ↓
Decision
  ↓
Delivery
  ↓
Runtime
  ↓
Learning

Cada nó tem links para os anteriores.

O Evidence Graph é método deste livro.

Evidence não decide sozinho

Um evidência bundle pode sustentar uma decisão, mas não substitui a decisão.

Alguma policy ou revisor ainda precisa registrar um desfecho como accepted, rejected, exception, deferred ou escalated.

Este capítulo para na fronteira entre provar propriedades e decidir se a mudança pode avançar. O Capítulo 15 tratará dessa segunda função.

Exception handling

Às vezes um gate falha e ainda assim existe razão legítima para prosseguir.

A exceção precisa ser explícita, autorizada, temporária quando aplicável, ligada ao risco e auditável.

Bypass silencioso destrói confiança no gate.

Evidence expiration e drift

Algumas provas expiram: scans, staging results, runtime health, backups, credenciais e aprovações.

Também pode haver drift entre Spec e implementação, tests e comportamento, artifact e runtime, runbook e infraestrutura.

Por isso, algumas evidências precisam ser continuamente regeneradas.

Falha típica: screenshot como prova universal

Screenshot pode provar aparência. Não prova regra, persistência, autorização, performance ou recovery.

Falha típica: CI verde sem lineage

Se não sabemos qual commit produziu o artifact implantado, o verde perde valor operacional.

Falha típica: revisor como test suite

Quando todo bug precisa ser descoberto por leitura humana, o processo não escala.

Review deve focar trade-offs, arquitetura, risco, intenção e exceções. Checks repetíveis devem ser mecanizados quando possível.

Falha típica: evidência produzida depois da decisão

Primeiro mergeamos. Depois montamos justificativa.

Esse fluxo transforma Evidence em documentação retrospectiva. A obrigação precisa ser conhecida antes ou durante a mudança.

Evidence as interface entre humano e agente

Quando agentes produzem mudanças em alta velocidade, humanos não conseguem repetir todo o trabalho.

Hassan propõe concentrar revisão humana em bundles estruturados de evidência em vez de obrigar o revisor a reconstruir tudo a partir de PRs crus. ³

Menos arqueologia. Mais julgamento.

Da evidência aos gates

Arquitetura de evidência define o que provar, onde registrar, como ligar e quem aceita.

O próximo capítulo trata de tornar parte dessa arquitetura executável: TDD, unit/integration/system tests, static checks, schemas, contracts, security checks e evals.

Fronteira de confiança

Toda evidência cruza uma boundary entre quem produziu a mudança e quem decide aceitá-la. Tool output, test result, log e relatório precisam de provenance e escopo. Evidência produzida pelo mesmo mecanismo que gerou a mudança pode ser válida, mas seu grau de independência deve ser conhecido.

Evidência exigida

Antes da implementação, declare a Evidence Obligation. Durante o ciclo, mantenha um scope-to-proof map ligando critérios a checks e artifacts. Readiness só avança quando a camada correspondente possui evidência suficiente.

Rollback e recuperação

Recovery faz parte da arquitetura de evidência. Mudanças de risco elevado devem demonstrar não apenas que podem ser implantadas, mas que existe mecanismo seguro e testado de retorno, mitigação ou restauração quando a hipótese de sucesso falha.

Proveniência das fontes

Rastreabilidade deste capítulo:

CLM-007 — Hassan, confiança em escala por evidência verificável;
CLM-008 — McEntire, distinção entre gates mecânicos e revisão consultivo;
CLM-047 — Hassan, Merge-Readiness Pack como evidência bundle estruturado;
CLM-048 — Hassan, layered readiness;
CLM-049 — Adkins et al., necessidade de preservar caminho de rollback/recovery.

As seis camadas de evidência, Evidence Budget, Evidence Quality, Evidence Graph e formato EVIDENCE.md são método deste livro.

O comparável de Nissl permanece fonte limitada e não foi usado como autoridade factual.

Fontes de acesso limitado não foram usadas como autoridade factual neste capítulo.

Recursos complementares

Recursos relacionados:

EVIDENCE.md template;
scope-to-proof map;
Evidence Obligation template;
Evidence Graph;
risk-tier Evidence Budget;
checklist de evidência de runtime;
checklist de evidência de recuperação;
futura visualização PCC de readiness por camada.

Living Book Expanded · capítulo executável

Arquitetura de Evidência: abrir Evidence Lab. A camada expandida preserva o texto estável e mantém repo/arquivo/commit e What changed? separados do manuscrito canônico.

Ahmed E. Hassan, Agentic Software Engineering (2026), front matter / scale flips the bottleneck, p. 13. Rastreabilidade interna: CLM-007. ↩
Jeremy McEntire, Beyond Code (2026), Chapter 6: Mechanical Gates Over Advisory Review, p. 57. Rastreabilidade interna: CLM-008. ↩
Ahmed E. Hassan, Agentic Software Engineering (2026), Structured evidence: the Merge-Readiness Pack and the Resolution Record, p. 50. Rastreabilidade interna: CLM-047. ↩ ↩²
Ahmed E. Hassan, Agentic Software Engineering (2026), Glossary Table — Layered readiness, p. 415. Rastreabilidade interna: CLM-048. ↩
Adkins et al., Building Secure & Reliable Systems (2020), Chapter 9: Design for Recovery — Rollbacks Represent a Tradeoff Between Security and Reliability, pp. 229–230. Rastreabilidade interna: CLM-049. ↩