Quando a IA participa de um pull request que causa uma falha, o postmortem não deve terminar em “o modelo escreveu”. Essa frase identifica uma circunstância, mas não explica qual requisito ficou ambíguo, qual revisão não detectou o risco, qual teste faltou ou qual sinal chegou tarde.
Um postmortem útil reconstrói quatro coisas: a mudança que entrou, o contexto de revisão e entrega, o impacto em runtime e o controle que será alterado. Cada afirmação recebe uma evidência ou é marcada como inferência, hipótese ou desconhecido. Cada ação tem responsável, teste de aceitação e prazo. Essa estrutura complementa o registro de decisões de engenharia quando um agente escreve código, que serve para decisões tomadas antes ou durante a implementação.
Resposta curta
- Reconstitua a mudança a partir do commit, do PR e do rastro do agente, quando esse rastro existir.
- Separe revisão, CI, aprovação e deploy da explicação sobre o que aconteceu em runtime.
- Rotule cada afirmação como
observed,inferred,hypothesizedouunknown.- Troque “revisar melhor” por um controle verificável, com dono e critério de aceitação.
O postmortem precisa responder o quê?
Comece com uma frase de impacto que uma pessoa fora do contexto consiga verificar: o que mudou, qual comportamento foi observado, quem foi afetado e como a recuperação terminou. Não comece atribuindo intenção ao modelo ou ao autor humano.
Depois responda, nesta ordem:
- Qual requisito, decisão ou suposição a mudança deveria atender?
- O que foi produzido e quais ferramentas participaram?
- O que a revisão humana, a automação e a aprovação realmente verificaram?
- Qual foi o primeiro sinal observável em produção ou no ambiente de entrega?
- Que controle estava ausente, fraco ou aplicado tarde demais?
- Como saberemos que a ação corretiva funciona?
Essa ordem segue a ideia de uma análise sem caça ao culpado. O guia do Google SRE sobre cultura de postmortem recomenda identificar causas contribuintes sem acusar uma pessoa ou equipe. A orientação do GitHub para revisar código gerado por IA também coloca a experiência humana, os testes, a análise estática e a verificação do contexto junto da automação, não depois dela.
Monte três trilhas de evidência
Uma mudança assistida por IA deixa evidências em lugares diferentes. Não misture todos os eventos numa narrativa única antes de saber o que cada fonte prova.
| Trilha | Pergunta | Evidências possíveis | Limite |
|---|---|---|---|
| Mudança | O que entrou no repositório e de onde veio? | commit, diff, PR, instrução, arquivos alterados, trace do agente | Um trace pode mostrar uma chamada sem provar que ela foi a causa do defeito. |
| Revisão e entrega | O que foi revisado, testado e aprovado? | comentários, checks, artefatos de CI, aprovação, deploy, configuração | Um check verde prova o que ele executou, não tudo que o sistema precisava fazer. |
| Runtime | O que aconteceu depois da entrega? | log redigido, métrica, alerta, ticket, rollback, consulta de estado | Um horário próximo não prova causalidade sozinho. |
Se o seu harness registra traces, use-os como ponte entre geração, chamadas de ferramenta, handoffs e guardrails. A documentação de tracing do Agents SDK descreve traces e spans para esse tipo de evento e alerta que os dados capturados podem ser sensíveis. Guarde referências, hashes ou trechos redigidos no postmortem; não copie prompts, tokens, segredos ou uma transcrição inteira só porque ela existe.
Para cada fonte, registre o identificador e o que ela permite afirmar. ci-184 pode provar que a suíte executou em um commit específico. Ele não prova que uma regra de negócio ausente foi considerada.
Separe fato, inferência, hipótese e desconhecido
Use rótulos explícitos. Eles impedem que uma hipótese conveniente vire a causa oficial durante a revisão do texto.
| Rótulo | Significado | Exemplo de frase |
|---|---|---|
observed |
Há uma evidência direta e apontada. | “O alerta checkout-error-rate abriu às 14:07.” |
inferred |
A conclusão combina duas ou mais evidências, mas não é observação direta. | “A mudança provavelmente afetou o fluxo de checkout porque o erro apareceu após o deploy e só nesse caminho.” |
hypothesized |
Explicação plausível ainda sem teste suficiente. | “A ausência de um caso de moeda pode ter deixado a validação incompleta.” |
unknown |
A fonte necessária não existe, está redigida demais ou não permite concluir. | “Não sabemos qual instrução o agente recebeu nesta tentativa.” |
Um horário de CI, um comentário de revisão e um log de produção podem formar uma linha do tempo coerente. Ainda assim, escreva a diferença entre “aconteceu depois” e “causou”. Se a causa continua hypothesized, uma ação pode ser justamente criar um teste que a confirme ou descarte.
Transforme a linha do tempo em uma matriz
Uma tabela curta costuma ser mais auditável do que vários parágrafos. Use IDs estáveis para que uma afirmação possa apontar para mais de uma fonte.
14:02 C1 commit 8f2a abriu o PR [observed]
14:05 R1 dois checks de CI terminaram verdes [observed]
14:09 D1 deploy de 8f2a terminou [observed]
14:17 P1 erro de checkout subiu [observed]
14:31 A1 rollback para 7c1d terminou [observed]
Em seguida, escreva uma matriz de afirmações:
| ID | Afirmação | Status | Evidência | Próximo passo |
|---|---|---|---|---|
| C1 | O PR mudou a normalização de moeda. | observed |
diff 8f2a |
Nenhum, fato estabelecido. |
| C2 | O caso de moeda ausente não tinha teste. | inferred |
suíte ci-184, cobertura do módulo |
Adicionar teste de aceitação. |
| C3 | O agente recebeu uma instrução ambígua. | unknown |
trace redigido sem prompt | Melhorar retenção segura ou não afirmar. |
Essa matriz também ajuda a revisão humana a discordar de uma afirmação sem reabrir toda a narrativa. O handbook de postmortems da Atlassian descreve uma prática semelhante de combinar linha do tempo, causas e ações responsáveis. Use-o como referência de processo, não como prova de que todo incidente deve seguir um formulário fixo.
Valide o documento antes de publicar
O formato pode ter uma verificação pequena e determinística. A fixture abaixo não analisa o código do agente nem prova uma causa de produção. Ela só garante duas invariantes do documento: uma afirmação observada aponta para alguma evidência, e toda ação tem responsável e critério de aceitação.
import assert from "node:assert/strict";
const report = {
claims: [
{
id: "C1",
status: "observed",
evidence: ["diff-8f2a", "ci-184"],
},
{
id: "C2",
status: "hypothesized",
evidence: [],
},
],
actions: [
{
id: "A1",
control: "Add the missing currency case to the merge test",
owner: "checkout-team",
acceptance: "ci-201 fails before the fix and passes after it",
due: "2026-12-01",
},
],
};
function validatePostmortem(value) {
assert.ok(value.claims.length > 0, "postmortem needs claims");
for (const claim of value.claims) {
if (claim.status === "observed") {
assert.ok(claim.evidence.length > 0, `${claim.id} needs evidence`);
}
}
for (const action of value.actions) {
assert.ok(action.owner, `${action.id} needs an owner`);
assert.ok(action.acceptance, `${action.id} needs acceptance criteria`);
assert.ok(action.due, `${action.id} needs a due date`);
}
}
validatePostmortem(report);
console.log("postmortem evidence checks passed");
Salve como postmortem-check.mjs e execute com node postmortem-check.mjs. Em um sistema real, conecte essa validação ao repositório do postmortem ou ao processo de revisão. Não faça o script fingir que uma ação foi concluída só porque os campos existem.
Troque a causa por um controle
Uma boa ação corretiva muda o sistema que permitiu a falha. Exemplos:
| Controle perdido | Ação verificável |
|---|---|
| O requisito tinha uma lacuna | Adicionar um caso de aceitação que falha no comportamento antigo e passa no novo. |
| A revisão não tinha contexto operacional | Anexar ao PR um resumo redigido da mudança, do risco e dos checks executados. |
| O CI não cobria uma fronteira | Criar um teste de regressão e torná-lo obrigatório para o caminho afetado. |
| A permissão era ampla demais | Restringir a ferramenta ou o ambiente e verificar a política em CI. |
| O primeiro sinal veio tarde | Adicionar um alerta com limiar, responsável e teste de disparo. |
“Revisar com mais atenção” não tem critério de término. Um post sobre observabilidade de agentes de código no CI ajuda a pensar na trilha operacional que deve chegar ao PR, e o teste de aprovação humana para agentes cobre a verificação de uma barreira humana como comportamento testável.
O que não entra no documento
Não publique uma transcrição integral do agente, segredos, prompts privados, tokens, dados pessoais ou uma narrativa que atribua intenção sem evidência. Também não transforme uma discussão de comunidade em prova técnica. O postmortem deve preservar o que permite aprender e remover o que aumenta exposição sem melhorar a explicação.
Não prometa que a IA foi a causa apenas porque ela participou da mudança. Compare a especificação, o diff, os checks e o comportamento observado. Se a participação do agente não puder ser reconstruída com segurança, registre isso como unknown e corrija a observabilidade como uma ação separada.
Método e limites
Este texto foi escrito por Samuel Fajreldines como uma síntese de documentação pública de SRE, revisão de código gerado por IA, tracing de agentes e práticas de postmortem, combinada com a fixture local acima. A fixture foi executada com Node.js, mas não representa um incidente de produção, não é benchmark e não mede a eficácia de um modelo. A assistência de IA ajudou na organização da pesquisa e da redação; não executou um teste de produção nem substitui a responsabilidade do autor. A ferramenta do autor é o RemoteCode.
O resultado deve ser adaptado ao controle de acesso, retenção de logs e exigências de privacidade da sua organização. Se o rastro do agente contém dados sensíveis, a ausência de uma cópia no postmortem pode ser a decisão correta, desde que o repositório preserve uma referência segura e auditável.
Checklist final
- [ ] A linha do tempo aponta para commits, checks, deploys e sinais observáveis.
- [ ] Mudança, revisão e runtime estão em trilhas separadas.
- [ ] Cada afirmação está marcada como observada, inferida, hipotética ou desconhecida.
- [ ] A ação muda um controle, tem responsável, teste de aceitação e prazo.
- [ ] O documento não expõe segredos, dados pessoais ou uma transcrição desnecessária.
- [ ] A causa continua proporcional ao que as evidências permitem afirmar.