Como é um bom registro de atrito

Por que registros, e não memórias?

O atrito em uma única sessão é apenas ruído. O mesmo atrito ao longo de oito sessões é um padrão que sua equipe pode corrigir — mas somente se essas oito sessões tiverem gerado registros que vocês possam realmente analisar juntos: consistentes (mesmo esquema, para que sejam comparáveis) e confiáveis (observações baseadas em evidências, não em impressões).

Nenhuma das duas coisas ocorre por padrão. O momento em que surge o atrito é o momento em que se tem o máximo de informação sobre ele — a linha exata desatualizada no manual de operações, o parâmetro exato que o briefing deixou em aberto. Essa informação se perde rapidamente. O agente normaliza sua própria solução alternativa em poucas iterações e, ao final da sessão, o sinal desaparece, a menos que algo tenha sido registrado; o que quer que um subagente descubra “desaparece no momento em que retorna” (Hindsight, maio de 2026). Este capítulo trata do registro.

Como o atrito se torna perceptível

Antes que qualquer coisa possa ser registrada, ela precisa ser percebida. São quatro canais, e cada um deles capta coisas diferentes:

O agente percebe que está enfrentando dificuldades. Ciclos de repetição, retrocesso, releitura do mesmo arquivo ou nova consulta à mesma visualização analítica — uma suposição forçada por uma lacuna no briefing. As plataformas de produção convergiram essencialmente para esta lista de sinais comportamentais (Sinais de Fábrica, janeiro de 2026). O canal mais barato, com dois limites claros: ele é cego para coisas ausentes (um ciclo de tentativas é percebido; um documento que nunca existiu não produz nenhum sinal), e a autoobservação supera o autodiagnóstico — os modelos localizam mal seus próprios erros de agência, mesmo em rastros selecionados (~11%, TRAIL). Portanto, a tarefa durante a sessão é observar sintomas e citar evidências, mantendo o diagnóstico de forma flexível.

Um segundo agente revisa a transcrição. Um revisor novo percebe o que o agente responsável pela revisão inicial normalizou. É mais objetivo; exige uma segunda revisão e traz seus próprios erros de julgamento.

Um ser humano corrige o agente. Ainda é o sensor dominante: um estudo de produção de 8 semanas constatou que cerca de 70% das falhas silenciosas dos agentes foram detectadas inicialmente por uma pessoa que percebeu que algo estava errado — e não por testes unitários, verificações de integridade ou auditorias de governança (arXiv 2606.14589). Cada correção (um “não, eu quis dizer…” de um revisor, uma parte interessada reexplicando o briefing no meio de uma auditoria) marca exatamente onde o contexto divergiu da intenção, e o agente pode capturar isso no momento, sem nenhum custo adicional ao processo.

Telemetria. Taxas de erro de ferramentas, recusas de permissão, contagem de ciclos, durações prolongadas. Automática e imparcial, mas superficial: ela sabe que algo aconteceu, mas não por quê.

As configurações mais eficazes funcionam em conjunto: a telemetria indica onde procurar, uma análise posterior explica por quê e a correção humana resolve os problemas que nenhum sinal automático consegue detectar. Seja qual for a combinação que você utilize, o resultado final deve ser o mesmo: um recorde.

O que leva o agente a registrar isso?

Um agente não registrará um atrito que ninguém lhe tenha instruído a procurar. A maior parte do atrito não é registrada não porque não tenha sido percebido, mas porque nada fez com que o registro ocorresse. Quatro mecanismos, que diferem principalmente no que garante a ativação:

• Uma habilidade: um procedimento escrito e versionado que o agente executa ao final da sessão. Contém o esquema e as regras de honestidade, de modo que o que é acionado seja consistente: o mesmo procedimento funciona tanto em uma refatoração quanto em uma revisão de conta de publicidade. Ponto fraco: a invocação é probabilística; pode, silenciosamente, nunca ser acionada.
• Um gancho: o próprio harness aciona ou lembra (uma injeção no início da sessão, um acionador no fim da sessão). É determinístico (a única opção que não depende de ninguém se lembrar de nada), mas pouco preciso (ele também é acionado em sessões de dois minutos) e restrito à plataforma.
• Uma regra de convenção: uma instrução permanente no arquivo de contexto do escopo, ou em seu equivalente fora do código, uma etapa no procedimento operacional padrão (SOP) da equipe: “encerrar toda sessão substancial assistida por IA registrando os atritos”. Infraestrutura zero, mas depende inteiramente de o modelo respeitar uma regra entre muitas, e perde eficácia à medida que o arquivo cresce; o modo de falha identificado é o arquivo de memória que “deixou de ser lido” (nota de campo sobre antipadrões).
• Um comando: digitado por uma pessoa/retroao final de um branch de recurso ou de um turno de triagem. Deliberado e com tempo precisamente calculado; o ponto fraco é a memória humana.

