speq-code-guardrails

Code Guardrails

TDD workflow and quality guardrails. Draws on established practice, including work by R. Martin, K. Beck, B. Meyer, and Toyota's Five Whys.

Golden Rule

No production code without a failing test first. Before changing existing code that has no test, add one that captures its current behavior first.

Evidence Rule

No claim without evidence. Run command, show output, then claim.

Dependency Rule

No new dependency without confirming the standard library or an already-installed dependency cannot do it first.

TDD Cycle (London School)

RED    → Write failing test, run it, show failure
GREEN  → Minimal code to pass, run test, show pass
REFACTOR → Clean up, run test + lint, show output

Run ONLY the test you created/changed, not the full suite.

Tests

• Arrange, act, assert. One concept per test.
• The test name states the condition and the expected behavior.
• Independent and repeatable: no shared mutable state, no real clock, network, filesystem, or unseeded randomness.
• Cover every branch and every edge case: empty, single, maximum, off-by-one, transition, and each way the operation can fail.
• Assert observable behavior, never internal state.
• Pure logic is tested without doubles. Orchestration is tested with doubles at its abstractions. Adapters are tested against the real thing.
• Test code follows every rule in this document, same as production code.
• A skipped or ignored test is a defect. Fix it or delete it.

Guiding Principles

Principle	Meaning
KISS	Simplest solution that works
YAGNI	Build for now, not hypotheticals
DRY	Extract duplication on the third occurrence, not the second (Rule of Three)
Single Responsibility (SOLID)	One function = one purpose
Boy Scout	Leave code cleaner than you found it
Root Cause	Five Whys — fix the source, not the symptom

Design

• Law of Demeter: talk only to immediate collaborators
• Dependency direction, module depth, and boundary placement: see /speq-design-philosophy