Quando um agente de IA escreve parte do código, o diff registra o resultado, mas não preserva sozinho o motivo da escolha. Um registro de decisão de engenharia deve guardar o problema, as alternativas, a evidência que foi conferida, a pessoa que aceitou a decisão e o que faria a equipe reabrir o assunto.

Isso não significa salvar a transcrição inteira da conversa com o agente. Significa transformar uma decisão durável em um documento curto, versionado e pesquisável. O AGENTS.md enxuto para agentes de código continua sendo o lugar para instruções estáveis. O registro de decisões guarda a história do porquê.

Fluxo mostra uma pergunta passando por proposta de agente, verificação humana, registro de decisão e condição para reabrir a escolha.

Resposta curta

  • Registre decisões que mudam estrutura, qualidade, operação ou uma fronteira difícil de reverter.
  • Separe proposta do agente, evidência verificada e decisão humana aceita.
  • Inclua alternativas rejeitadas, trade-offs, confiança e condição para reabrir o registro.
  • Guarde o arquivo no repositório e substitua decisões aceitas com um novo registro ligado ao anterior.
  • Use CI para checar presença e formato, não para declarar que o julgamento técnico está correto.

Por que um diff não substitui um registro de decisão?

O diff explica quais linhas mudaram. Ele não explica por que a equipe escolheu uma fila em vez de uma chamada síncrona, por que aceitou uma consistência mais fraca ou por que rejeitou uma sugestão do agente. Depois de algumas sessões, o código mantém a escolha, mas o raciocínio pode ter desaparecido do contexto disponível.

A documentação da Microsoft define um architecture decision record como o registro de como e por que um sistema chegou à sua forma atual. Ela recomenda incluir contexto, alternativas, justificativa, consequências, nível de confiança e status, além de registrar mudanças em um novo documento que substitua o anterior (Microsoft, guia de ADR). O artigo é sobre decisões arquiteturais em geral. A participação de um agente exige alguns campos extras para evitar que uma sugestão pareça conhecimento verificado.

Discussões recentes de praticantes descrevem o mesmo problema em linguagem mais direta: decisões somem entre sessões longas, compactações e agentes diferentes. Em uma discussão no r/ClaudeCode, participantes mencionam um DECISIONS.md curto, o motivo da rejeição e uma instrução para consultar o arquivo. Isso é um sinal de linguagem e de dor recorrente, não uma prova de que um formato específico melhora métricas de engenharia.

Quais decisões merecem um registro?

Não transforme cada escolha de sintaxe em uma ADR. Registre o que muda o comportamento do sistema ou o trabalho de quem vier depois. Um bom filtro é perguntar se outra pessoa poderia tomar a decisão oposta sem entender um risco que já foi discutido.

Registre quando a escolha... Exemplo com agente Evidência que cabe no registro
muda a estrutura do sistema separa o processamento em worker e fila diagrama, teste de contrato ou restrição operacional
altera um atributo de qualidade aceita consistência eventual para reduzir acoplamento requisito, medição disponível ou limite declarado
é difícil de reverter escolhe um formato de evento ou um banco alternativas, custo de migração e dependências
fixa uma fronteira do agente permite leitura, mas exige aprovação antes de escrever política, teste de permissão e responsável
rejeita uma hipótese importante não usa uma tool ou um modelo para certa tarefa motivo da rejeição e condição que mudaria a decisão

O Engineering Playbook da Microsoft recomenda um log porque decisões e consequências se perdem dentro de documentos grandes. Ele também diferencia uma decisão rápida de um estudo mais elaborado. O registro pode ser curto. O importante é que o contexto e a consequência não dependam da memória de uma sessão.

Não confunda esse histórico com o registro de execução. A observabilidade de agentes de código no CI responde o que aconteceu durante uma execução. A decisão responde por que o sistema deve seguir aquele caminho.

Quais campos acrescentar quando um agente participa?

Uma ADR tradicional já precisa de problema, opções, decisão, trade-offs e status. Para um fluxo com agente, acrescente a proveniência da proposta e o estado da evidência. A pergunta não é “qual modelo escreveu a linha?”, mas “o que foi sugerido, o que foi conferido e quem aceitou o risco?”.

