Como escrever uma spec que o agente realmente entende (e não inventa em cima)

A maior parte dos bugs de agente que eu vejo em 2026 não é o modelo errando.

É a spec mentindo.

O dev escreve "adicione testes para o serviço de cobrança", o agente devolve uma porção de testes que cobre o caminho feliz e nada mais, e a conclusão é "esses LLM são burros". Não são. Você pediu testes. Ele entregou testes. A culpa de não ter coberto o caso do cartão recusado é de quem não escreveu isso na spec.

Esse post é sobre uma habilidade que ninguém ensina formalmente ainda: escrever instrução técnica para um leitor que não tem cultura, não tem histórico do projeto e não tem como ler sua mente. Vou destrinchar três anti-padrões reais, com exemplo antes/depois, e fechar com um checklist de sete pontos que eu uso antes de mandar qualquer spec pro Claude Code.

TL;DR

• O que é: spec = qualquer texto que o agente lê antes de agir (prompt, CLAUDE.md, ticket colado no terminal).
• Diagnóstico: a maior parte dos erros de agente em 2026 é falha de contexto, não de modelo (Anthropic, Effective context engineering).
• Três anti-padrões: ambiguidade que parece clareza, contexto irrelevante que polui o foco, regra implícita que só existe na sua cabeça.
• Saída prática: checklist de 7 pontos para passar a spec antes de mandar pro agente.

Por que escrever spec virou habilidade nova

Andrej Karpathy resumiu em uma frase que virou referência no campo: o LLM é a CPU, a janela de contexto é a RAM, e seu trabalho é ser o sistema operacional, carregando a memória de trabalho com exatamente o código e os dados certos para a tarefa (Lakera, Prompt Engineering Guide 2026).

A Anthropic foi mais direta no Effective context engineering for AI agents: a maioria das falhas de agente hoje não vem do modelo, vem de contexto montado errado. Documento errado recuperado. Histórico inflado. Instrução vaga assumindo conhecimento compartilhado que não existe.

O que isso muda no dia a dia do dev?

Antes você era o autor do código. Agora, em qualquer fluxo onde existe agente envolvido (Claude Code, Cursor, agente de PR, pipeline de migração em massa), você virou o redator da spec. O código é consequência. A spec é a entrada.

E aí cai a ficha: ninguém na faculdade ensinou "escrita técnica para LLM". Não tem manual. Não tem livro do tio Bob para isso. A indústria está descobrindo no susto que escrever bem para um agente é uma habilidade própria, diferente de escrever ticket para humano e diferente de escrever prompt para chat one-shot.

A boa notícia: os anti-padrões se repetem. Conhecer três deles já corta uma faixa enorme dos erros.

Anti-padrão 1: ambiguidade que parece clareza

Esse é o mais traiçoeiro porque a frase soa profissional. Você escreveu, releu, achou claro. Para você. Que tem o projeto inteiro carregado na cabeça.

Antes:

adicione testes para foo.py

Depois:

escreva um teste para foo.py cobrindo o edge case em que o usuário
está deslogado. evite mocks; use a fixture de banco real do tests/conftest.py.

Esse exemplo vem direto da tabela de boas práticas do Claude Code, e é didático justamente porque a versão "antes" parece um ticket razoável.

Por que falha? Quando a instrução é ambígua, o modelo preenche o vazio com a média do que viu no treino. "Adicione testes" vira o que a maioria dos repositórios públicos chama de "testes para um arquivo": três testes de happy path com pytest, importando direto, sem fixture nenhuma. Tecnicamente é o que você pediu. Operacionalmente é inútil.

A frase da Anthropic que eu deixaria tatuada: "Claude can infer intent, but it can't read your mind."

Outro flanco da mesma armadilha: nomes ambíguos em parâmetros e funções. A Anthropic recomenda no Writing tools for agents que parâmetros sejam inequívocos: user_id em vez de user, file_type em vez de mime_type. Vale para spec também. Se você diz "atualize o user", qual user? O objeto? O ID? A linha do banco? As três coisas têm semânticas diferentes e o agente vai chutar uma.

Regra prática: se a frase aceita mais de uma interpretação técnica plausível, ela está ambígua. Não importa que pareça clara.

Anti-padrão 2: contexto irrelevante que polui o foco

A reação intuitiva ao primeiro anti-padrão é "ah, então eu mando mais contexto". Calma. O outro extremo também quebra.

Antes (CLAUDE.md de 4000 tokens com tudo dentro):

# Sobre o projeto
Este projeto começou em 2023 com a missão de...
[800 palavras de história]

# Decisões antigas
Em 2024 migramos de MySQL para Postgres por causa de...
[600 palavras de decisões irrelevantes para a tarefa de hoje]

# Padrões
Use camelCase. Exceto em arquivos legados, que usam snake_case.
Mas nos novos serviços de billing voltamos para snake_case também
porque...
[500 palavras de exceções e contra-exceções]

# Tarefa
Implemente o endpoint POST /coupons.

Depois:

# Padrões que importam pra esta tarefa
- Endpoints novos: POST /coupons segue o pattern de POST /orders
  em app/Http/Controllers/OrderController.php
- snake_case nos campos de request (estamos no domínio billing)
- Validação no FormRequest, nunca no controller

# Tarefa
Implemente POST /coupons. Schema: code (string, único, 3-20 chars),
discount_percent (int, 1-100), expires_at (datetime futuro).
Critério de sucesso: tests/Feature/CouponTest.php verde.