Esses elementos compõem o sistema; organize-os em camadas. Um gatilho determinístico (um gancho ou uma etapa do SOP de fim de turno), uma carga útil procedural (a habilidade) e uma linha de convenção que define a prática como uma norma — escolha pelo menos um gatilho; dois são melhores. Até mesmo os fornecedores chegaram a essa conclusão: a orientação do Codex da OpenAI diz “quando o Codex cometer o mesmo erro duas vezes, peça a ele uma análise retrospectiva e atualize o AGENTS.md” (melhores práticas).

A anatomia de uma boa introdução

Um registro é o contrato entre a sessão que detectou o atrito e tudo o que vem a seguir — a qualidade da síntese é limitada pela qualidade do registro. Quatro componentes essenciais:

1. Um momento comprovado por evidências, com seu custo. O que aconteceu, quando e a consequência observável, com detalhes suficientes para que alguém que não estivesse presente na sessão pudesse agir com base nisso. Custo significa trabalho refeito, tempo perdido, resultado incorreto; um registro sem custo não pode ser classificado posteriormente. O custo estimado pelo agente é aproximado: indique-o(est.) em vez de fingir precisão.

2. Exatamente um rótulo de causa raiz de um vocabulário fixo de dez rótulos. Vocabulários fixos podem ser rotulados de forma confiável (o MAST atingiu κ = 0,88 em 14 modos de falha; consulte arXiv 2503.13657); categorias de formato livre variam de pessoa para pessoa e deixam de ser agregadas. As dez:

• ambiguous-instruction: a solicitação deixou um parâmetro fundamental em aberto (público-alvo, escopo, definição, período) e nos obrigou a dar um palpite
• missing-context: um fato já conhecido pela equipe, mas que não foi compartilhado
• incorrect-context: as informações fornecidas estavam incorretas
• missing-documentation: falta um documento que deveria existir (não há README, especificação, manual de procedimentos nem procedimento operacional padrão)
• incorrect-documentation: existe um documento, mas ele está desatualizado ou contém erros, e foi utilizado como referência
• work-material-friction: o material em que se estava trabalhando tornava o trabalho lento ou propenso a erros: dívida técnica ou estrutura confusa no código; uma conta, um quadro, uma planilha ou um modelo desorganizado fora do código (sempre mencione o material específico)
• missing-access-or-tool: um conector, uma permissão ou uma ferramenta necessária não estava disponível
• agent-error: erro do próprio agente (suposição incorreta, conhecimento desatualizado, um bug que ele mesmo causou)
• changed-requirements: a solicitação mudou no meio da sessão e o trabalho teve que ser refeito
• environment-friction: falhas nas ferramentas, tempo limite esgotado, problemas com a sandbox ou com a plataforma

Um rótulo por constatação mantém as distribuições precisas: escolha o que melhor se encaixa, observe as contradições nas evidências, nunca invente um rótulo no meio da análise. Três regras de delimitação realizam a maior parte do trabalho de desambiguação. O teste de conhecimento do agente: o fato era localizável em qualquer lugar onde o agente pudesse razoavelmente procurar? Não encontrado em nenhum lugar onde deveria estar → missing-documentation; fornecido apenas posteriormente, por uma pessoa → missing-context. O erro do agente é o residual: use-o apenas quando as informações fornecidas foram adequadas e o agente ainda assim cometeu um erro; se o erro for atribuível a uma informação incorreta, rotule a informação. E ambiguidade versus mudança: se o esclarecimento revelou o que sempre se quis dizer, era ambiguous-instruction; se o objetivo realmente mudou, é changed-requirements.

3. Uma correção do tamanho de um ticket, indicando sua “altitude”. A “altitude” é o nível ao qual a correção se destina: memória, habilidade, ambiente, documentação, o próprio material, processo ou upstream. Um registro de atrito sem uma correção anexada é uma reclamação.

Aqui está uma anotação completa de uma sessão que não envolveu programação, uma revisão mensal da conta de publicidade:

