Registro de solicitações do Claude Code

Comigo isso já aconteceu mais de uma vez: à noite eu e a equipe testamos várias versões de um bloco, e de manhã alguém pergunta por que o título ficou mais curto. Na conversa há dezenas de mensagens, na memória fica algo como "acho que o fundo era claro", e a decisão exata se dilui entre as alterações.

Nesses momentos, quem salva é o requests.log. É um rastro externo curto do trabalho, que dá para abrir em qualquer editor e ler de cima para baixo. Eu o valorizo não pela quantidade de linhas, mas pela possibilidade de ligar uma solicitação ao que realmente ficou decidido.

Para que serve um rastro externo

Ao longo dos anos, me acostumei a separar quatro coisas: a solicitação, a decisão, a conversa e a versão salva do arquivo. Elas respondem a perguntas diferentes, embora durante uma mesma sessão se misturem facilmente numa história confusa.

O log funciona como um índice: leva de volta ao momento certo e às palavras exatas. Ele não recupera o código em si. Se precisar ver a versão salva da página, consulte os arquivos e o histórico de versões do projeto.

No esquema fica bem visível uma diferença que importa na hora de analisar o log. A cadeia de cima mostra o andamento do trabalho, a de baixo é o que fica registrado no log. A linha automática surge antes do resultado; a anotação de decisão aparece só depois da revisão. Uma não substitui a outra.

Do que é feito um registro útil

Vou mostrar com três variantes de registro. Em projetos reais já encontrei cada uma delas.

pronto

Essa linha é quase inútil: não dá para saber quem fez o quê, quando, nem a qual tarefa esse "pronto" se refere.

Usuário: Deixe o título do cartão mais curto...
Claude: Certo, primeiro vou olhar o componente...
Usuário: E diminua o espaçamento...
Claude: Corrigido...

E aqui já tem informação demais para uma busca rápida. O fluxo completo é bom no histórico da conversa, mas um log separado vira rápido uma cópia incômoda dele. Já tentei fazer assim e depois eu mesmo perdia tempo rolando a tela.

2026-09-08T14:32:11+03:00 | prompt_submitted | actor=user | ref=card-header | text="Encurte o título do cartão para uma linha só"
2026-09-08T14:41:06+03:00 | decision_recorded | actor=user | ref=card-header | text="Título curto aceito, tamanho 24 px"

A terceira variante é a de que mais gosto: nela ficam um fato curto, a hora com fuso horário, o autor e a etiqueta ref, que liga as linhas. Os nomes dos campos aqui foram inventados para um projeto didático. Esse é o formato do nosso arquivo, não um esquema obrigatório do Claude Code. Nesta análise, as etiquetas ref foram adicionadas manualmente às linhas relacionadas. O hook não adivinha a qual bloco a solicitação se refere: o evento básico UserPromptSubmit não traz esse tipo de etiqueta semântica. Se não houver campo de vínculo, ainda dá para buscar no seu log pela frase exata.

O que se sabia no momento do registro

A linha prompt_submitted diz exatamente uma coisa: chegou à sessão aquela solicitação, e o hook a registrou. Normalmente é o texto do(a) senhor(a), mas nem sempre. O UserPromptSubmit dispara também na próxima volta do /loop, no relatório de um subagente em segundo plano e numa mensagem vinda de outra sessão, então actor=user no nosso formato é uma suposição do exemplo didático. Dela não decorre que o Claude Code alterou a página, que a revisão passou ou que o resultado agradou a todos.

Vale registrar o resultado depois que ele já for conhecido. No nosso exemplo isso é uma anotação separada, feita após a revisão da página. Se no seu formato existem campos result ou error, preencha-os com fatos observados, não com uma suposição sobre o desfecho futuro da tarefa.

Onde anotar a decisão tomada

Uma decisão aparece só quando alguém a registra explicitamente. No exemplo acima, a linha foi adicionada pelo usuário depois de revisar a página. O autor fica em actor, e o vínculo com a solicitação é guardado por ref=card-header.

A anotação pode ser manual, e não tem problema nisso. O registro automático guarda o que foi enviado, e uma pessoa confirma o sentido do resultado. Numa linha "pronto" sem autor nem vínculo, melhor não confiar.

Lendo o registro de solicitações

Vamos analisar um log pequeno de cinco linhas. É justamente com fragmentos curtos assim que costumo começar quando preciso reconstruir o caminho de uma decisão.

2026-09-08T14:32:11+03:00 | prompt_submitted | actor=user | ref=card-header | text="Encurte o título do cartão para uma linha só"
2026-09-08T14:36:20+03:00 | prompt_submitted | actor=user | ref=card-header | text="Mostre duas variantes: 24 px e 28 px"
2026-09-08T14:41:06+03:00 | decision_recorded | actor=user | ref=card-header | text="Título curto aceito, tamanho 24 px"
2026-09-08T15:03:44+03:00 | prompt_submitted | actor=user | ref=card-shadow | text="Deixe a sombra do cartão mais suave"
2026-09-08T15:08:17+03:00 | prompt_submitted | actor=user | ref=card-header | text="Tente uma cor mais escura para o título"

