speq-code-guardrails git:20260720.15e76d6A

Immutable. This exact content is served forever at /api/v1/blob/4b15a3489642dae0.

---
name: speq-code-guardrails
description: TDD cycle and code quality guardrails — failing-test-first, evidence, and dependency rules. Triggered by /speq-implement, implementer-agent, implementer-expert-agent, and code-reviewer before any implementation or review work.
---

# Code Guardrails

**Clean Code** (Martin) TDD workflow and quality guardrails.

## Golden Rule

**No production code without a failing test 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.

## Guiding Principles

| Principle | Meaning |
|-----------|---------|
| **KISS** | Simplest solution that works |
| **YAGNI** | Build for now, not hypotheticals |
| **DRY** | Extract duplication, don't copy-paste |
| **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

- Config at high levels, behavior at low levels
- Polymorphism over conditionals
- Dependency injection for testability
- Law of Demeter: talk only to immediate collaborators

## Functions

- Small and focused
- Few arguments (≤3 ideal)
- No side effects
- No boolean flags — split into separate methods

## Naming

- Descriptive, unambiguous, pronounceable
- Named constants over magic numbers
- No prefixes or type encodings

## Comments

- Public/interface methods: brief doc comment (purpose only)
- Private methods: no comments
- No inline comments — code should be self-explanatory
- No work tracking (TODOs, FIXMEs, ticket refs)

## YAGNI Checks

- Abstraction (interface, generic type, configuration value) with one implementation/caller? Inline it.
- 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 |