Contexto, ação, resultado e próxima decisão

Field Note

Terça-feira, 14h. Você pede para o Claude Code corrigir um teste que falha. Ele roda a suíte, lê o erro, abre dois arquivos, edita um, roda de novo. Falha diferente. Edita outro. Roda. Agora passa. Você comemora e vai tomar café. Na volta, olha o diff com calma: o teste passou porque a asserção foi trocada. O código continua quebrado. Cada passo fazia sentido isolado. O conjunto andou para o lado errado, e ninguém estava lendo o caminho.

Conceito

Na primeira lição vimos o loop agêntico: coletar contexto, agir, verificar, repetir. Aqui o foco é outro. Não é entender que o loop existe. É ler o loop enquanto ele roda e saber a hora de mexer no volante.

A doc oficial resume a mecânica numa frase: cada uso de ferramenta devolve informação que alimenta a próxima decisão. Isso tem uma consequência prática. Se um resultado vem errado ou ambíguo, a decisão seguinte herda o problema. Um teste mal lido vira uma edição desnecessária, que vira um novo erro, que vira mais uma edição. O loop é eficiente para os dois lados: converge rápido quando o sinal é bom e diverge rápido quando o sinal é ruim.

Para acompanhar, pense em quatro colunas para cada passo:

• Contexto: o que ele sabia ao decidir.
• Ação: qual ferramenta usou e com qual alvo.
• Resultado: o que voltou (saída de comando, conteúdo de arquivo, erro).
• Próxima decisão: o que mudou por causa desse resultado.

Onde ler o histórico. A tela principal mostra um resumo. Para ver o detalhe, Ctrl+O abre o transcript viewer, que mostra o uso de ferramentas e a execução com mais detalhe, incluindo o modelo usado em cada resposta. É ali que você vê qual comando rodou de fato e o que voltou, sem depender do resumo que o agente escreveu.

Como interromper e redirecionar. A doc descreve dois jeitos, e eles servem a situações diferentes:

1. Esc para tudo na hora. A chamada de ferramenta em andamento é cancelada, o trabalho feito até ali fica, e o Claude espera a sua próxima instrução. Use quando a direção já está errada.
2. Digitar e apertar Enter sem parar. A mensagem entra na fila. Se ele estiver rodando ferramentas, lê sua mensagem assim que essas chamadas terminam, dentro do mesmo turno, e ajusta antes do próximo passo. Use quando a direção está certa e só falta um detalhe ("o teste certo é o de integração, não o unitário").

Se quiser mandar o que está na fila sem esperar, Ctrl+Enter envia na hora (a doc indica versão 2.1.275 ou mais nova). Esc também envia a fila logo depois de interromper.

Intenção e execução são coisas diferentes. Você define o objetivo e o critério de pronto. O agente escolhe o caminho. Quando você começa a ditar comando por comando, vira operador de terminal com passos extras. Quando você nem define o critério de pronto, ele para quando "parece pronto", que é o único sinal disponível. A doc de boas práticas é direta: sem uma verificação que ele consiga rodar, você vira o loop de verificação.

Sinais de que o loop perdeu o objetivo:

• O mesmo comando rodando de novo com variações mínimas.
• Leitura de arquivos que não têm relação com a tarefa.
• Edição em teste, configuração de lint ou tipo para "fazer passar".
• Erro sendo silenciado em vez de resolvido.
• O escopo crescendo sem você pedir ("aproveitei e refatorei...").
• A explicação dele fica mais longa e menos concreta a cada passo.

Quando usar

• Toda tarefa com mais de três ou quatro passos. É onde o desvio acumula.
• Bug que exige reproduzir, ler log e testar hipótese.
• Primeiras semanas usando o Claude Code: ler o loop é como você calibra o quanto pode soltar a mão.
• Sempre que o resultado final surpreender. Volte ao transcript e ache o passo em que a decisão mudou.

Quando não usar

• Pergunta de uma resposta só sobre o código. Não tem loop para acompanhar.
• Tarefa curta com verificação automática forte (teste que cobre exatamente o caso). Deixe rodar e leia a evidência no fim.
• Quando você está microgerenciando por ansiedade. Se cada passo está fazendo sentido, interromper só custa tempo e contexto.

Faça agora

A prática é produzir um Diário de um loop com pelo menos cinco decisões.

1. Escolha uma tarefa pequena e real que envolva rodar algo: um teste falhando, um lint com erro, um script que não executa. Trabalhe numa branch separada.
2. Abra a sessão e mande um pedido com objetivo e critério de pronto:

O teste X está falhando. Descubra a causa e corrija o código, não o teste. Pronto quando a suíte passar sem alterar asserções. Ao final, liste os comandos que rodou e o resultado de cada um.

3. Enquanto ele trabalha, não interrompa. Só observe.
4. Ao terminar, abra o transcript com Ctrl+O e reconstrua a sequência. Para cada passo, preencha contexto, ação, resultado e próxima decisão.
5. Marque com um asterisco os passos em que o resultado mudou a direção. São esses que mostram o loop funcionando.
6. Marque com um X qualquer passo que você teria interrompido, e escreva por quê.
7. Rode a mesma tarefa de novo (ou outra parecida) e, desta vez, intervenha uma vez com mensagem na fila e, se preciso, uma vez com Esc. Anote o efeito de cada intervenção.

Armadilhas

• Ler só o resumo final. O resumo é a versão do agente. O transcript é o que aconteceu.
• Interromper cedo demais. Ele lê três arquivos antes de agir porque precisa. Parar no segundo só tira o contexto que ele estava montando.
• Corrigir em looping. A doc recomenda: se você corrigiu mais de duas vezes o mesmo ponto na mesma sessão, o contexto está poluído com tentativas que falharam. /clear e um pedido melhor, já com o que você aprendeu, quase sempre ganham.
• Pedir sem critério de pronto. Sem um "pronto quando", o loop para no primeiro resultado plausível.
• Achar que fila e Esc são a mesma coisa. Fila ajusta sem parar. Esc para. Escolha pelo tamanho do desvio.

Material para levar

Diário de um loop:

Tarefa:
Critério de pronto:
Branch:

Passo | Contexto            | Ação (ferramenta e alvo) | Resultado          | Próxima decisão
1     |                     |                          |                    |
2     |                     |                          |                    |
3     |                     |                          |                    |
4     |                     |                          |                    |
5     |                     |                          |                    |

Passos que mudaram a direção (*):
Passos que eu interromperia (X) e por quê:
Intervenções feitas (fila ou Esc) e efeito:
O loop terminou porque: passou na verificação / parecia pronto / eu parei

Sinais de desvio, para colar ao lado do terminal:

Mesmo comando repetido          → pare e peça diagnóstico, não nova tentativa
Arquivo sem relação sendo lido  → reescreva o escopo
Teste ou lint sendo editado     → Esc, exija correção no código
Erro sendo silenciado           → peça a causa raiz
Duas correções sem efeito       → /clear e pedido novo