- **[missing-context]** The brief didn't say the French campaigns were deliberately
  paused for Q3; ~40 min (est.) auditing a "broken" campaign that was fine.
  → Fix (altitude: process): add campaign-status flags to the monthly brief template

Um momento, um custo identificado com um(est.)marcador, uma etiqueta, uma solução que alguém poderia adotar na próxima semana. Compare com a versão inutilizável da mesma observação: “o briefing era confuso”: sem momento, sem custo, sem próximo passo. A imprecisão é, por si só, uma forma de falha.

4. Permissão para não dizer nada. “Nada digno de nota” é uma resposta válida e útil; um registro repleto de conclusões inventadas acaba ofuscando as reais.

Mais um ponto de design: a gravação deve ser sem restrições — um agente que precise de permissão para gravar gera subnotificação de problemas. Deixe que ele grave livremente, e que o feedback humano sirva como correção a posteriori: um sinal complementar da pessoa que também participou da sessão, e não um ponto de verificação pelo qual o ciclo fique aguardando.

As regras de “never-log”

Os registros sobrevivem às sessões: eles são gravados, compartilhados e agregados. Algumas coisas nunca são incluídas:

• Segredos, credenciais, tokens ou chaves de API, sob qualquer forma, mesmo que parciais.
• Dados de clientes ou informações pessoais.
• Números comerciais ainda não divulgados ou dados confidenciais — descreva o efeito, não os dados.
• Acima de tudo, pessoas. Nunca um nome, uma função ou qualquer coisa que identifique quem causou uma lacuna. Descreva a lacuna e o que ela custou: “o briefing deixou o público em aberto”, e não “o briefing de X”. As anotações criticam contribuições e sistemas, não pessoas — a mesma disciplina seguida por uma boa retrospectiva, e o que torna o registro seguro para ser lido em conjunto.

É esperado que se faça uma crítica às entradas: briefings pouco claros, falta de contexto e requisitos apresentados tardiamente costumam ser os pontos onde se encontram as informações que dão margem a ações concretas. O agente deve fazer uma autocrítica com a mesma honestidade. Se não for possível descrever os atritos de um escopo sem recorrer a contexto confidencial, mantenha as entradas desse escopo privadas e compartilhe apenas o briefing agregado.

Onde fica o log

Um registro por escopo de revisão — o limite onde as correções são aplicadas. Para a maior parte do trabalho de desenvolvimento, esse escopo é o repositório: sua documentação, configuração e convenções estão alojadas no repositório, portanto, seu registro de atritos também. Fora do código, o escopo é a conta de anúncios, a caixa de entrada do suporte, o engajamento com o cliente; mantenha o registro na pasta de documentos desse espaço de trabalho. Um registro arquivado fora de seu escopo é aquele que o eventual responsável pela correção nunca encontrará; uma entrada gravada em um diretório temporário desaparece com o fim da sessão.

O que deve permanecer idêntico em todos os lugares não é o armazenamento, mas a estrutura: é o esquema, e não o armazenamento, que permite a agregação posterior dos registros. Essa é a perspectiva de equipe deste capítulo: registros comparáveis — entre pessoas, agentes, sessões e ferramentas — são o que torna possível, de fato, a agregação no nível da equipe. Adapte o armazenamento livremente; proteja o esquema.

O que vem a seguir

Uma pilha de bons registros é matéria-prima, não uma percepção. Os próximos capítulos dão continuidade a partir daqui: escolher a altitude de cada ponto de referência (a diferença entre uma anotação de memória e a refatoração para a qual o atrito continua apontando); sintetizar as entradas em um resumo de uma página que a equipe possa ler em conjunto; e a cerimônia em que as pessoas e o registro se encontram — a retrospectiva, com os registros do agente servindo como contribuição dos participantes. Esse ciclo é uma instância do Feedback Flywheel: reaproveitar os aprendizados nos artefatos que fornecem contexto (martinfowler.com). E a disciplina das entradas é a análise de erros, “a atividade mais importante nas avaliações” (Husain & Shankar, FAQ sobre avaliações), transferida para o momento mais econômico possível: enquanto a sessão que encontrou o atrito ainda está em andamento.

Tudo o que foi descrito acima funciona com um arquivo de texto e qualquer agente compatível. Se você preferir não criar o modelo por conta própria, a ai-session-retroskill gratuita implementa esse formato de entrada do início ao fim; o artigo de introdução rápida explica como instalá-la em cerca de dez minutos.

Próximo capítulo: Onde a correção deve ser aplicada? — o problema da altitude e a tabela de roteamento.