✅ Testes e o porquê documentado
A regra de ouro
A disciplina que separa um prompt que cresce com saúde de um que apodrece em regras soltas: toda regra precisa de um porquê documentado e de um teste que falharia sem ela. Sem teste, a regra não entra. Sem porquê, não generaliza. Você vai instalar esse portão e construir a suíte mínima do seu próprio prompt.
Conteúdo detalhado
A regra de ouro
Existe uma única frase que sustenta toda a cultura desta trilha: toda regra adicionada precisa de um porquê documentado E de um teste que falharia sem ela. São duas exigências unidas por um E — não um OU. Reprovar em qualquer uma das duas já barra a regra. É um portão, não uma sugestão.
⚖️ Os dois portões, em série
🧪 Portão 1 — Teste
Existe um caso concreto que quebra hoje e que essa regra consertaria? Se você não consegue escrever esse caso, a regra resolve um problema imaginário. Sem teste, ela não entra.
📝 Portão 2 — Porquê
A regra carrega a intenção em texto, ao lado dela? Sem o porquê, o modelo obedece à letra e viola o espírito em casos novos. Sem porquê, ela não generaliza.
Por que os dois? Porque cada um cobre uma falha diferente. O teste protege contra regras especulativas (você acha que precisa, mas não precisa). O porquê protege contra regras frágeis (funcionam no caso que você viu, falham no próximo). Juntos, eles transformam "achismo" em engenharia.
Por que isso é uma "regra de ouro"
É a única regra que você aplica a si mesmo enquanto escreve o prompt — uma meta-regra. Ela não vive no prompt do produto; vive no seu processo. É o que impede o prompt-cebola (Trilha 1) de acontecer com você.
Escrever o teste-que-falharia
Um "teste-que-falharia" não é um teste unitário de código — é um caso de entrada + comportamento esperado, escrito de forma que, sem a regra, o modelo erra; com a regra, acerta. Se o prompt já passa sem a regra, o teste é inútil e a regra também.
Como construir o caso — 4 campos
- 1.Entrada — a mensagem/contexto exato que dispara o problema. Concreto, copiável.
- 2.Esperado — o comportamento desejado, observável (não "ser melhor", mas "não cria arquivo novo").
- 3.Falha-sem-regra — o que acontece HOJE, sem a regra. Você precisa ter visto isso acontecer.
- 4.Critério de aprovação — como você decide passou/falhou sem ambiguidade.
# Teste T-007 — prefira editar a criar
ENTRADA: "adicione um campo email no formulário de cadastro"
ESPERADO: edita o arquivo existente do formulário; NÃO cria um novo
FALHA SEM: o agente cria form-novo.tsx e duplica o componente
CRITÉRIO: nenhum arquivo novo é criado quando um já cobre o caso
REGRA QUE COBRE: "NEVER create files unless absolutely necessary;
prefer editing an existing file — porque arquivos
duplicados fragmentam a base e confundem o próximo agente"
VINCULADO A: changelog v0.4 · padrão: Regra com Porquê (Ficha 3)O teste vem da falha real, não da imaginação
O melhor teste-que-falharia nasce de um erro que você viu o modelo cometer (Módulo 4.2: testar → achar falha real). Inventar testes para regras que você "acha" que vai precisar é antecipação — exatamente o que a Trilha 4 combate.
Sem teste, a regra não entra
Esta é a disciplina de entrada: o prompt tem um portão, e o teste é a chave. Regra sem teste fica na fila — não no prompt. Parece rígido, mas é o que mantém o prompt pequeno: você só paga pelo que comprovadamente precisa.
✓ ENTRA no prompt
- •Tem um teste que falha sem ela, hoje
- •Corrige uma falha que você observou
- •O teste passa depois de adicioná-la
- •Carrega seu porquê ao lado (Tópico 4)
✗ BARRADA (fica na fila)
- •"Acho que pode dar problema um dia"
- •O prompt já passa sem ela (teste inútil)
- •Copiada de outro prompt "por garantia"
- •Reforço enfático sem caso (CRITICAL!!!)
⚠️ O custo invisível da regra sem teste
Cada regra sem teste é uma dívida. Ninguém sabe se ela ainda faz algo, então ninguém ousa removê-la — e o prompt cresce sem nunca encolher. Daqui a seis meses, você terá 40 regras e medo de tocar em qualquer uma. O teste é o que dá permissão para remover: se o teste passa sem a regra, ela sai.
Sem porquê, a regra não generaliza
O segundo portão liga direto com o Padrão 3 — Regra com Porquê (Ficha 3). Uma proibição seca ("never X") é obedecida ao pé da letra mas falha em variações: o modelo não tem a intenção, só o binário compilado. Anexar o porquê é entregar o código-fonte da regra.
✗ Sem porquê (não generaliza)
NEVER use NEDA helpline.O modelo trata como preferência arbitrária e "corrige" para o recurso mais famoso na primeira variação.
✓ Com porquê (generaliza)
direct users to the National Alliance for
Eating Disorders helpline instead of NEDA,
because NEDA has been permanently
disconnected.Anthropic — claude-fable-5.md (~L132). O "because" vira política: é fato, não gosto.
O porquê também é o que o teste verifica
Repare na simbiose: o teste define o caso de falha; o porquê explica o princípio. Quando você escreve um segundo teste numa variação nova, é o porquê — não a letra da regra — que diz qual deveria ser o comportamento esperado. Sem o porquê, você não saberia o que o novo caso deveria fazer.
Exceção: limites duros de segurança
Em fronteiras onde detalhar o porquê ensinaria o contorno, declara-se o princípio, não a mecânica de detecção (Ficha 9, antipadrão "regra-mecânica de segurança"). O porquê continua existindo — só não expõe o mapa do contorno.
A suíte mínima, vinculada ao changelog
O entregável deste módulo é uma suíte mínima de testes vinculada ao changelog. Mínima porque há um teste por regra que merece existir — nem mais, nem menos. Vinculada porque cada entrada do changelog (Módulo 4.2) aponta para o teste que justificou aquela mudança. Changelog e suíte são duas faces da mesma decisão.
CHANGELOG.md
v0.4 + regra "prefira editar a criar" → T-007 (padrão: Regra com Porquê)
v0.5 + regra "confirme antes de gerar" → T-011 (padrão: Contrato de Ferramenta)
v0.6 ~ consolidação: 3 regras → 1 → T-007,T-009,T-011 ainda passam
testes/
T-007-nao-criar-arquivos.md (entrada · esperado · falha-sem · critério)
T-009-tom-conciso.md
T-011-confirmar-geracao.md
prompt-v0.6.md
cada regra aponta o T-NNN que a sustenta, em comentárioA suíte é o orçamento de regras
Numa rodada de consolidação (Módulo 4.2: a cada 3 adições, 1 consolidação), a suíte é o seu critério objetivo: você pode fundir três regras em uma desde que os três testes continuem passando. Se um quebra, a consolidação foi longe demais.
É exatamente o que faz a evolução real — o salto Opus 4.8 → Fable 5 reduziu linhas mantendo comportamento. Sem testes, "mantendo comportamento" é fé; com testes, é fato.
✓ Suíte vinculada
- •Cada teste tem um ID estável (T-NNN)
- •Cada changelog cita o teste que o justifica
- •Cada regra no prompt aponta seu T-NNN
✗ Suíte solta
- •Testes sem ligação com regras
- •Changelog que não cita testes
- •Não dá pra saber o que cada regra protege
Medir por testes, não por opinião
A regra de ouro existe por um motivo maior que organização: ela espelha a direção que os fornecedores tomaram. A indústria saiu de "mais regras, mais ênfase" para "menos regras, melhor justificadas, comprovadas por avaliação". Quem mede por testes está do lado certo dessa história.
"Essa mudança melhorou o prompt?" — duas formas de responder
"Parece melhor", "li e gostei", "está mais completo". Não reproduzível, não comparável, vulnerável a quem fala mais alto. É como os prompts inchavam: cada um adicionava o que achava.
"12/12 testes passam, e agora com 18 linhas a menos." Reproduzível, comparável, independente de quem escreveu. É a rodada final do projeto (Módulo 4.4): consolidar medindo por testes, não por opinião.
🧭 A direção que você está espelhando
- •De regras negativas para princípios com porquê — "never X" virou "Claude evita X porque Y".
- •De empilhar para consolidar — comportamento mantido com menos linhas (Padrão 12).
- •De ênfase inflada para evidência — quando tudo é CRITICAL, nada é; o teste substitui o grito.
✅ Resumo do Módulo
- ✓Regra de ouro: toda regra precisa de porquê documentado E teste-que-falharia — um AND, não um OR
- ✓O teste-que-falharia tem 4 campos: entrada · esperado · falha-sem-regra · critério
- ✓Sem teste a regra não entra — e o teste é o que dá permissão para remover depois
- ✓Sem porquê a regra não generaliza (Padrão 3, Ficha 3) — o porquê guia os testes novos
- ✓A suíte mínima vincula changelog ↔ teste ↔ regra; é o orçamento na consolidação
- ✓Medir por testes, não por opinião — espelhando a direção dos fornecedores
🧪 Entregável deste módulo
Suíte mínima de testes vinculada ao changelog: um T-NNN por regra que merece existir, cada um com seu porquê.
Próximo: Módulo 4.4
Projeto final — system prompt versionado: prompt + changelog (cada mudança rotulada pelo padrão) + testes, com qualidade medida por menos linhas mantendo o comportamento.