✅ Tests and the documented why
The golden rule
The discipline that separates a prompt that grows healthily from one that rots into scattered rules: every rule needs a documented why and a test that would fail without it. Without a test, the rule doesn’t make it in. Without a rationale, it doesn’t generalize. You’ll install this gate and build the minimal test suite for your own prompt.
Detailed content
The golden rule
There is a single sentence that underpins the entire culture of this track: every rule added needs a documented why AND a test that would fail without it. They are two requirements joined by a E — not a OR. Failing either of the two blocks the rule. It’s a gate, not a suggestion.
⚖️ The two gates, in series
🧪 Gate 1 — Test
There is a concrete case that breaks today, and what would this rule fix? If you can’t write that case, the rule solves an imaginary problem. Without a test, it doesn't come in.
📝 Gate 2 — Why
The rule carries the intent in text, alongside it? Without the why, the model follows the letter and violates the spirit in new cases. Without the why, it doesn't generalize.
Why both? Because each one covers a different failure. The test protects against speculative rules (you think you need it, but you don't). The reason protects against fragile rules (work in the case you saw, fail in the next one). Together, they turn "guesswork" into engineering.
Why this is a "golden rule"
It’s the only rule you apply to itself while writing the prompt—a meta-rule. It doesn’t live in the product prompt; it lives in your process. It’s what keeps the prompt onion (Track 1) from happening to you.
Write the test that would fail
A “test-that-would-fail” isn’t a code unit test — it’s a input case + expected behavior, written so that, without the rule, the model gets it wrong; with the rule, gets it right. If the prompt already passes without the rule, the test is useless and so is the rule.
How to build the case — 4 fields
- 1.Input — the exact message/context that triggers the problem. Concrete and easy to copy.
- 2.Expected — the desired, observable behavior (not "be better," but "doesn't create a new file").
- 3.Failure without a rule — what happens TODAY without the rule. You need to have seen it happen.
- 4.Approval criteria — how you decide pass/fail unambiguously.
# 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)The test comes from a real failure, not imagination
The best test that would fail comes from a mistake you saw the model to commit (Module 4.2: test → find a real failure). Inventing tests for rules you "think" you'll need is anticipation — exactly what Track 4 addresses.
Without a test, the rule doesn't get included
This is the input discipline: the prompt has a gate, and the test is the key. A rule without a test stays in the queue — out of the prompt. It may seem rigid, but this is what keeps the prompt small: you only pay for what you demonstrably need.
✓ ENTERS the prompt
- •There is a test that fails without it, today
- •Fix a failure you observed
- •The test passes after adding it
- •Carries its rationale alongside it (Topic 4)
✗ BLOCKED (stays in the queue)
- •"I think this might cause a problem someday"
- •The prompt already passes without it (useless test)
- •Copied from another prompt "just in case"
- •Emphatic reinforcement without a case (CRITICAL!!!)
⚠️ The invisible cost of an untested rule
Every rule without a test is debt. No one knows whether it still does anything, so no one dares remove it—and the prompt keeps growing without ever shrinking. Six months from now, you’ll have 40 rules and be afraid to touch any of them. The test is what gives it permission to remove: if the test passes without the rule, remove it.
Without a reason, the rule doesn't generalize
The second gate connects directly to the Pattern 3 — Rule with a Reason (Sheet 3). A blunt prohibition ("never X") is obeyed literally but fails on variations: the model doesn’t have the intent, only the compiled binary. Including the reason is like handing over the rule's source code.
✗ Without the why (doesn't generalize)
NEVER use NEDA helpline.The model treats it as an arbitrary preference and "corrects" it to the most famous feature in the first variation.
✓ With the why (generalizes)
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). The "because" becomes policy: it's a fact, not a preference.
The reason is also what the test checks
Notice the symbiosis: the test defines the failure case; the reason explains the principle. When you write a second test for a new variation, it’s the why — not the letter of the rule — that tells you what the expected behavior should be. Without the why, you wouldn’t know what the new case should do.
Exception: hard safety limits
At boundaries where explaining why would teach how to work around them, state the principle, not the detection mechanism (Card 9, anti-pattern "mechanical safety rule"). The reason still exists — it just doesn't reveal the bypass map.
The minimum test suite, linked to the changelog
The deliverable for this module is a minimal test suite linked to the changelog. Minimal because there’s one test for each rule that deserves to exist—no more, no less. Linked because each changelog entry (Module 4.2) points to the test that justified that change. The changelog and test suite are two sides of the same decision.
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árioThe test suite is the rule budget
In a consolidation round (Module 4.2: for every 3 additions, 1 consolidation), the suite is your objective criterion: you can merge three rules into one as long as all three tests continue to pass. If one breaks, the consolidation went too far.
It’s exactly what real evolution does—the jump from Opus 4.8 → Fable 5 reduced the number of lines while preserving behavior. Without tests, “preserving behavior” is faith; with tests, it’s fact.
✓ Linked suite
- •Each test has a stable ID (T-NNN)
- •Each changelog entry cites the test that justifies it
- •Each rule in the prompt points to its T-NNN
✗ Standalone suite
- •Tests not tied to rules
- •Changelog that doesn’t cite tests
- •There's no way to know what each rule protects
Measure with tests, not opinions
The golden rule exists for a reason bigger than organization: it mirrors the direction vendors took. The industry has moved from “more rules, more emphasis” to “fewer rules, better justified, proven through evaluation.” Those who measure with tests are on the right side of that story.
"Did this change improve the prompt?" — two ways to answer
"Seems better," "I read it and liked it," "it's more complete." Not reproducible, not comparable, vulnerable to whoever speaks loudest. That's how prompts got bloated: each person added what thought.
"12/12 tests pass, and now with 18 fewer lines." Reproducible, comparable, independent of who wrote them. This is the project's final round (Module 4.4): consolidate by measuring with tests, not opinions.
🧭 The direction you’re mirroring
- •From negative rules to principles with reasons — "never X" became "Claude avoids X because Y".
- •From piling on to consolidate — behavior preserved with fewer lines (Pattern 12).
- •From inflated emphasis to evidence — when everything is CRITICAL, nothing is; testing replaces shouting.
✅ Module Summary
- ✓Golden rule: every rule needs a documented reason AND a test that would fail — an AND, not an OR
- ✓The test-that-would-fail has 4 fields: input · expected · failure-without-rule · criterion
- ✓Without a test, the rule doesn't get included — and the test is what gives you permission to remove it later
- ✓Without a reason, the rule doesn't generalize (Pattern 3, Card 3) — the reason guides new tests
- ✓The minimum test suite links changelog ↔ test ↔ rule; it’s the consolidation budget
- ✓Measure with tests, not opinions — mirroring the providers' direction
🧪 Module Deliverable
Minimum test suite linked to the changelog: one T-NNN per rule that deserves to exist, each with its own reason.
Next: Module 4.4
Final project — version-controlled system prompt: prompt + changelog (each change labeled by pattern) + tests, with quality measured by less lines while preserving behavior.