Este template é um ponto de partida. Use docs/decisions/ ou o diretório equivalente que o repositório já possui:

---
status: accepted
date: 2026-11-15
owner: nome-ou-time
confidence: medium
validUntil: 2027-11-15
supersedes: null
---

# Usar chave idempotente na entrada de pedidos

## Context
O worker pode receber a mesma mensagem depois de um timeout.

## Options considered
- Aceitar a última gravação e reconciliar depois.
- Rejeitar duplicatas com uma chave idempotente.

## Decision
Usaremos a chave idempotente antes da mutação.

## Evidence
- Teste: `npm test -- idempotency`
- Ainda não há medição de carga distribuída.

## AI participation
O agente propôs as duas opções e gerou um primeiro teste.
Uma pessoa revisou o caso de retry, executou a suíte e aceitou o trade-off.

## Consequences
Ganhamos uma barreira contra duplicatas, mas precisamos expirar chaves.

## Reopen when
O contrato de entrega mudar ou a política de expiração causar colisões.

Os campos mais importantes são estes:

  • Contexto: problema, restrições e o que já era verdade quando a escolha foi feita.
  • Opções consideradas: inclusive a alternativa rejeitada e o motivo. Isso evita que uma nova sessão recomende o mesmo caminho sem saber por que ele falhou.
  • Decisão e consequências: o que será feito e qual custo foi aceito.
  • Evidence: comandos, testes, links, medições ou a declaração explícita de que algo ainda não foi verificado.
  • AI participation: proposta, busca, código ou teste produzido pelo agente. Não confunda participação com aprovação.
  • Owner, confidence e validUntil: pessoa ou time responsável, confiança atual e uma data ou evento que force revisão quando fizer sentido.
  • Reopen when: a mudança observável que faria a equipe reavaliar o registro.

O guia de ADR da Microsoft recomenda registrar confiança mesmo quando ela é baixa. Um position paper recente sobre engenharia assistida por IA defende separar status epistêmico e validade temporal. É uma proposta de pesquisa, não um padrão adotado nem uma validação do template acima. Aqui, a ideia útil é simples: não apresente uma hipótese não testada como fato permanente.

Como separar proposta do agente e decisão humana?

Use três estados diferentes no texto e no fluxo de revisão:

  1. Proposta: o agente resumiu opções, sugeriu uma implementação ou produziu uma fixture.
  2. Verificação: uma pessoa conferiu o contrato, executou os testes relevantes e verificou se a evidência responde à pergunta.
  3. Decisão: uma pessoa responsável aceitou o resultado, o trade-off e os limites.

Um agente pode preencher um rascunho. Ele não deve se autoatribuir confiança nem transformar um teste que passou em aprovação arquitetural. Se a verificação não foi executada, escreva isso. Se apenas uma parte do cenário foi coberta, nomeie a lacuna.

Essa separação também ajuda no portfólio. O README de portfólio que prova decisões de engenharia apresenta uma escolha ao leitor. O registro no repositório preserva o processo para a equipe e para as próximas sessões. São documentos relacionados, mas não têm o mesmo leitor nem a mesma função.

O portfólio de software engineer com IA pode apontar para esses registros como evidência de julgamento, mas a página pública não substitui a documentação operacional do projeto.

Como guardar e atualizar sem criar burocracia?

Comece com uma pasta versionada e uma regra curta. Um arquivo por decisão torna a busca e o link mais precisos:

docs/decisions/
  0001-use-idempotency-key.md
  0002-run-agent-read-only-by-default.md

O nome pode variar. O que importa é que o arquivo apareça no mesmo pull request que introduz ou altera a decisão, quando isso for possível. Faça link para a ADR no README, na documentação da área ou no comentário do código que depende da escolha. Não cole o documento inteiro em AGENTS.md: instrução de trabalho e histórico de decisão envelhecem de formas diferentes.

Depois que um registro foi aceito, trate-o como append-only. Se o contexto mudar, crie outro arquivo com status: superseded, ligue os dois e explique o que mudou. Editar silenciosamente a decisão antiga apaga justamente a história que você queria preservar. Esse padrão é recomendado na documentação da Microsoft e também aparece no decision log do Engineering Playbook.

