Como descrever regra de negócio cheia de exceções no prompt do Claude Code

Fala aí, beleza? Toda empresa tem aquela regra que cabe em uma frase e desaba em trinta linhas de ‘exceto quando’

O frete é grátis acima do valor mínimo, exceto item frágil, exceto região não atendida, exceto cliente com pendência, exceto na semana da promoção, exceto se o pedido veio do marketplace…

Aí você joga isso no agente e acontece o clássico: ele implementa a regra geral com perfeição e erra TODAS as exceções

E a culpa não é do modelo, é do enunciado 🙂

A regra geral qualquer um infere, inclusive um LLM lendo o nome da sua função. A exceção é a parte que só existe na sua empresa, e é justamente essa parte que costuma ir pro prompt em forma de prosa desorganizada

Bora arrumar isso?

O que você precisa antes de escrever o prompt

Lista curta e honesta, nada de pré-requisito enfeitado:

• As exceções mapeadas, nem que seja num rascunho feio de bloco de notas. Se elas só existem na cabeça de alguém do time, o prompt vai nascer torto
• Claude Code aberto no projeto, porque o agente lendo o código existente já resolve metade da ambiguidade
• Saber onde moram as instruções persistentes: CLAUDE.md na raiz do projeto, arquivos de projeto em .claude/ dentro do repositório e escopo global em ~/.claude/, que vale pra todos os projetos da máquina
• Idealmente, algum comando de checagem que rode e devolva pass ou fail (teste, build, linter)

Esse último item é opcional pra começar, mas ele muda o jogo lá na frente, te conto o porquê no passo 6

Passo a passo: transformar ‘exceto quando’ em prompt que o agente implementa

A ideia central é simples: parar de descrever a regra e passar a mostrar o comportamento esperado

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

1. Escreva a regra geral em UMA frase, no positivo

A documentação de boas práticas recomenda dizer ao Claude o que fazer, e não o que evitar. Instrução positiva funciona melhor que lista de proibição

Regra geral: pedido acima do valor minimo sai com frete gratis

Acabou. Uma linha

Se a sua ‘regra geral’ ainda tem um ‘desde que’ no meio, ela não é a regra geral, ela já é uma exceção disfarçada

O erro comum deste passo: escrever a regra geral no negativo (‘não conceder frete grátis quando…’). Aí o modelo fica adivinhando qual é o caminho feliz

2. Liste cada ‘exceto quando’ como entrada e saída, não como prosa

Prosa aceita ambiguidade, linha de entrada e saída não aceita. É aqui que você descobre que metade das exceções do seu time nunca foi decidida de verdade 😀

item fragil                -> frete cobrado
regiao nao atendida        -> frete cobrado
cliente com pendencia      -> frete cobrado
pedido vindo do marketplace-> frete cobrado pelo parceiro
semana de promocao         -> frete gratis mesmo abaixo do minimo

O erro comum deste passo: juntar duas condições na mesma linha sem dizer quem ganha. Item frágil E semana de promoção dá o quê? Se você não sabe, o agente também não vai saber

3. Vire essa lista numa tabela de entradas e saídas esperadas

A tabela obriga você a preencher a célula do cruzamento, aquela que a prosa deixa escapar

| Valor        | Regiao      | Item    | Situacao cliente | Saida esperada          |
|--------------|-------------|---------|------------------|-------------------------|
| acima do min | atendida    | comum   | ok               | frete gratis            |
| acima do min | atendida    | fragil  | ok               | frete cobrado           |
| acima do min | nao atendida| comum   | ok               | frete cobrado           |
| abaixo do min| atendida    | comum   | ok               | frete cobrado           |
| abaixo do min| atendida    | comum   | ok + promocao    | frete gratis            |
| acima do min | atendida    | comum   | com pendencia    | frete cobrado           |

Vale reforçar: essa tabela é um formato prático de escrever exemplo, não uma prescrição oficial da Anthropic. O que a documentação pede é exemplo bom, o desenho fica a seu critério

O erro comum deste passo: montar a tabela só com os casos que dão certo. Caso de borda fora da tabela é caso de borda que o agente vai inventar sozinho

4. Converta as linhas mais representativas em 3 a 5 exemplos canônicos dentro de tags XML

A documentação de multishot prompting trata exemplos como uma das formas mais confiáveis de direcionar formato, tom e estrutura da saída, e indica de 3 a 5 exemplos diversos e relevantes pra melhor resultado, com mais exemplos tendendo a ajudar em tarefas complexas

Relevante quer dizer que espelha o caso de uso real. Diverso quer dizer que cobre casos de borda e varia o bastante pra o Claude não captar um padrão não intencional

A mesma doc orienta envolver cada exemplo em <example> e o conjunto em <examples>, justamente pro modelo não misturar instrução, dados e exemplo