A versão "antes" não é caricatura. É o CLAUDE.md médio que eu vejo em projeto real. E quebra duas vezes: primeiro pelo custo (a janela enche e o modelo começa a esquecer instruções antigas), segundo pela diluição (a regra que importa some no meio do ruído).

A própria documentação do Claude Code é taxativa: "If your CLAUDE.md is too long, Claude ignores half of it because important rules get lost in the noise." (Best Practices for Claude Code). E recomenda o teste cirúrgico: para cada linha, pergunte "se eu tirar isso, o agente vai errar?" Se a resposta é não, corta.

Contexto não é gratuito. É um recurso escasso que você está consumindo. Trate como você trataria payload de uma API com bilhete por byte: só o que paga o próprio peso entra.

Anti-padrão 3: regra implícita que só existe na sua cabeça

Esse é o anti-padrão que separa o sênior do júnior na escrita de spec, e o que mais gera "alucinação" sem alucinação nenhuma. O modelo não inventou. Ele preencheu uma lacuna que você deixou.

Antes:

implemente o pagamento seguindo os padrões do projeto e tratando
os erros adequadamente.

Quantas decisões implícitas tem essa frase? Conta com calma:

• "Padrões do projeto": quais? Onde? Qual arquivo é o exemplar?
• "Pagamento": qual gateway? Stripe? Pagar.me? Mock para dev?
• "Tratando os erros": loga? lança exceção? retorna 500? notifica o Sentry?
• "Adequadamente": para o cliente final? para o suporte? para o oncall?

Cada uma dessas lacunas é uma decisão que o agente vai tomar por conta. Você só vai descobrir no PR review.

Depois:

implemente o pagamento via Stripe seguindo o pattern de
app/Services/Billing/SubscriptionPaymentService.php.
Tratamento de erro:
- StripeCardException: lance App\Exceptions\PaymentDeclinedException
  com a mensagem amigável do Stripe.
- StripeRateLimitException: retry com backoff exponencial
  (use o trait RetriesStripeCalls).
- Qualquer outra StripeException: log no canal "billing", notifica
  Sentry com tag payment_provider=stripe, lança PaymentFailedException.

A régua da Anthropic para tool design vale linha a linha para spec: "think of how you would describe your tool to a new hire on your team. Consider the context that you might implicitly bring...and make it explicit" (Writing tools for agents).

E tem um princípio adjacente que o time deles repete em quase todo material recente: se um engenheiro humano não sabe dizer com certeza qual tool usar numa situação, o agente também não vai saber. Vale para qualquer decisão na spec. Se você precisa parar e pensar pra responder, o agente não tem contexto pra adivinhar.

Critério prático: se um dev novo da equipe não conseguisse executar a tarefa lendo só essa spec, o agente também não consegue. Ele só consegue parecer que conseguiu.

Checklist: 7 pontos antes de mandar pro agente

Esse é o passe final que eu rodo antes de submeter qualquer spec não-trivial pro Claude Code. Leva 60 segundos. Economiza muito mais que isso em ida e volta.

1. Objetivo cabe em uma frase concreta? Com substantivo de produto, não verbo abstrato. "Adicionar endpoint POST /coupons" passa. "Melhorar a parte de cupons" não.

2. Arquivos e funções estão referenciados pelo nome? Sem "aquela parte do auth", sem "o serviço de cobrança". Caminho exato: app/Services/Billing/CouponService.php.

3. Critério de sucesso é verificável? Teste que precisa passar, comando que precisa rodar, output esperado. Sem isso o agente fica sem feedback loop e você vira a única validação (Best Practices chama isso de "the single highest-leverage thing you can do").

4. Edge cases estão listados nominalmente? Não vale "considere os edge cases", isso é delegar a especificação. Liste: usuário deslogado, cartão recusado, código duplicado, expiração no passado.

5. Toda linha passa no teste do "se eu tirar, o agente erra"? Se a resposta é "não muda nada", deleta. Spec inflada faz o modelo ignorar a parte que importa.

6. Padrão a seguir tem exemplar apontado? "Siga o pattern de X" precisa do X com caminho. Descrição abstrata de padrão não funciona, exemplo concreto sim.

7. Um dev novo da equipe conseguiria executar lendo só isso? Se a resposta é "ele teria que perguntar", o agente também teria. Só que ele não pergunta: ele inventa.

Se passou nos sete, manda. Se travou em algum, ajusta antes. Sai mais barato editar uma spec do que reverter um PR.

Fecha aqui

Spec deixou de ser overhead burocrático e virou superfície de programação. Quem escreve bem dirige o agente. Quem escreve mal vira revisor de output ruim em loop infinito.

A próxima vantagem competitiva do dev não é decorar prompt mágico nem caçar a próxima ferramenta. É essa habilidade chata e concreta de escrever instrução técnica que sobrevive a um leitor sem cultura, sem histórico e sem capacidade de perguntar de volta. É escrita técnica para LLM: disciplina nova, com pouquíssima literatura, e que vai diferenciar quem constrói produto com agente de quem só faz demo bonita.

Esse é exatamente o tipo de músculo que a gente treina ao vivo no Harness Engineering com Claude Code, nos dias 16 e 17/05: dois dias montando do zero, com Claude Code + Laravel + NativePHP, um agente que recebe link de produto, pesquisa alternativas em e-commerces, compara preço e devolve recomendação estruturada. Spec, contexto, harness e produto rodando, sem chatbot de demo no meio do caminho.