Cada execução ensina a próxima

A situação: corrigir o código sem corrigir o sistema

Durante a revisão de uma mudança, a equipe encontra um access token, credencial temporária de acesso, no log. O token é removido e o ticket é encerrado. Três semanas depois, outra rota registra a mesma informação. A primeira correção resolveu um arquivo; não ensinou o sistema a impedir a classe de falha.

“Cada execução ensina a próxima” significa escolher um artefato durável para o aprendizado: teste, política, automação, documentação ou arquitetura. Não significa guardar toda conversa na memória do agente nem acrescentar “tome cuidado” a um prompt cada vez maior.

Antes da retrospectiva, porém, o trabalho precisa de revisão independente. Este capítulo mostra os dois movimentos: avaliar a entrega atual e melhorar o ambiente que produzirá a próxima.

Vocabulário antes do processo

• Code review é a revisão de uma mudança por outra pessoa ou contexto, com base em critérios e evidências.
• Conformidade com a especificação pergunta se a mudança resolve o problema e respeita os limites acordados.
• Conformidade de engenharia pergunta se a solução é segura, legível, testável, operável e compatível.
• Achado é um problema observado, acompanhado de evidência e consequência.
• Severidade representa o impacto e a urgência, não o gosto do revisor.
• Owner é a pessoa ou equipe responsável por decidir ou manter um controle.
• Hook é uma automação acionada por um evento local; CI gate é um portão automático no fluxo de integração.
• ADR — Architecture Decision Record, ou registro de decisão arquitetural, preserva uma escolha difícil de reverter e suas consequências.
• Skill é um procedimento especializado carregado sob demanda por um agente.
• Redaction é a remoção ou substituição de informação sensível antes de registrar ou exibir dados.
• MCP — Model Context Protocol é um protocolo para conectar sistemas de IA a dados e ferramentas externas.
• Harness é o entorno que compõe contexto, ferramentas, permissões, limites e verificações para a execução do agente; uma policy é uma regra aplicada por esse entorno.
• Dívida de instruções surge quando regras se acumulam sem revisão, entram em conflito e consomem contexto.

Modelo mental: duas lentes e uma oficina

Use duas lentes para revisar. A primeira enxerga o contrato: atores, estados, erros, aceite e fora de escopo. A segunda enxerga a construção: autorização, transação, concorrência, dados, logs, testes, operação e rollback. Uma mudança pode passar por uma lente e falhar pela outra.

Depois, leve a falha à “oficina do processo”. Em vez de polir apenas o artefato atual, descubra qual ferramenta evitará a repetição. A analogia termina quando o controle depende de julgamento: nem todo problema pode ser automatizado, e um owner humano continua responsável por decisões de risco.

O losango “pode repetir?” evita transformar toda observação em nova regra global. Uma falha isolada e barata pode exigir apenas correção local; uma classe recorrente ou de alto impacto exige controle sistêmico.

Passe 1 — conformidade com a especificação

Comece pela spec, não pelo estilo do código. Confirme:

1. o problema e o usuário estão atendidos;
2. pré-condições, pós-condições e invariantes foram preservados;
3. caminho nominal, erros e abusos possuem evidência;
4. interfaces correspondem ao contrato;
5. itens fora de escopo não foram adicionados silenciosamente;
6. critérios de aceite podem ser ligados a testes ou inspeções.

No caso da aprovação de OS, uma solução pode exibir o botão correto e gravar APPROVED, mas esquecer a negação entre unidades. Ela parece funcional e falha no contrato de autoridade.

Um comentário acionável seria:

[Alta] Aprovação atravessa a fronteira de unidade

Reprodução: supervisor unit=south envia POST para OS unit=north e recebe 200.
Critério violado: AC-04 exige negação sem mudança de estado.
Impacto: acesso indevido e trilha de auditoria falsa.
Evidência esperada: teste de contrato com 403 e versão da OS inalterada.

“Não gostei” não informa critério, consequência nem reprodução. O revisor não precisa escrever a implementação substituta; precisa tornar o risco verificável.

Passe 2 — conformidade de engenharia

Agora examine como a solução foi construída:

• autorização e validação estão no servidor?
• transação e concorrência mantêm consistência?
• repetições automáticas (retries) são idempotentes?
• logs e rastros técnicos (traces) evitam segredos e dados excessivos?
• testes observam comportamento ou apenas substitutos simulados (mocks)?
• dependências, licença e vulnerabilidades foram avaliadas?
• métricas e mensagens permitem operar a mudança?
• existe compatibilidade e rollback?
• o diff permanece focado e compreensível?

