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
Functions
- Small and focused
- Few arguments (≤3 ideal)
- No hidden side effects: a function changes nothing its name and contract do not announce
- 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
Draws on established practice, including R. Martin (Clean Code, SOLID, Boy Scout Rule), K. Beck (TDD), and B. Meyer (Command-Query Separation).
1---2name: speq-code-guardrails3description: "TDD cycle and code quality guardrails for the implementer and reviewer agents during /speq-implement. Not for general coding."4metadata:5 source: https://skillmd.com/skills/exasol-labs/speq-code-guardrails6---78# Code Guardrails910TDD workflow and quality guardrails. Draws on established practice, including work by R. Martin, K. Beck, B. Meyer, and Toyota's Five Whys.1112## Golden Rule1314**No production code without a failing test first.** Before changing existing code that has no test, add one that captures its current behavior first.1516## Evidence Rule1718**No claim without evidence.** Run command, show output, then claim.1920## Dependency Rule2122**No new dependency without confirming the standard library or an already-installed dependency cannot do it first.**2324## TDD Cycle (London School)2526```27RED → Write failing test, run it, show failure28GREEN → Minimal code to pass, run test, show pass29REFACTOR → Clean up, run test + lint, show output30```3132Run ONLY the test you created/changed, not the full suite.3334## Tests3536- Arrange, act, assert. One concept per test.37- The test name states the condition and the expected behavior.38- Independent and repeatable: no shared mutable state, no real clock, network, filesystem, or unseeded randomness.39- Cover every branch and every edge case: empty, single, maximum, off-by-one, transition, and each way the operation can fail.40- Assert observable behavior, never internal state.41- Pure logic is tested without doubles. Orchestration is tested with doubles at its abstractions. Adapters are tested against the real thing.42- Test code follows every rule in this document, same as production code.43- A skipped or ignored test is a defect. Fix it or delete it.4445## Guiding Principles4647| Principle | Meaning |48|-----------|---------|49| **KISS** | Simplest solution that works |50| **YAGNI** | Build for now, not hypotheticals |51| **DRY** | Extract duplication on the third occurrence, not the second (Rule of Three) |52| **Single Responsibility** (**SOLID**) | One function = one purpose |53| **Boy Scout** | Leave code cleaner than you found it |54| **Root Cause** | **Five Whys** — fix the source, not the symptom |5556## Design5758- Law of Demeter: talk only to immediate collaborators59- Dependency direction, module depth, and boundary placement: see `/speq-design-philosophy`6061## Functions6263- Small and focused64- Few arguments (≤3 ideal)65- No hidden side effects: a function changes nothing its name and contract do not announce66- No boolean flags: split into separate methods67- No selector arguments of any type: an argument that picks a branch means two functions68- One level of abstraction per function: decide or do the work, not both69- A function either mutates something or answers a question, never both in one call (Command-Query Separation)70- No output parameters: return the value71- Guard clauses first. One unindented main path72- No undocumented ordering contract between calls: if a second call requires a first, make it unreachable without it7374## Errors7576- Failure is signalled by the language's own error mechanism, never a sentinel value, magic number, or in-band absent value77- Absence is explicit: an empty collection or the language's optional type, never a stand-in for a value78- Every error states what was attempted, the input that failed, and the constraint violated79- Translate a third-party error into this module's own error type at the boundary: callers never handle a provider's error taxonomy80- Never discard an error, never catch broadly: handle at one level, let the rest propagate81- Errors signal exceptional conditions, not control flow82- The failure path is written test-first, like any other behavior8384## Naming8586- Descriptive, unambiguous, pronounceable87- Named constants over magic numbers88- No prefixes or type encodings89- Types are nouns, functions are verbs, predicates read as questions90- One word per concept across the codebase91- Name length matches scope: single letters only within a few lines92- No role-suffix names that state no responsibility (Manager, Processor, Handler, Data, Info, Util)93- A name reflects what a thing is for, never how it is built: keep transport, vendor, or storage format out of it94- Domain vocabulary over generic programming vocabulary9596## Comments9798- 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 signature99- Private methods: no comments100- No inline comments: make the code self-explanatory101- No work tracking (TODOs, FIXMEs, ticket refs)102103## YAGNI Checks104105- 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.106- Feature flag or extension point nobody uses? Remove it.107108## Code Smells109110| Smell | Signal |111|-------|--------|112| Rigidity | Small changes cascade everywhere |113| Fragility | One change breaks unrelated code |114| Immobility | Can't reuse code elsewhere |115| Opacity | Hard to understand at a glance |116117## Attribution118119Draws on established practice, including R. Martin (*Clean Code*, SOLID, Boy Scout Rule), K. Beck (TDD), and B. Meyer (Command-Query Separation).