Imagine que o(a) senhor(a) precisa encontrar a última decisão tomada sobre o formato do título. Comece buscando por card-header no editor. Vão aparecer quatro linhas. A última traz um novo pedido sobre a cor, mas não uma decisão. Por isso a conclusão se apoia na linha das 14:41:06: título curto aceito, com tamanho de 24 px.

Minha rotina de leitura é simples:

1. Primeiro formulo a pergunta: procuro uma solicitação, uma decisão ou um erro observado.
2. Encontro a etiqueta comum, o nome do componente ou a frase exata.
3. Fico só com os registros do tipo que preciso e os leio em ordem cronológica.
4. Aponto as linhas que confirmam a conclusão. Todo o resto, com honestidade, deixo como desconhecido.

Essa análise dá para fazer até sem rodar o Claude Code. É um hábito útil: primeiro conferir a conclusão com o arquivo por conta própria, e só depois delegar o mesmo trabalho ao agente.

Quando não há decisão no log

Agora vamos tirar a linha das 14:41:06. Ficam o pedido para mostrar dois tamanhos e um pedido posterior para mudar a cor. Qual tamanho foi aceito? O log não responde.

Nesses casos dá muita vontade de escolher 24 px, porque é a primeira variante proposta. Melhor não. A solicitação mostra a intenção de testar variantes, não o resultado da escolha. A única conclusão honesta aqui é esta: a decisão tomada sobre o tamanho não está registrada no log.

A bifurcação não depende da ordem dos pedidos, mas do tipo de registro encontrado. Há uma anotação explícita de decisão - a conclusão pode ser confirmada. Sobraram só solicitações - registramos o desconhecido e não preenchemos a lacuna com suposição. Essa contenção, no fim, economiza bastante tempo.

O que deixar fora do log

Não tento transformar um log útil num depósito de tudo. O que vai em cada registro deve ser escolhido pensando na pergunta que depois precisará ser respondida. Para buscar decisões, em geral bastam a hora, o tipo de evento, o autor, a etiqueta de vínculo e um texto curto.

• Não copie chaves, tokens, o conteúdo do .env nem dados pessoais.
• Não grave por inteiro as respostas de serviços externos se só precisar do status ou do identificador da operação.
• Deixe o prompt completo só onde isso realmente for necessário. Neste artigo ele está completo apenas porque o exemplo é fictício e curto.
• Verifique de vez em quando o tamanho do arquivo e a utilidade dos registros antigos. Não existe um prazo de retenção único para todos os projetos.

Cortar a linha em cem caracteres melhora a legibilidade, mas não remove segredos automaticamente. Um token curto cabe tranquilamente nos primeiros cem caracteres. Primeiro decida quais dados é aceitável registrar. É por essa regra que vale a pena começar, não pelo tamanho da linha.

Como analisar o log junto com o Claude Code

O Claude Code monta bem uma sequência temporal e encontra rápido as linhas relacionadas. Mas para isso ele precisa ler o arquivo de forma explícita: o requests.log existir no projeto não significa, por si só, que o conteúdo dele já está no contexto.

Dê ao agente uma tarefa concreta:

Leia o requests.log. Encontre a última decisão explicitamente aceita
sobre o tamanho do título do cartão (card-header). Indique os registros em que você se apoia.
Se no log houver só um pedido, diga isso claramente.
Liste à parte o que permaneceu desconhecido.

Uma boa resposta separa os fatos da conclusão: cita a hora, o tipo de evento e o texto da decisão, e depois lista as questões sem confirmação. Confira essas referências com as linhas originais. O erro fica especialmente visível quando o agente chama o último pedido de "variante aceita".

Para este log didático, a resposta será esta: a decisão sobre o tamanho é confirmada pelo registro 2026-09-08T14:41:06+03:00; depois apareceu um pedido sobre uma cor mais escura, mas a decisão aceita sobre a cor é desconhecida. É exatamente esse tipo de resposta que considero confiável: ela não promete mais do que existe no arquivo.

• O hook guarda a solicitação antes de ela ser processada, por isso esse registro não confirma o resultado.
• Uma anotação separada liga a decisão tomada à solicitação pela hora ou pela etiqueta.
• A busca começa com uma pergunta concreta e termina com uma referência às linhas originais.
• Se não há confirmação, o log deixa uma lacuna. Não é para preenchê-la com suposição.

Assim o requests.log continua sendo um pequeno rastro de trabalho: ajuda a encontrar a virada certa da discussão, mas não finge ser nem uma cópia de segurança do projeto, nem prova de que a tarefa está pronta. Quando o log é montado com honestidade, dá vontade mesmo de voltar a ele.