Esses pontos concretizam, para este projeto, categorias também presentes na orientação oficial do Google sobre o que procurar numa revisão de código, como design, funcionalidade, complexidade, testes, nomes, comentários e documentação.

Uma implementação pode satisfazer todos os exemplos atuais e ainda criar uma consulta sem índice que derruba produção. Também pode ser tecnicamente elegante e resolver o requisito errado. Por isso os eixos não devem ser fundidos numa nota genérica.

Independência: por que o autor não é o único revisor

Auto-revisão é barata e útil. Peça ao agente criador para comparar a mudança com a spec, reler o diff e executar verificações. Mas ele compartilha as mesmas suposições e o mesmo contexto que produziram a solução.

Para risco relevante, use outro revisor — humano ou agente em contexto separado — com acesso à especificação, ao diff e às evidências, mas sem a narrativa persuasiva da implementação. A decisão final sobre ações irreversíveis, dados pessoais, segurança e produção permanece com o owner humano autorizado.

Multiagente não é sinônimo de independência. Dois agentes que recebem o mesmo resumo incompleto podem repetir a mesma falha. Independência vem de papel, contexto, critérios e evidência adequadamente separados.

Priorização de achados

Classifique por impacto provável e urgência:

Nível	Exemplo	Tratamento
bloqueador	perda de dados, autorização quebrada, segredo exposto	não aprovar; corrigir e repetir os portões
alto	regressão central, concorrência inconsistente	corrigir antes de integrar ou obter decisão explícita do owner
médio	operação frágil, teste insuficiente, manutenção custosa	planejar correção com prazo e responsável
baixo	clareza local sem risco imediato	sugestão, sem esconder achados mais importantes

Não use quantidade de comentários como medida de qualidade. Dez preferências de estilo não compensam uma falha de autorização omitida.

Retrospectiva: escolha o controle certo

Depois de corrigir a entrega, pergunte se a classe de falha pode reaparecer. Encaminhe o aprendizado ao mecanismo apropriado:

Falha recorrente	Controle preferido	Por que
regra de domínio regressa	teste determinístico	o comportamento é executável e binário
segredo entra no log	redaction central + scanner/CI	não deve depender de interpretação
comando correto é esquecido	instrução curta no repositório	é estável e sempre relevante naquele escopo
procedimento especializado reaparece	skill testada	carrega método sob demanda sem inflar todo contexto
decisão estrutural volta à pauta	ADR	preserva contexto, decisão e consequências
ferramenta extrapola autoridade	policy do harness	bloqueia a ação no ponto de execução
dados externos mudam	validação de contrato e monitor	detecta deriva observável
arquitetura força duplicação	refatoração planejada	concentra complexidade atrás de interface menor

Memória serve para fatos duráveis e aprovados, não para despejar transcrições. MCP oferece acesso a dados ou ações externas; não é substituto para regra. Um hook ou CI deve assumir regras determinísticas que não podem depender da atenção do modelo.

Exemplo executável: token em logs

Este exemplo TypeScript demonstra uma proteção central pequena. Salve-o como redact-secrets.mts:

export function redactSecrets(message: string): string {
  return message
    .replace(/Bearer\s+[A-Za-z0-9._-]+/gi, "Bearer [REDACTED]")
    .replace(/access_token=[^&\s]+/gi, "access_token=[REDACTED]");
}

A função recebe uma mensagem e substitui dois formatos conhecidos. Ela não deve ser considerada detector universal de segredos; o controle real combina tipos seguros, logging estruturado, lista de campos permitidos e scanner.

Salve o teste como test-redact-secrets.mts:

import assert from "node:assert/strict";
import { redactSecrets } from "./redact-secrets.mts";

const output = redactSecrets(
  "POST /sync Authorization: Bearer abc.def access_token=xyz&retry=1",
);

assert.equal(output.includes("abc.def"), false);
assert.equal(output.includes("access_token=xyz"), false);
assert.match(output, /Bearer \[REDACTED\]/);
assert.equal(redactSecrets("OS 742 retry=1"), "OS 742 retry=1");

As duas primeiras asserções são evidências negativas: valores sensíveis não permanecem. A terceira confirma que o log ainda informa a presença de uma credencial redigida. A quarta protege texto inofensivo contra alteração excessiva. Use somente tokens sintéticos. Com Node.js 22.18 ou posterior, execute node test-redact-secrets.mts; a execução nativa de TypeScript remove tipos, mas não faz typecheck. Depois provoque a falha removendo temporariamente uma substituição e confirme que a asserção correspondente falha.

