implementation-standards git:20261022.c5514d3A

Immutable. This exact content never changes and is served at /api/v1/blob/d3d9cf18830c4b15.

---
name: implementation-standards
description: "Engineering criteria for implementation: SOLID, Clean Code, patterns, comment anchors, quality signals and simplification-first debt."
license: MIT
---

# Implementation standards

> Load this skill before writing or reviewing code. It is the **source of engineering criteria**;
> `.atlas/agents/engineer.md` is only a summary.

---

## SOLID

- **S** — one reason to change per class; one use case per application service.
- **O** — extend through composition, polymorphism and dependency injection before inheritance.
- **L** — subtypes must be substitutable without breaking invariants; prefer composition.
- **I** — keep interfaces small and specific to their consumer; no god interfaces.
- **D** — dependencies point toward the domain; high-level modules do not depend on low-level ones.
- Supporting concepts: cohesion, low coupling, encapsulation.

## Design patterns

- Apply them **only when the problem justifies it** and they reduce complexity.
- Premature abstraction is debt, just like duplication.
- Common: Factory, Strategy, Repository, Specification, Observer, Builder.

## Clean Code

- Meaningful names that reveal intent; no cryptic abbreviations.
- Small functions that do one thing.
- No dead, commented-out or unrefactored code.
- DRY with judgment: do not abstract for the sake of abstracting.

## Comment anchor (mandatory)

- Comments explain **why**, never what or how.
- Reference an **ADR** (`adr/NNNN-...`) or functional documentation.
- **Never** reference `openspec/specs/` (they are deltas that get archived).
- **Never** reference roadmaps, planning documents or other projects as the justification.
- If no ADR anchors the decision, the comment is **self-contained**: decision and reason, here and now.

## Quality controls are signals, not goals

- Do not delete blank lines, split methods without cohesion or add trivial tests to pass a number.
- Do not raise the CRAP threshold so a change passes.
- Do not exclude files with real logic from coverage or CRAP.
- If a touched file has pre-existing lint violations, resolve them; do not leave debt "because it was
  not mine".
- If a limit is close, **refactor** or **document why** in the commit.

## Technical debt: simplification first

1. Extract Method / Extract Class.
2. Decompose Conditional / Replace Conditional with Polymorphism.
3. Introduce Parameter Object / Preserve Whole Object.

- Protected by the existing tests (green before and after).
- Additional tests are a **complement**, not a substitute for reducing complexity.
- Do not mask a complex method with tests that only cover the happy path.

## Tests

- Test behavior, not implementation details.
- No disabled tests, magic sleeps or trivial assertions.
- Cover error paths and business rules, not only the happy path.