diff --git a/documents/patterns/test-dont-yell.md b/documents/patterns/test-dont-yell.md new file mode 100644 index 0000000..b7456c3 --- /dev/null +++ b/documents/patterns/test-dont-yell.md @@ -0,0 +1,28 @@ +--- +authors: [emmanuel_lin_toulemonde] +--- + +# Test, Don't Yell + +## Problem + +Emphatic instructions ("NEVER do X", "ALWAYS follow Y", "ABSOLUTELY respect this") are unreliable — AI ignores them over long sessions, forgets them as context grows, or complies superficially. Stronger rules don't improve reliability; they just consume context. + +## Pattern + +Replace emphatic instructions with automated tests or linters AI can run to verify its own output. Instead of telling AI what to do, give it a way to *check* that it did it. + +This turns a subjective instruction into a deterministic assertion. AI gets concrete, unambiguous feedback (pass or fail) without relying on memory or interpretation of rules. + +**AI can write these checks itself.** Describe the constraint, ask AI to implement the validation. Once implemented, verify it passes on correct code and fails when a violation is introduced. The test suite becomes the living specification. + +For every standard or architecture decision, ask: can this be expressed as an automatic validation? + +## Example + +**Cloud resource name length** — instead of writing `Cloud resource names must be shorter than 63 characters`, add a test that validates all declared resource names. AI runs it and gets a clear failure with the offending name. + +Other applications: +- `Every data product must have a valid data contract` → A test that checks the contract file exists and matches the expected schema. +- `Always follow this architecture pattern` → An import linter that verifies dependencies only flow in the allowed direction. +- `Database migrations must be reversible` → A test that runs each migration up then down and checks the schema is unchanged. diff --git a/documents/relationships.mmd b/documents/relationships.mmd index d3942d6..345d7fd 100644 --- a/documents/relationships.mmd +++ b/documents/relationships.mmd @@ -124,6 +124,12 @@ graph LR obstacles/selective-hearing -->|related| obstacles/context-rot obstacles/negative-bleedthrough -->|related| obstacles/selective-hearing patterns/point-the-target -->|solves| obstacles/negative-bleedthrough + patterns/test-dont-yell -->|solves| obstacles/selective-hearing + patterns/test-dont-yell -->|solves| anti-patterns/obsess-over-rules + patterns/test-dont-yell -->|solves| anti-patterns/perfect-recall-fallacy + patterns/test-dont-yell <-->|similar| patterns/habit-hooks + patterns/test-dont-yell <-->|similar| patterns/offload-deterministic + patterns/test-dont-yell -->|uses| patterns/hooks %% Obstacle → Anti-pattern relationships (related) obstacles/obedient-contractor -->|related| anti-patterns/silent-misalignment diff --git a/website/config/authors.yaml b/website/config/authors.yaml index efb3519..8030574 100644 --- a/website/config/authors.yaml +++ b/website/config/authors.yaml @@ -23,3 +23,7 @@ rdmueller: juan_michelini: name: Juan Michelini github: juanmichelini +emmanuel_lin_toulemonde: + name: Emmanuel-Lin Toulemonde + github: ELToulemonde + url: https://eltoulemonde.fr/en