Contexto que ajuda sem despejar o repositório

Field Note

Quarta-feira, 10h. Duas pessoas pedem a mesma coisa ao Claude Code. A primeira escreve "arruma o bug do login". A segunda cola o arquivo de autenticação inteiro, o log de 4 mil linhas da última madrugada, a conversa do Slack sobre o incidente e o README do projeto. A primeira recebe uma correção para um bug que não era o dela. A segunda recebe uma resposta lenta, cara e genérica, porque o problema estava enterrado embaixo de tudo que ela colou. As duas deram contexto. Nenhuma deu o contexto certo.

Conceito

Contexto bom não é muito contexto. É o mínimo que impede o agente de adivinhar o que ele não consegue descobrir sozinho, e nada além disso.

A doc oficial parte de uma restrição: a janela de contexto enche rápido e o desempenho cai conforme ela enche. Cada mensagem, arquivo lido e saída de comando ocupa espaço. Então o trabalho é separar duas categorias:

• O que só você sabe: o objetivo, o que está fora do escopo, as restrições do negócio, o que conta como pronto, o sintoma que o usuário relatou.
• O que ele consegue buscar: estrutura de pastas, conteúdo de arquivo, histórico do git, saída de teste. Isso você aponta, não cola.

A doc de boas práticas mostra quatro movimentos que transformam um pedido vago num pedido útil. Adaptados:

1. Delimite a tarefa. Qual arquivo, qual cenário, qual preferência de teste. "Escreva um teste para foo.py cobrindo o caso em que o usuário está deslogado. Evite mocks." em vez de "adicione testes para foo.py".
2. Aponte a fonte. Diga onde está a resposta. "Olhe o histórico do git de ExecutionFactory e resuma como a API chegou nesse formato" em vez de "por que essa API é estranha?".
3. Referencie um padrão existente. "Veja como os widgets da home estão implementados. HotDogWidget.php é um bom exemplo. Siga o mesmo padrão." O agente copia convenção muito melhor do que adivinha.
4. Descreva o sintoma. O que acontece, onde provavelmente está, e como fica quando estiver resolvido. "Login falha depois que a sessão expira. Veja o fluxo em src/auth/, principalmente o refresh de token. Escreva um teste que reproduza o problema e depois corrija."

Ferramentas para apontar em vez de colar:

• @ para arquivos e pastas. Digitar @ abre um menu de caminhos. Referenciar um arquivo inclui o conteúdo completo dele na conversa. Referenciar uma pasta mostra a listagem, não o conteúdo. A doc avisa um detalhe: mencionar um arquivo com @ também traz o CLAUDE.md da pasta dele e das pastas acima.
• Imagens. Arraste ou cole um print de erro ou de tela. No terminal, Ctrl+V cola (no Windows e WSL, Alt+V).
• Pipe para dados grandes. Em vez de colar um log, filtre antes e mande pelo terminal: tail -n 200 erro.log | claude -p "explique este erro".
• Deixar ele buscar. Muitas vezes basta dizer "use o gh para ler a issue 123" ou "rode o teste e leia a saída".

E o pedido vago? Tem lugar. A própria doc diz que perguntas abertas como "o que você melhoraria neste arquivo?" ajudam a descobrir coisas que você não pensaria em perguntar. Vago serve para explorar. Para executar, não.

Para tarefas maiores, a doc sugere inverter: você escreve o mínimo e pede que o Claude te entreviste com a ferramenta AskUserQuestion sobre implementação, casos de borda e trade-offs, até sair um SPEC.md. Isso conversa com a lição de planejamento, mais à frente.

Quando usar

• Qualquer pedido que vai gerar edição. Critério de pronto é obrigatório.
• Bug relatado por outra pessoa: o sintoma e o passo para reproduzir são contexto que só existe fora do código.
• Projeto com convenções fortes: apontar um arquivo de exemplo economiza três rodadas de correção.
• Quando a resposta anterior veio genérica. Quase sempre faltou fonte ou restrição.

Quando não usar

• Exploração aberta, em que você quer ver como ele interpreta o problema antes de restringir.
• Contexto que já está no CLAUDE.md. Repetir no prompt só gasta espaço.
• Detalhe que ele descobre lendo o código em segundos (nome de função, estrutura de pasta). Aponte o lugar e deixe ele ler.

Faça agora

A prática é escrever três versões do mesmo pedido e comparar o resultado.

1. Escolha uma tarefa real e pequena no seu projeto, numa branch separada.
2. Escreva a versão vaga: uma frase, sem arquivo, sem critério.
3. Escreva a versão excessiva: cole tudo que parece relevante (arquivos inteiros, log, histórico de conversa).
4. Escreva a versão verificável usando o modelo abaixo.
5. Rode cada versão numa sessão nova. Use /clear entre elas ou abra sessões separadas, para uma não contaminar a outra. Se a tarefa edita arquivos, volte o código entre as rodadas com git stash ou git checkout.
6. Para cada uma, anote: quantos passos até terminar, se acertou o problema certo, quantas correções você precisou fazer, e o que /context mostrou ocupando a janela ao final.
7. Escreva duas linhas sobre o que a versão verificável tinha que as outras não tinham.

Modelo de pedido verificável:

Objetivo: o que precisa mudar e por quê, em uma ou duas frases.
Sintoma ou cenário: o que acontece hoje e como reproduzir.
Onde olhar: @caminho/do/arquivo ou pasta, e um exemplo de padrão a seguir.
Restrições: o que não pode mudar (API pública, dependências, formato).
Fora de escopo: o que não é para mexer agora.
Pronto quando: teste, comando ou saída que prova que funcionou.

Armadilhas

• Colar o repositório. Ele lê arquivo sozinho. Colar ocupa contexto e tira dele a chance de escolher o que importa.
• Log inteiro. Quatro mil linhas de log enterram a única linha que interessa. Filtre antes.
• Restrição implícita. "Óbvio que não podia mudar a assinatura" só é óbvio para você. Escreva.
• Sem critério de pronto. Sem ele, o agente para quando parece pronto, e quem verifica é você.
• Restrições contraditórias. "Não mexa em nada fora de src/auth" e "atualize a documentação" no mesmo pedido. Ele vai escolher uma. Talvez não a sua.
• Prompt longo para compensar falta de verificação. Parágrafo a mais não substitui um teste que roda.

Material para levar

Checklist antes de mandar um pedido que edita código:

[ ] Objetivo em uma ou duas frases
[ ] Sintoma ou cenário concreto
[ ] Pelo menos um caminho com @ ou uma fonte apontada
[ ] Um exemplo de padrão a seguir, se existir
[ ] Restrições escritas, não presumidas
[ ] O que está fora do escopo
[ ] Critério de pronto que roda (teste, build, script, saída esperada)
[ ] Nada colado que ele poderia ler sozinho

Comparação das três versões:

Versão       | Passos | Problema certo? | Correções minhas | O que pesou no /context
Vaga         |        |                 |                  |
Excessiva    |        |                 |                  |
Verificável  |        |                 |                  |

O que fez diferença: