Vale a pena explicar o porquê da tarefa no prompt do Claude Code?

Fala aí, beleza? Tem prompt que só manda fazer, e tem prompt que conta pra quê

O primeiro diz "troque essa função por uma versão sem regex"

O segundo diz "troque essa função por uma versão sem regex, porque ela roda em cima de input do usuário"

Mesma tarefa, dois pedidos bem diferentes…

A dúvida aqui é honesta: esse "porque" ajuda o Claude Code a escolher melhor, ou é texto jogado fora que só ocupa contexto? A resposta curta é que depende do tipo de tarefa, e é exatamente isso que a gente separa neste post

De cara vale registrar uma coisa: a própria Anthropic, na página de boas práticas de prompting, recomenda dar contexto ou motivação por trás das instruções, ou seja, explicar ao Claude por que aquele comportamento importa, pra que ele entenda melhor o objetivo e entregue respostas mais direcionadas

Então a discussão não é "pode ou não pode"

É QUANDO compensa 🙂

Prompt só com o passo técnico x prompt com a intenção: o que muda

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O exemplo que a Anthropic usa pra ilustrar isso é ótimo porque não tem nada de código nele

A instrução ruim é "NUNCA use reticências"

A instrução boa é "nunca use reticências porque o texto será lido por um motor de text-to-speech, que não sabe pronunciá-las"

A segunda funciona melhor, e o motivo é simples: com o porquê na mão, o modelo consegue aplicar a mesma lógica pra tudo que o motor de voz também não sabe ler, e não só pro caractere que você lembrou de proibir

(sim, eu uso reticências aqui no blog o tempo todo, mas ninguém vai ler isso em voz alta haha)

A outra régua oficial é a regra de ouro: mostre o prompt pra um colega que tem contexto MÍNIMO sobre a tarefa e peça pra ele seguir o texto

Se o colega ficaria confuso, o Claude também fica

Repare que o segundo modo não é "escrever mais"

É escrever a linha que elimina a ambiguidade, e só ela

Em que tarefas o porquê muda a solução escolhida

Aqui tá o fio condutor do post inteiro: quando o critério de sucesso não está no código, o porquê É o critério

Vamos aos casos onde isso aparece de verdade

Restrição que só faz sentido conhecendo o destino do output:

O caso das reticências é isso em estado puro

O código gerado não tem como saber que aquele texto vai virar áudio

Nenhuma leitura do repositório entrega essa informação, ela mora fora do projeto, na cabeça de quem pediu

Quando a restrição depende de onde o resultado vai parar, o motivo não é enfeite, é dado de entrada

Decisão de estilo que depende do entorno:

Esse é o exemplo mais interessante, e quem conta é a Anthropic no post sobre as novas regras de context engineering

O system prompt antigo do Claude Code trazia a instrução In code: default to writing no comments

Regra limpa, direta… e errada pra uma parte real das tarefas

Tem usuário com preferência própria de documentação, e tem trecho complexo que pede bloco de comentário mesmo

A orientação nova é acompanhar o código ao redor: densidade de comentário, nomenclatura e idioma

Ou seja, uma regra fixa foi trocada por um critério

E critério é justamente o que você entrega quando explica o porquê

Pedido em que não há como inferir:

A documentação de boas práticas do Claude Code resume isso numa frase honesta: o Claude consegue inferir intenção, mas não lê mentes

E aí ela manda o dever de casa: referencie arquivos específicos, mencione restrições e aponte padrões de exemplo

Se você conhece aquele colega novo que entrou no time semana passada, é a mesma dinâmica

Ele é excelente, lê o repositório inteiro, mas não estava na reunião em que vocês decidiram que aquele endpoint não pode quebrar contrato com o app antigo

Essa reunião você tem que contar

Quando explicar o porquê só ocupa espaço

Agora o outro lado, que é onde a maioria dos posts sobre prompt para de falar

A Anthropic removeu mais de 80% do system prompt do Claude Code para os modelos da geração Claude 5, sem perda mensurável nas avaliações de código

Mais de 80%, se liga nisso

O diagnóstico oficial foi que eles estavam super-restringindo o Claude Code, e não só pelo system prompt: também pelos arquivos CLAUDE.md e pelas skills

Mensagens sobrepostas e conflitantes numa mesma requisição competem entre si

Ou seja, cada justificativa a mais não é neutra, ela disputa espaço com o resto

E tem o fenômeno que a Anthropic chama de context rot: conforme o número de tokens na janela de contexto cresce, a capacidade do modelo de recuperar informação daquele contexto com precisão diminui

