Skip to main content

Quality as Architecture

In one line: Make quality the path of least resistance — enforced by hooks, agents, and skills, not by remembering to be disciplined.

What: Quality enforcement is built into the infrastructure as automated structural constraints, not maintained through discipline, review guidelines, or team agreements. High-quality work is the easy path; low-quality work takes extra effort.

Why: Discipline-based quality is fragile — it depends on everyone remembering every rule, every time, under deadline pressure. With AI it is doubly fragile: the AI has no intrinsic motivation to follow quality practices and obeys instructions literally. Tell it to write tests and it does; omit that, or say "skip tests for now," and it complies without objection.

Architecture-based quality removes the volition by making each decision structural — and each decision is made once, when the control is configured, then applies without anyone remembering it:

  • Hooks run automatically — the post-edit hook lints every save; the pre-push hook blocks a push when tests fail.
  • Agents review automatically — API-touching changes get the API reviewer, schema changes get the migration reviewer.
  • Memory persists automatically — decisions, debt, and standards survive across sessions, so conventions are not re-explained each time.
  • Skills enforce process automatically — skipping a phase means working around the tooling, which is more effort than following it.

The net effect inverts the usual dynamic: quality violations require more effort than quality compliance.

Evidence: Each control names a mechanism, not a habit. Mocking requires a MOCK APPROVED annotation or review flags it; tenant isolation lives in database-level FORCE ROW LEVEL SECURITY so it holds even for a superuser connection; schema changes go through migrations, never a manual ALTER TABLE; audit trails use append-only tables the database itself refuses to mutate. The guarantee never depends on application code being correct. See appendix-e-hooks.md for the gate architecture.

How: The quality architecture has four layers:

  1. Instruction layer (CLAUDE.md + Memory) — Rules that shape AI behavior at session start. "No mocking by default." "Always use Alembic." "No time.sleep() in tests." These are read once and applied throughout the session.

  2. Process layer (Superpowers Skills) — Workflow structure that prevents phase-skipping. The verification-before-completion skill does not allow marking a task complete without test evidence. The writing-plans skill does not produce implementation code — it produces a design artifact.

  3. Hook layer (PreToolUse, PostToolUse, Stop) — Automated checks that run at specific trigger points in the development flow. Post-edit linting. Pre-push test gates. Stop-time verification prompts.

  4. Agent layer (Reviewer Agents) — Specialized review agents that check for domain-specific quality: API consistency, security patterns, compliance requirements, migration correctness. These provide automated second opinions that do not suffer from reviewer fatigue.

These layers are independent and redundant. A quality failure must pass through all four layers undetected to reach the codebase. This defense-in-depth approach is borrowed from security engineering — the principle that no single control should be the sole protection against any category of failure.