Skip to content
Da Vibe Coding à Engenharia Agêntica

Capítulo 15 — Review, Git e memória operacional

Preservar decisão, não apenas código

Section titled “Preservar decisão, não apenas código”

Depois que Spec virou propriedade verificável e os gates mecânicos passaram, ainda resta uma pergunta:

o que precisa existir para alguém aceitar esta mudança?

O diff mostra o que mudou.

Ele não mostra sozinho:

  • por que mudou;
  • qual requisito motivou;
  • que risco foi aceito;
  • quais alternativas foram rejeitadas;
  • que evidência sustentou a decisão;
  • quem aprovou;
  • como voltar.

Por isso, revisão não deve ser tratado apenas como leitura de código.

É uma etapa de governança da mudança.

A cadeia de revisão

Section titled “A cadeia de revisão”

O método deste livro usa a seguinte cadeia:

Spec
  ↓
Change Episode
  ↓
branch/worktree
  ↓
diff
  ↓
tests + evidência
  ↓
commit
  ↓
PR
  ↓
approval / resolution
  ↓
merge
  ↓
rollback point

Isso é método deste livro.

A ideia é simples:

nenhum elo deveria ficar órfão.

Diff é unidade de mudança, não de contexto completo

Section titled “Diff é unidade de mudança, não de contexto completo”

Diff é excelente para responder:

“o que mudou entre dois estados?”

Mas é limitado para responder:

  • “por que?”;
  • “qual risco?”;
  • “qual requisito?”;
  • “qual evidência?”;
  • “qual decisão?”.

Por isso, diff deve ser acompanhado de provenance.

Hassan et al. defendem que revisão de trabalho agêntico precisa apoiar-se em uma trilha de auditoria versionada que conecte artefatos, ferramentas e evidências, em vez de depender apenas da leitura de PRs crus ou de trajetórias de chat. 1

Small diff

Section titled “Small diff”

Mudanças menores são mais fáceis de:

  • revisar;
  • testar;
  • explicar;
  • reverter;
  • atribuir a uma intenção específica.

No método deste livro, small-batch change continua valendo no revisão.

Um PR enorme aumenta:

  • superfície cognitiva;
  • risco de comportamento escondido;
  • custo de regressão;
  • dificuldade de rollback.

Commit como checkpoint

Section titled “Commit como checkpoint”

Commit é mais que “salvar progresso”.

Pode funcionar como checkpoint semântico.

Um bom checkpoint responde:

  • que estado está sendo preservado?
  • que hipótese acabou de ser validada?
  • que parte da mudança ficou concluída?

Exemplo:

feat(auth): add token validation boundary

é mais útil que:

update files

Commit pequeno não significa commit arbitrário

Section titled “Commit pequeno não significa commit arbitrário”

Pequeno deve significar coeso.

Um commit idealmente contém uma unidade de intenção que:

  • compila ou é consistente;
  • tem evidência correspondente;
  • pode ser revertida com efeito compreensível.

Branch como espaço de mudança

Section titled “Branch como espaço de mudança”

Branch cria isolamento lógico.

No método deste livro, a branch deve representar uma Change Episode ou uma unidade de trabalho claramente identificável.

Exemplo:

feat/vibe-book-chapter-15-zero-draft

O nome não precisa conter toda a Spec.

Mas deve permitir ligação com o trabalho.

Worktree como isolamento físico

Section titled “Worktree como isolamento físico”

Git worktree permite manter mais de uma working tree associada ao mesmo repositório.

Isso é útil quando:

  • dois agentes trabalham em branches distintas;
  • uma tarefa precisa continuar enquanto outra é revisada;
  • queremos evitar troca constante de branch.

No método deste livro, worktree é implementação opcional, não requisito conceitual.

O risco da branch longa

Section titled “O risco da branch longa”

Quanto mais tempo a branch diverge:

  • maior chance de conflito;
  • maior diferença de contexto;
  • maior custo de integração;
  • maior risco de assumptions desatualizadas.

Por isso, branches de agente devem tender a ciclos curtos quando possível.

Review orientado por intenção

Section titled “Review orientado por intenção”

Um revisor não deveria começar perguntando apenas:

“esse código está bom?”

Perguntas melhores:

  • qual era a intenção?
  • que comportamento deveria mudar?
  • que comportamento deveria permanecer?
  • o diff corresponde à Spec?
  • os gates observam os riscos relevantes?
  • existe mudança fora do escopo?

Review por progressive disclosure

