Quality Code Specifications

Prescriptive standards for how new projects should be built. These are not records of past decisions — they are codified patterns for rapid development of small projects with rigorous code quality.

The focus is application development: servers, CLIs, consumers, data processors, one-shot scripts. Frameworks and libraries have different organizational needs and are not covered here.

Values

• Complexity isolation — every piece of complexity has one home
• Inversion of control — depend on abstractions, not concretions
• Law of Demeter — talk to your friends, not your friends' friends
• One obvious place for everything — no ambiguity about where code lives
• No fat dependencies — understand what you import

Specs

Architecture

• Hexagonal Architecture — Three layers, strict dependency rule, domain at the center
• Composition Root — Single wiring point, constructor injection, DI when justified
• Use Case Pattern — One class per use case, application layer as explicit seam
• Port Definitions — Protocol-based ports, explicit adapter inheritance

Domain

• Domain Value Objects — Frozen dataclasses, validation in __post_init__, derived properties
• Domain Exception Hierarchy — Flat hierarchy, bidirectional translation at adapter boundaries

Testing

• Testing Strategy — Mirror structure, one behavior per test, fixtures over setup/teardown
• Mock Separation — Creation, injection, and configuration as three separate concerns
• Fixture Centralized Construction — Factory fixtures with setdefault overrides

Tooling

• Project Tooling — uv, src/ layout, pre-commit with ruff, mypy, and pytest
• Typing Discipline — Strict mypy on source, @final, @override, relaxed tests
• Minimal Dependencies — Small focused packages, prefer the standard library