<examples>
<example>
Entrada: valor acima do minimo, regiao atendida, item comum, cliente ok
Saida: frete_gratis = true, motivo = regra geral
</example>
<example>
Entrada: valor acima do minimo, regiao atendida, item fragil, cliente ok
Saida: frete_gratis = false, motivo = item fragil exige embalagem especial
</example>
<example>
Entrada: valor abaixo do minimo, regiao atendida, item comum, cliente ok, semana de promocao
Saida: frete_gratis = true, motivo = promocao ignora valor minimo
</example>
<example>
Entrada: valor abaixo do minimo, regiao nao atendida, item comum, cliente ok, semana de promocao
Saida: frete_gratis = false, motivo = regiao nao atendida tem prioridade sobre promocao
</example>
</examples>

Se liga no quarto exemplo: ele coloca promoção e região não atendida na MESMA entrada de propósito, duas condições que apontam pra saídas opostas, pra ensinar a PRECEDÊNCIA, que é a parte que ninguém escreve e todo mundo assume

O erro comum deste passo: escolher cinco exemplos irmãos gêmeos. Cinco variações do caminho feliz ensinam o modelo a generalizar exatamente o que você não queria

5. Rode em plan mode antes de deixar ele escrever código

No plan mode o Claude lê arquivos e responde sem alterar código. Dá pra ativar pressionando Shift+Tab até a barra de status mostrar o plan mode ativo, ou já abrindo a sessão assim:

claude --permission-mode plan

Leia o plano procurando uma coisa só: ele citou as exceções? Se o plano fala em frete grátis acima do mínimo e não menciona item frágil, seu enunciado ainda não passou

Esse também é o momento de perceber onde ele deveria ter perguntado em vez de chutar, que é um assunto inteiro sobre quando o agente decide sozinho

O erro comum deste passo: ler o plano no diagonal e aprovar. Plano aprovado no diagonal é código errado com autorização assinada por você haha

6. Feche o loop com uma checagem executável

A documentação do Claude Code é direta nisso: sem uma checagem que o próprio Claude possa rodar, ‘parece pronto’ vira o único sinal disponível

Dar algo que produza pass ou fail (suíte de testes, exit code de build, linter, script que compara a saída com uma fixture) fecha o ciclo: ele roda, lê o resultado e itera até passar

# a tabela do passo 3 vira a fixture da checagem
npm test -- frete

Repare que a tabela de entradas e saídas já é, na prática, o seu conjunto de casos de teste. O mesmo artefato serve pra enunciar e pra verificar, isso é MUITO conveniente

O erro comum deste passo: testar só o caminho geral. Se a checagem não cobre a exceção, o agente passa no teste errando a parte que importa

Por que descrever a exceção vale mais que descrever a regra geral

Pensa em como o modelo chega no seu projeto

Ele lê calcularFreteGratis, vê o código em volta, vê os nomes das variáveis e já infere sozinho que frete grátis tem a ver com valor de pedido. A regra geral está meio que embutida no mundo

Agora, que a sua empresa cobra frete de item frágil porque a embalagem especial estoura a margem? Isso não está em lugar nenhum do planeta, só na sua cabeça e talvez numa thread do Slack de dois anos atrás

É o mesmo raciocínio de quando você precisa descrever uma tela sem design pronto: o que o modelo consegue inferir você não precisa escrever, o que ele não tem como saber é obrigatório

Vale pra qualquer domínio chato da vida real:

• Desconto: o cupom acumula com a promoção da categoria? Em quais categorias não acumula?
• Elegibilidade: quem entra na regra é fácil, quem SAI dela é onde mora a dor
• Cálculo de imposto: a alíquota geral é pública, o regime especial da sua operação não é
• Prazo: prazo padrão todo mundo sabe, o que acontece quando o prazo cai em feriado municipal é decisão interna

A própria Anthropic escreveu sobre isso: times costumam despejar uma ‘laundry list’ de edge cases tentando articular toda regra possível, e a recomendação oficial é curar um conjunto de exemplos canônicos e diversos que mostrem o comportamento esperado, porque pra um LLM exemplo é a imagem que vale mil palavras

Ou seja, não é escrever MAIS, é escrever o certo

E o critério oficial de exemplo bom volta aqui: relevante (espelha o caso real) e diverso (cobre os casos de borda). Suas exceções são, por definição, os casos de borda. Elas são o material bruto perfeito 😀

Prompt em prosa x prompt com tabela de entradas e saídas

Mesma regra, mesma pessoa escrevendo, dois resultados bem diferentes

Não é comparativo de ferramenta, é comparativo de técnica: as duas formas cabem no mesmo prompt, só que uma delas você consegue manter vivo por seis meses

Onde guardar essa regra para não reescrever o prompt toda sessão

Fazer esse trabalho todo e colar no chat de novo amanhã é desperdício, né?

1. Coloque a regra no CLAUDE.md

Ele é o arquivo markdown de instruções persistentes e o Claude lê no começo de toda sessão. Se o projeto ainda não tem, o /init gera um inicial e o /memory serve pra refinar o arquivo depois

/init