Section titled “Review por progressive disclosure”

Review escalável exige progressive disclosure: primeiro uma superfície resumida, depois aprofundamento em testes, logs, traces e evidências quando necessário. 2

Uma boa PR surface pode conter:

Summary

Section titled “Summary”

O que mudou.

Why

Section titled “Why”

Por que mudou.

Scope

Section titled “Scope”

O que entrou e o que ficou fora.

Evidence

Section titled “Evidence”

Quais gates passaram.

Risk

Section titled “Risk”

Blast radius e pontos sensíveis.

Rollback

Section titled “Rollback”

Como retornar.

Open questions

Section titled “Open questions”

O que ainda depende de decisão.

Depois o revisor abre detalhes sob demanda.

PR não é apenas formulário

Section titled “PR não é apenas formulário”

Pull Request é uma boundary de integração.

Ele junta:

  • branch;
  • diff;
  • checks;
  • comments;
  • approvals;
  • merge decision.

No método deste livro, o PR é parte da evidência chain.

Não é a cadeia inteira.

Spec ↔ PR

Section titled “Spec ↔ PR”

A PR deve apontar para a Spec ou Mission Brief equivalente.

Isso permite verificar:

criterion
  ↓
change
  ↓
evidência

Sem esse vínculo, revisão vira reconstrução de intenção.

Tests ↔ PR

Section titled “Tests ↔ PR”

Checks precisam estar visíveis ou linkados.

Exemplo:

acceptance criterion A
  → test_auth_refresh
  → CI run #239
  → PASS

O revisor não precisa confiar em “rodei localmente”.

Commit ↔ PR

Section titled “Commit ↔ PR”

O conjunto de commits conta a história executada.

Pode divergir do plano inicial.

Essa divergência não é necessariamente problema.

Mas precisa ser compreensível.

Plan vs executed plan

Section titled “Plan vs executed plan”

Mudança real frequentemente descobre fatos novos.

Por isso, revisão deve registrar:

  • plano inicial;
  • execução real;
  • divergências relevantes;
  • rationale.

Isso evita dois extremos:

  • fingir que tudo saiu como planejado;
  • tratar qualquer divergência como falha.

Approval não é emoji

Section titled “Approval não é emoji”

Approval representa decisão de integração.

No método deste livro, uma aprovação relevante deveria ter contexto suficiente para responder:

  • o que foi aceito?
  • com base em que evidência?
  • sob quais restrições?
  • quem tinha autoridade?

Resolution Record

Section titled “Resolution Record”

Hassan descreve Resolution Record como registro durável da decisão, ligado aos artefatos e evidências que a justificaram. Sem esse registro, revisão tende a ser evento isolado e o conhecimento se perde. 3

No método deste livro, podemos representar isso de forma leve.

Exemplo:

decision: approved
revision: abc123
evidência: CI #239, security scan #88
constraints: feature flag required
authority: maintainer
date: ...

Decisão vira memória operacional

Section titled “Decisão vira memória operacional”

Quando uma decisão é registrada, ela pode alimentar:

  • futura Spec;
  • runbook;
  • policy;
  • architecture record;
  • regression test;
  • onboarding;
  • incident analysis.

Review deixa de ser evento descartável.

Git como memória

Section titled “Git como memória”

Git preserva:

  • snapshots;
  • autoria;
  • timestamps;
  • branches;
  • merges;
  • diffs;
  • tags.

Mas Git não conhece automaticamente:

  • requisito;
  • rationale;
  • risco;
  • approval authority;
  • evidência de runtime.

Por isso, Git é infraestrutura da memória operacional, não a memória completa.

Commit message como índice

Section titled “Commit message como índice”

Commit message deve apontar para significado.

Ele não precisa conter um relatório inteiro.

Mas pode funcionar como índice para:

  • issue;
  • Change Episode;
  • PR;
  • migration;
  • decision record.

Tag como marco

Section titled “Tag como marco”

Tags podem marcar:

  • release;
  • baseline;
  • recovery point;
  • migration boundary.

Isso facilita reconstrução histórica.

Rollback point como referência de decisão

Section titled “Rollback point como referência de decisão”

Git ajuda a identificar estados de código antes e depois de uma decisão. Isso cria pontos claros para comparação e, em alguns casos, para revert.

Mas este capítulo não trata revert como recovery completa. Dados, side effects, credentials e artifacts podem exigir mecanismos operacionais adicionais.