Não crie um registro para cada prompt. Um bom limite é uma decisão que muda a direção, a superfície de risco ou o contrato que outro agente precisa respeitar. Para o restante, um comentário no pull request ou uma nota de execução basta.

Como validar o formato no CI?

CI pode verificar se o registro é legível e completo. Não consegue provar que a escolha é boa. O script abaixo é ilustrativo, mas executável com Node.js sem dependências. Ele checa títulos obrigatórios em um arquivo Markdown.

Salve-o como scripts/check-decision-record.mjs e rode node scripts/check-decision-record.mjs docs/decisions/0001-use-idempotency-key.md:

import { readFileSync } from "node:fs";

const file = process.argv[2];
if (!file) {
  console.error("Usage: node scripts/check-decision-record.mjs <file>");
  process.exit(2);
}

const text = readFileSync(file, "utf8");
const required = [
  "Context",
  "Options considered",
  "Decision",
  "Evidence",
  "AI participation",
  "Consequences",
  "Reopen when",
];
const missing = required.filter(
  (heading) => !new RegExp(`^## ${heading}$`, "im").test(text),
);

if (missing.length > 0) {
  console.error(`Missing sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`Decision record is structurally complete: ${file}`);

Pré-requisitos: Node.js em uma versão que aceite módulos ES e um arquivo Markdown com os títulos do template. Para verificar, rode o comando com o exemplo completo e depois remova uma seção para confirmar que o CI falha. Se o repositório usa YAML frontmatter estrito, acrescente um parser e checks para status, owner e confidence; o exemplo não valida YAML, conteúdo factual, qualidade da evidência, links ou autorização humana.

O teste mais importante continua fora desse script: abra a decisão como alguém que não participou da conversa. Você consegue entender o problema, encontrar a alternativa rejeitada, repetir a verificação e saber quando a decisão deixa de valer? Se não, um check verde não resolve a lacuna.

Falhas comuns e limites

Registrar só o resultado. “Usamos fila” não explica a restrição, o custo ou a alternativa rejeitada. Volte ao contexto e à consequência.

Deixar o agente escrever a decisão final sozinho. Automação pode montar o rascunho e apontar evidências. A aceitação precisa ter uma pessoa ou time responsável.

Transformar confiança em nota decorativa. high sem teste ou argumento verificável não é prova. Ligue a confiança ao que foi observado e nomeie o que ainda é hipótese.

Colocar tudo em um arquivo de memória. Um log gigante fica difícil de consultar e misturar regras, decisões e tarefas cria conflitos. Separe instruções estáveis, decisões aceitas e notas temporárias.

Editar o passado para deixar a história bonita. Se a escolha mudou, marque a anterior como substituída e escreva a nova. A mudança de direção é parte do contexto.

Acreditar que o registro substitui testes. Documentação torna o raciocínio auditável. Não transforma uma hipótese em comportamento correto, não valida segurança e não mede carga por conta própria.

Fechamento

Um registro de decisão para código assistido por IA não é um diário do agente. É um artefato de responsabilidade técnica: torna visíveis o problema, as alternativas, a evidência, a participação da ferramenta, a decisão humana e o momento em que a escolha deve ser reaberta.

Comece com uma pasta docs/decisions/, um template curto e uma regra de substituição. Linke cada decisão ao código ou ao pull request que depende dela. Depois, se o volume justificar, valide a estrutura no CI. A parte que não deve ser automatizada é o julgamento sobre se a evidência realmente sustenta a escolha.

Como este artigo foi produzido

Samuel Fajreldines é o autor responsável por este artigo. A pesquisa comparou a documentação atual de ADR da Microsoft, um decision log de engenharia versionado, um position paper sobre validade de decisões e discussões públicas recentes sobre perda de contexto em coding agents. As discussões foram usadas para linguagem e falhas percebidas, não como prova técnica. O diagrama é uma SVG autoral e o validator foi verificado localmente com Node.js usando um registro fictício, sem medir um time real, chamar um modelo ou fazer um benchmark de produção. A assistência de IA apoiou descoberta, organização, redação, localização e revisão de consistência. O autor usa o RemoteCode como ferramenta de trabalho, mas ela não executou testes de produção nem forneceu experiência operacional.

Fontes consultadas