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ê.
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:
- Proposta: o agente resumiu opções, sugeriu uma implementação ou produziu uma fixture.
- Verificação: uma pessoa conferiu o contrato, executou os testes relevantes e verificou se a evidência responde à pergunta.
- 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
- Microsoft Learn, “Maintain an architecture decision record (ADR)”, consultado em 15/11/2026.
- Microsoft Engineering Playbook, “Design Decision Log”, consultado em 15/11/2026.
- Sankalp Gilda e Shlok Gilda, “AI-Assisted Engineering Should Track the Epistemic Status and Temporal Validity of Architectural Decisions”, position paper, consultado em 15/11/2026.