Aqui, o papel do rollback point é preservar qual estado foi aceito e qual estado o precedeu. O Capítulo 16 tratará da promoção do artifact; os capítulos de Operations e Recovery tratarão da volta segura em runtime.

Merge strategy

Section titled “Merge strategy”

Squash, merge commit e rebase têm trade-offs.

Este livro não prescreve uma estratégia universal.

O requisito é preservar:

  • traceability;
  • coherent history;
  • evidência links;
  • rollback reasoning.

Squash

Section titled “Squash”

Pode simplificar history quando a branch contém muitos commits experimentais.

Risco:

  • perder checkpoints internos úteis.

Merge commit

Section titled “Merge commit”

Preserva estrutura da branch.

Pode facilitar reconstrução de integração.

Risco:

  • history mais ruidosa.

Rebase

Section titled “Rebase”

Pode produzir sequência linear e limpa.

Risco:

  • reescrever identidade de commits já compartilhados.

A escolha deve servir o modelo operacional.

Merge queue

Section titled “Merge queue”

Em equipes ou frotas de agentes com alto paralelismo, branches podem passar isoladamente e falhar quando combinadas.

Merge queue reduz esse risco ao testar combinações próximas do estado real de integração.

Isso pertence ao capítulo de delivery em maior profundidade, mas afeta revisão readiness.

Provenance

Section titled “Provenance”

Provenance responde:

de onde veio esta mudança e por que confiamos nela?

Uma cadeia mínima pode ser:

Spec ID
  ↓
Change Episode
  ↓
branch
  ↓
commit SHA
  ↓
CI run
  ↓
PR
  ↓
approval
  ↓
merge SHA

Change Episode

Section titled “Change Episode”

O projeto deste livro usa Change Episode como implementação prática de memória da mudança.

Ele registra:

  • intent;
  • risk;
  • autonomy;
  • branch;
  • evidência;
  • delivery;
  • outcome.

Isso é método deste livro.

Não tratamos Change Episode como conceito histórico inédito.

É uma implementação da necessidade mais geral de rastreabilidade e memória operacional.

Project Command Center

Section titled “Project Command Center”

O Project Command Center também é implementação.

Ele consolida:

  • status;
  • roadmap;
  • current state;
  • next action;
  • Change Episodes;
  • evidência pointers.

O conceito subjacente é mais amplo:

um sistema precisa de estado operacional legível e retomável.

Chat não é source of truth

Section titled “Chat não é source of truth”

Chat é útil para exploração.

Mas é fraco como memória canônica porque:

  • pode ser longo;
  • pode conter hipóteses descartadas;
  • pode não refletir estado final;
  • pode estar separado do código.

Decisões importantes devem migrar para artefatos duráveis.

Falha típica: “está no histórico”

Section titled “Falha típica: “está no histórico””

Histórico existe, mas ninguém sabe onde procurar.

Memória operacional precisa de indexação.

Links ajudam:

  • Spec → PR;
  • PR → commit;
  • commit → CI;
  • PR → decision;
  • decision → deploy.

Falha típica: commit gigante

Section titled “Falha típica: commit gigante”

Um commit que mistura:

  • refactor;
  • feature;
  • migration;
  • formatting;
  • dependency update;

fica difícil de explicar e reverter.

Separação semântica melhora revisão.

Falha típica: aprovação sem revisão do scope

Section titled “Falha típica: aprovação sem revisão do scope”

Checks verdes podem esconder mudança fora do pedido.

Review precisa comparar touch set com intenção.

Falha típica: resolução só no chat

Section titled “Falha típica: resolução só no chat”

Hassan alerta para decisões que permanecem efêmeras quando não viram registro durável. 3

Se uma exceção importante foi aprovada apenas em chat, o próximo agente pode repetir a discussão do zero.

Falha típica: merge sem rollback point

Section titled “Falha típica: merge sem rollback point”

Se não sabemos que estado restaurar, o merge vira one-way door operacional.

Mesmo quando revert é simples, o ponto anterior precisa estar identificável.

Review Checklist

Section titled “Review Checklist”

Artefato operacional deste capítulo:

Intent

Section titled “Intent”
  • Spec/issue/episode está linkado?

Scope

Section titled “Scope”
  • diff corresponde ao pedido?
  • existe touch set inesperado?

Evidence

Section titled “Evidence”
  • checks relevantes passaram?
  • evidência está ligada aos critérios?

Risk

Section titled “Risk”
  • blast radius está explícito?
  • efeitos externos foram considerados?

