Code Guardrails
Clean Code (Martin) TDD workflow and quality guardrails.
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
Functions
- Small and focused
- Few arguments (≤3 ideal)
- No side effects
- No boolean flags: split into separate methods
- No selector arguments of any type: an argument that picks a branch means two functions
- One level of abstraction per function: decide or do the work, not both
- A function either mutates something or answers a question, never both in one call (Command-Query Separation)
- No output parameters: return the value
- Guard clauses first. One unindented main path
- No undocumented ordering contract between calls: if a second call requires a first, make it unreachable without it
Errors
- Failure is signalled by the language's own error mechanism, never a sentinel value, magic number, or in-band absent value
- Absence is explicit: an empty collection or the language's optional type, never a stand-in for a value
- Every error states what was attempted, the input that failed, and the constraint violated
- Translate a third-party error into this module's own error type at the boundary: callers never handle a provider's error taxonomy
- Never discard an error, never catch broadly: handle at one level, let the rest propagate
- Errors signal exceptional conditions, not control flow
- The failure path is written test-first, like any other behavior
Naming
- Descriptive, unambiguous, pronounceable
- Named constants over magic numbers
- No prefixes or type encodings
- Types are nouns, functions are verbs, predicates read as questions
- One word per concept across the codebase
- Name length matches scope: single letters only within a few lines
- No role-suffix names that state no responsibility (Manager, Processor, Handler, Data, Info, Util)
- A name reflects what a thing is for, never how it is built: keep transport, vendor, or storage format out of it
- Domain vocabulary over generic programming vocabulary
Comments
- Public/interface methods: brief doc comment stating what the method promises — purpose, and design intent or rationale when that is not self-evident from the signature
- Private methods: no comments
- No inline comments: make the code self-explanatory
- No work tracking (TODOs, FIXMEs, ticket refs)
YAGNI Checks
- Abstraction (interface, generic type, configuration value) with one implementation/caller? Inline it — unless it is a seam over I/O, nondeterminism, or a third party, or the concrete choice is expected to change. Those seams stay.
- Feature flag or extension point nobody uses? Remove it.
Code Smells
| Smell |
Signal |
| Rigidity |
Small changes cascade everywhere |
| Fragility |
One change breaks unrelated code |
| Immobility |
Can't reuse code elsewhere |
| Opacity |
Hard to understand at a glance |
Attribution
Concepts from Robert C. Martin's Clean Code: A Handbook of Agile Software Craftsmanship, adapted here.
1---2name: speq-code-guardrails3description: TDD cycle and code quality guardrails — failing-test-first, evidence, dependency, error-handling, and test-quality rules. Triggered by implementer-agent, implementer-expert-agent, and code-reviewer before any implementation or review work.4---56# Code Guardrails78**Clean Code** (Martin) TDD workflow and quality guardrails.910## Golden Rule1112**No production code without a failing test first.** Before changing existing code that has no test, add one that captures its current behavior first.1314## Evidence Rule1516**No claim without evidence.** Run command, show output, then claim.1718## Dependency Rule1920**No new dependency without confirming the standard library or an already-installed dependency cannot do it first.**2122## TDD Cycle (London School)2324```25RED → Write failing test, run it, show failure26GREEN → Minimal code to pass, run test, show pass27REFACTOR → Clean up, run test + lint, show output28```2930Run ONLY the test you created/changed, not the full suite.3132## Tests3334- Arrange, act, assert. One concept per test.35- The test name states the condition and the expected behavior.36- Independent and repeatable: no shared mutable state, no real clock, network, filesystem, or unseeded randomness.37- Cover every branch and every edge case: empty, single, maximum, off-by-one, transition, and each way the operation can fail.38- Assert observable behavior, never internal state.39- Pure logic is tested without doubles. Orchestration is tested with doubles at its abstractions. Adapters are tested against the real thing.40- Test code follows every rule in this document, same as production code.41- A skipped or ignored test is a defect. Fix it or delete it.4243## Guiding Principles4445| Principle | Meaning |46|-----------|---------|47| **KISS** | Simplest solution that works |48| **YAGNI** | Build for now, not hypotheticals |49| **DRY** | Extract duplication on the third occurrence, not the second (Rule of Three) |50| **Single Responsibility** (**SOLID**) | One function = one purpose |51| **Boy Scout** | Leave code cleaner than you found it |52| **Root Cause** | **Five Whys** — fix the source, not the symptom |5354## Design5556- Law of Demeter: talk only to immediate collaborators57- Dependency direction, module depth, and boundary placement: see `/speq-design-philosophy`5859## Functions6061- Small and focused62- Few arguments (≤3 ideal)63- No side effects64- No boolean flags: split into separate methods65- No selector arguments of any type: an argument that picks a branch means two functions66- One level of abstraction per function: decide or do the work, not both67- A function either mutates something or answers a question, never both in one call (Command-Query Separation)68- No output parameters: return the value69- Guard clauses first. One unindented main path70- No undocumented ordering contract between calls: if a second call requires a first, make it unreachable without it7172## Errors7374- Failure is signalled by the language's own error mechanism, never a sentinel value, magic number, or in-band absent value75- Absence is explicit: an empty collection or the language's optional type, never a stand-in for a value76- Every error states what was attempted, the input that failed, and the constraint violated77- Translate a third-party error into this module's own error type at the boundary: callers never handle a provider's error taxonomy78- Never discard an error, never catch broadly: handle at one level, let the rest propagate79- Errors signal exceptional conditions, not control flow80- The failure path is written test-first, like any other behavior8182## Naming8384- Descriptive, unambiguous, pronounceable85- Named constants over magic numbers86- No prefixes or type encodings87- Types are nouns, functions are verbs, predicates read as questions88- One word per concept across the codebase89- Name length matches scope: single letters only within a few lines90- No role-suffix names that state no responsibility (Manager, Processor, Handler, Data, Info, Util)91- A name reflects what a thing is for, never how it is built: keep transport, vendor, or storage format out of it92- Domain vocabulary over generic programming vocabulary9394## Comments9596- Public/interface methods: brief doc comment stating what the method promises — purpose, and design intent or rationale when that is not self-evident from the signature97- Private methods: no comments98- No inline comments: make the code self-explanatory99- No work tracking (TODOs, FIXMEs, ticket refs)100101## YAGNI Checks102103- Abstraction (interface, generic type, configuration value) with one implementation/caller? Inline it — unless it is a seam over I/O, nondeterminism, or a third party, or the concrete choice is expected to change. Those seams stay.104- Feature flag or extension point nobody uses? Remove it.105106## Code Smells107108| Smell | Signal |109|-------|--------|110| Rigidity | Small changes cascade everywhere |111| Fragility | One change breaks unrelated code |112| Immobility | Can't reuse code elsewhere |113| Opacity | Hard to understand at a glance |114115## Attribution116117Concepts from Robert C. Martin's *Clean Code: A Handbook of Agile Software Craftsmanship*, adapted here.
marconae