Por isso a definição de context engineering deles é essa: encontrar o menor conjunto possível de tokens de alto sinal que maximize a chance do resultado desejado, porque o orçamento de atenção é finito

Menor conjunto possível

De ALTO sinal

Seu parágrafo de justificativa passa nesses dois filtros? Se não passa, ele tá competindo com a instrução que importa

E tem ainda o caso em que o vago é legítimo: a própria doc do Claude Code diz que prompts vagos podem ser úteis quando você está explorando e pode se dar ao luxo de corrigir o rumo depois

Exploração não precisa de briefing

É o mesmo raciocínio de escolher entre /goal e ultracode conforme o tamanho da tarefa: o peso do enquadramento tem que caber no que você tá pedindo

Onde colocar o porquê: no prompt, no CLAUDE.md ou numa skill

Muita gente trata isso como uma decisão só, e não é

O material oficial da Anthropic sobre direcionar o Claude Code divide bem os lugares:

• CLAUDE.md serve pra preferências de nível de projeto
• instruções procedurais (fluxo de deploy, checklist de release, processo de revisão) pertencem a uma skill, não ao CLAUDE.md

E tem um detalhe que muda tudo: o corpo de uma skill só carrega quando ela é usada, ao contrário do conteúdo do CLAUDE.md, que fica sempre no contexto

Agora junta com o que a gente viu na seção anterior

Motivo que vale pra TODO pedido do projeto não deveria ser recolado a cada prompt, o lugar dele é a preferência de projeto

Motivo de um procedimento específico não deveria morar sempre ligado, o lugar dele é a skill que carrega na hora que for usada

É a mesma conversa de quando você compara montar seu próprio fluxo de prompts com adotar um pacote pronto: o que decide não é a quantidade de instrução, é onde cada pedaço fica ligado

Dois comandos que ajudam nesse dimensionamento:

O /doctor faz um check-up completo da configuração e ajuda a diagnosticar por que CLAUDE.md, settings, hooks, servidores MCP ou skills não estão fazendo efeito

A Anthropic afirma ter embutido essas boas práticas de context engineering nele justamente pra você dimensionar corretamente suas skills e seus arquivos CLAUDE.md

Já o /clear é pra outra dor: quando a sessão acumula correção em cima de correção, a orientação oficial é limpar e recomeçar com um prompt mais específico

O argumento deles é forte: uma sessão limpa com prompt melhor quase sempre supera uma sessão longa com correções acumuladas

Tome cuidado com o reflexo de continuar empurrando "não, não era isso" na mesma conversa

Geralmente é mais rápido escrever o prompt que você deveria ter escrito na primeira vez 😀

Vale a pena? O veredito

Vale, mas como token de alto sinal, não como preâmbulo

Uma frase de intenção que elimina ambiguidade paga por si sozinha

Parágrafos de justificativa repetidos em toda instrução caem exatamente no over-constraining que a própria Anthropic apagou do produto dela

E a justificativa dessa poda é de capacidade, não de preguiça: modelos antigos precisavam de orientação forte, às vezes errada, pra evitar o pior caso, enquanto os modelos novos conseguem ler o contexto ao redor e usar julgamento

A linha atual é essa: Opus 5, Sonnet 5, Fable 5 e Mythos 5

A mudança de fundo é de regras pra julgamento

E julgamento se alimenta de objetivo, não de proibição

Pra quem o porquê importa mais? Pra quem trabalha em código onde várias soluções passam no teste e só uma serve pro negócio: integração com sistema legado, regra de produto, restrição que não tá escrita em lugar nenhum do repo

Pra quem quase não muda nada? Renomear variável, extrair função, escrever teste de uma função pura, mexer em CSS

Nessas, o passo técnico já é o objetivo inteiro

Conclusão

O critério cabe em uma linha: existe mais de uma solução correta? Então diga o porquê

Se só existe uma, o porquê vira ruído competindo com a instrução

Seu próximo passo, bem concreto:

1. Pegue o ÚLTIMO prompt que você mandou pro Claude Code e aplique a regra de ouro: um colega com contexto mínimo sobre a tarefa conseguiria seguir aquilo sem perguntar nada?
2. Mova o que é procedimento (deploy, release, revisão) pra uma skill, já que o corpo dela só carrega quando é usada
3. Deixe no CLAUDE.md só o que é preferência de nível de projeto, lembrando que aquilo fica sempre no contexto
4. Rode /doctor e confira o dimensionamento antes de sair enchendo o contexto de justificativa

Explicar o porquê no prompt do Claude Code é ferramenta de precisão, não é volume

Uma frase certa vale mais que três parágrafos de contexto que ninguém pediu

Bora testar no seu próximo prompt? 🙂

até o próximo post!