Meça o aprendizado; não apenas o registre

Um novo controle precisa de hipótese e métrica. Para tokens em logs:

Problema: 3 incidentes em 60 dias.
Hipótese: redaction central + scanner no CI bloqueiam a classe conhecida.
Métrica: ocorrências detectadas antes do merge e incidentes após deploy.
Owner: plataforma.
Revisão: 30 e 90 dias.
Remoção/alteração: substituir padrões quando logging estruturado eliminar texto livre.

Se a recorrência não cair, investigue cobertura, novos formatos e pontos que ignoram o logger central. Não acrescente automaticamente mais parágrafos a AGENTS.md.

Dívida de instruções e limpeza

Regras acumuladas podem se contradizer: “sempre execute toda a suíte” e “nunca execute comandos demorados”, por exemplo. Revise periodicamente instruções, skills, hooks e ADRs. Remova duplicatas, limite o escopo pelo diretório e transfira regras determinísticas para automação.

Uma instrução permanente deve ser estável e quase sempre relevante. Uma skill serve a procedimento repetível sob demanda. Um subagente serve a trabalho focado com contexto isolado. CI serve a regra executável. Escolher errado aumenta ruído e reduz a chance de o modelo perceber o que realmente importa.

Falhas comuns e diagnóstico

Sintoma	Causa	Próxima ação
mesmo bug retorna	correção local sem controle durável	classificar a falha e criar teste/policy apropriado
AGENTS.md cresce sem limite	todo aprendizado virou instrução	mover procedimentos para skills e regras para CI
revisão discute gosto	achado sem critério e impacto	reescrever com reprodução e consequência
dois revisores concordam no erro	contexto e critérios não independentes	separar papéis e voltar à fonte/spec
scanner gera alertas ignorados	falsos positivos e owner ausente	calibrar, priorizar e atribuir responsável
ADR nunca é consultado	decisões triviais ou índice ruim	reservar ADR para escolhas duráveis e ligar ao código/spec

Segurança e respeito às pessoas

Revise o artefato, não a pessoa. IA não deve fabricar certeza nem diluir responsabilidade. Preserve privacidade em diffs, traces, prompts e exemplos de incidente. Antes de enviar um achado a serviço externo, confirme autorização e política de dados.

Achados de segurança precisam de canal e divulgação proporcionais. Não exponha segredo novamente no comentário de revisão; registre referência redigida e siga o processo de resposta.

Antes e agora

Antes, “peça ao mesmo chat para conferir” era tratado como revisão suficiente. Hoje, auto-revisão continua útil, mas especificação, testes, contexto separado, automação e aprovação humana aumentam independência.

A mudança mais importante não é ter mais agentes. É compor um harness que conserva evidência, limita autoridade e transforma falhas recorrentes no controle correto.

Exercício guiado

1. escolha uma mudança concluída;
2. faça o passe de especificação e registre três perguntas;
3. faça o passe de engenharia sem reler seus comentários anteriores;
4. escreva um achado com reprodução, impacto e evidência esperada;
5. escolha uma falha recorrente e encaminhe ao controle adequado;
6. defina owner, métrica e data de revisão;
7. execute o controle falhando antes da correção e passando depois.

O aceite exige dois relatórios separados, decisão do owner e evidência de que o novo controle detecta a classe de falha.

Desafio independente

Revise o ticket T-014 usando a spec e o pacote de evidência, sem consultar a conversa que produziu o código. Classifique os achados. Escolha um que possa repetir e implemente o aprendizado durável apropriado. Justifique por que ele pertence a teste, instrução, skill, CI, ADR, policy ou arquitetura.

O desafio falha se a solução for apenas “adicione mais atenção ao prompt”.

Conclusão

Você aprendeu a revisar com duas lentes, priorizar achados acionáveis e separar autoavaliação de revisão independente. Depois transformou uma falha recorrente no artefato que realmente a controla e definiu como medir seu efeito. Assim, a próxima execução não depende de uma conversa maior: ela recebe testes, políticas, instruções e arquitetura melhores.

Fontes

• Google — What to look for in a code review
• NIST — Secure Software Development Framework, SP 800-218
• OpenAI — Codex
• Node.js — TypeScript
• Node.js — Assert