O erro comum deste passo: despejar a tabela inteira com trinta linhas. Guarde a regra geral, as exceções e os exemplos canônicos escolhidos, o resto vive melhor na suíte de testes

2. Decida o escopo com consciência

Regra do produto é escopo de projeto e mora no repositório, em CLAUDE.md na raiz e nos arquivos dentro de .claude/. Preferência sua de fluxo de trabalho é escopo global e mora em ~/.claude/, valendo pra todos os projetos da máquina

Regra de negócio da empresa versionada junto do código é o caminho: entra no pull request, o time revisa, e quando a regra muda o histórico mostra quando mudou

O erro comum deste passo: botar regra de negócio no global. Aí só funciona na SUA máquina e o resto do time não faz ideia do porquê o agente acerta pra você e erra pra eles

3. Se virou rotina, transforme em comando invocável

Quando você repete o mesmo enunciado toda semana (revisar regra, gerar tabela de casos, conferir precedência), vale virar um comando com /nome

O recomendado hoje é .claude/skills/<nome>/SKILL.md. Comandos de projeto em .claude/commands/ e pessoais em ~/.claude/commands/ são o formato legado, com a mesma invocação por /nome

.claude/skills/regra-de-negocio/SKILL.md

O erro comum deste passo: criar o comando antes da regra estar estável. Primeiro faça funcionar na mão duas ou três vezes, depois empacota

O agente ignorou a exceção: o que checar no seu prompt

Antes de culpar o modelo, roda esse checklist

Sintoma: a exceção só aparece em negativa

Causa provável: o prompt está cheio de proibição (‘nunca conceda frete grátis para item frágil’) em vez de comportamento desejado

Como prevenir: a orientação oficial é dizer o que fazer, não o que não fazer. Reescreva como resultado esperado: item frágil, frete cobrado, motivo embalagem especial

Sintoma: ele acerta um caso e erra os parecidos

Causa provável: seus exemplos são todos parecidos e o modelo generalizou o padrão errado

Como prevenir: diversidade é critério oficial de exemplo bom. Troque um exemplo do caminho feliz por um exemplo onde duas exceções brigam entre si

Sintoma: ele trata o seu exemplo como se fosse a instrução (ou vice versa)

Causa provável: não tem separação entre instrução, dados e exemplo, está tudo no mesmo bolo de texto

Como prevenir: use <example> para cada exemplo e <examples> para o conjunto. As tags XML existem exatamente pra o modelo não misturar as coisas

Sintoma: ele diz que terminou e a exceção continua quebrada

Causa provável: não existe nenhuma forma de o agente saber que errou, então ‘parece pronto’ virou o único sinal disponível

Como prevenir: dê algo que produza pass ou fail. Com a checagem na mão ele roda, lê o resultado e itera até passar, sem depender do seu olho

E tem o teste que resolve mais que todos os outros juntos: a documentação de boas práticas de prompting traz como regra de ouro o teste do colega. Mostre o enunciado pra alguém com contexto mínimo e peça pra pessoa seguir

Se a pessoa ficar confusa, o Claude também fica 🙂

Já vi enunciado sobreviver a três rodadas de ajuste fino e morrer na primeira pergunta de um colega do outro time…

Use o próprio Claude Code para achar a exceção que você esqueceu

Essa parte é bônus e fecha o ciclo bonitinho

1. Peça pra ele analisar os caminhos de código e sugerir testes para condições de erro, valores de fronteira e entradas inesperadas. Ele espelha o estilo e o framework dos testes que já existem no projeto

Analise os caminhos de codigo de calculo de frete e sugira testes para
condicoes de erro, valores de fronteira e entradas inesperadas.
Siga o estilo e o framework dos testes existentes.

2. Leia a lista procurando o caso que você não tinha pensado. Valor exatamente NO limite, região vazia, item sem categoria, cliente sem histórico

3. Cada caso novo vira uma linha na tabela de entradas e saídas do passo 3, e os mais representativos podem entrar como exemplo canônico

O erro comum deste passo: aceitar a sugestão dele como verdade da regra. Ele acha o buraco no código, quem decide o que sai do buraco é você e o time

Conclusão

Regra de negócio cheia de exceção não precisa de mais texto, precisa de exemplo certo e de uma checagem que rode

Recapitulando o caminho: regra geral em uma frase no positivo, cada ‘exceto quando’ vira linha de entrada e saída, a lista vira tabela, as linhas mais representativas viram 3 a 5 exemplos canônicos em <example> dentro de <examples>, plan mode antes de liberar a escrita e uma checagem com pass ou fail pra ele iterar sozinho

Próximo passo concreto pra hoje: pega a regra mais bagunçada do teu projeto, aquela que ninguém do time explica igual, escreve os exemplos canônicos em tags <example>, cola no CLAUDE.md e roda em plan mode antes de deixar ele escrever uma linha sequer

Se o plano citar as exceções, tu já ganhou o dia 😀

até o próximo post!