Decision

Section titled “Decision”
  • approval authority está correta?
  • exceções estão registradas?

Recovery

Section titled “Recovery”
  • rollback point está identificado?
  • há efeitos não reversíveis?

Memory

Section titled “Memory”
  • decisão durável foi registrada?

O revisor não precisa ler tudo sempre

Section titled “O revisor não precisa ler tudo sempre”

Progressive disclosure reduz custo de revisão. 2

Comece com:

  • summary;
  • risk;
  • evidência;
  • diff stats.

Aprofunde onde o risco pede.

Isso é diferente de revisão superficial.

É revisão orientado por risco.

Review como compression boundary

Section titled “Review como compression boundary”

O trabalho do agente pode gerar:

  • milhares de ferramenta calls;
  • logs extensos;
  • tentativas descartadas.

A PR deve comprimir isso em informação decisória.

Mas a compressão precisa manter ponteiros para o detalhe.

Institutional memory

Section titled “Institutional memory”

A memória operacional nasce quando:

  • decisão;
  • evidência;
  • rationale;
  • outcome;

podem ser recuperados no futuro.

Isso reduz:

  • debate repetido;
  • regressão de policy;
  • redescoberta de risco;
  • dependência de memória individual.

Do revisão ao delivery

Section titled “Do revisão ao delivery”

Review encerra uma decisão sobre a mudança; não encerra sua jornada até produção.

A saída deste capítulo deve ser inequívoca:

  • intenção identificada;
  • diff e commits rastreáveis;
  • Evidence ligado à mudança;
  • decisão registrada;
  • revision/merge SHA conhecida.

O próximo capítulo recebe exatamente essa saída e responde outra pergunta:

como garantir que o artifact promovido é o artifact correspondente à revisão aprovada, sob permissions, rollout e recovery controls adequados?

Fronteira de confiança

Section titled “Fronteira de confiança”

Review é uma trust boundary entre mudança proposta e integração. Diff, CI, evidência pack e approval precisam referir-se à mesma revisão. Se o código muda depois da aprovação, a confiança precisa ser reavaliada.

Evidência exigida

Section titled “Evidência exigida”

Merge exige rastreabilidade mínima de Spec → diff → evidência → approval. O revisor deve conseguir reconstruir por que a revisão específica foi aceita sem depender de memória informal.

Rollback e recuperação

Section titled “Rollback e recuperação”

Antes do merge, identifique o rollback point e separe reversibilidade de código de reversibilidade operacional. Git pode restaurar conteúdo versionado; efeitos em dados, infraestrutura e sistemas externos podem exigir mecanismos adicionais.

Proveniência das fontes

Section titled “Proveniência das fontes”

Rastreabilidade deste capítulo:

  • CLM-053 — Hassan et al., trilha de auditoria versionada para supervisão orientada por evidências;
  • CLM-054 — Hassan, Resolution Record como decisão durável e memória institucional;
  • CLM-055 — Hassan et al., progressive disclosure para revisão escalável.

Change Episode, Review Checklist, cadeia Spec → Episode → branch → diff → evidência → commit → PR → approval → merge → rollback point e uso do Project Command Center são método deste livro.

O comparável de Liao 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

Section titled “Recursos complementares”

Recursos relacionados:

  • Review Checklist;
  • Change Episode template;
  • PR evidence-link template;
  • Resolution Record leve;
  • rollback-point checklist;
  • provenance chain template;
  • futura visualização PCC de Spec ↔ commit ↔ CI ↔ PR ↔ deploy.

Living Book Expanded · capítulo executável

Review, Git e memória operacional: abrir Review Lab. A camada expandida preserva o texto estável e mantém repo/arquivo/commit e What changed? separados do manuscrito canônico.

Footnotes

Section titled “Footnotes”

  1. Hassan et al., Agentic Software Engineering: Foundational Pillars and a Research Roadmap, 4.2.4 From Code Review to Evidence-Based Oversight, p. 11. Rastreabilidade interna: CLM-053. ↩

  2. Hassan et al., Agentic Software Engineering: Foundational Pillars and a Research Roadmap, 4.2.4 From Code Review to Evidence-Based Oversight, pp. 11–12. Rastreabilidade interna: CLM-055. ↩ ↩2

  3. Ahmed E. Hassan, Agentic Software Engineering (2026), Structured escalation: the Consultation Request Pack and the Resolution Record, pp. 51–52. Rastreabilidade interna: CLM-054. ↩ ↩2