ADR-013-F: Engineering Philosophy — The 42 Commandments of Lean AI-Assisted Development

Status: Accepted Date: 2026-04-16 Decision Makers: Gautham Chellappa

Context

AI-assisted development removes the natural friction that historically prevented bloat, over-engineering, and unmaintainable code. When generating code is nearly free, discipline becomes the only constraint. Without explicit principles, AI-assisted projects inevitably reach a point where they must be scrapped and rewritten.

The 42 Commandments (42-COMMANDMENTS.md) codify 42 specific principles addressing real patterns that kill software projects. Each commandment has a failure mode it prevents and a testable criterion. 177 guardrails (10-GUARDRAILS.md) map each commandment to enforcement rules with CI/PRE/REV/ADV tiers.

Decision

Finnest follows the 42 Commandments as the engineering philosophy. Every architectural decision, ADR, code review, and technical choice is evaluated against relevant commandments. All 177 guardrails are actively enforced at their designated tier.

Document hierarchy

42-COMMANDMENTS.md          The philosophy.                 Explains WHY.
  ↓
10-GUARDRAILS.md           The enforcement matrix.         177 rules mapped to commandments.
  ↓                         Tiers: CI / PRE / REV / ADV
  ↓
CLAUDE.md (per repo)        Operational checklist.          Per-stack practical guidance.
  ↓
ADRs                        Point-in-time decisions.        Cite relevant commandments.
  ↓
Code                        Obeys guardrails.                Line-level implementation.

All four must stay aligned. If the Commandments update, the Guardrails propagate. If a new Guardrail emerges, it maps back to a Commandment.

The 7 code commandments most cited in code review

These come up in almost every review:

1. Code is a liability — every line you ship is a line you maintain
2. No speculative abstractions — wait for 2+ implementations before extracting
3. Understand every line you ship — "tests pass" is not "I understand"
4. Solve the problem you have — YAGNI; don't build for hypothetical requirements
5. Consistency over cleverness — match existing patterns, don't invent new ones
6. Delete before you add — but understand before you delete (Chesterton's Fence)
7. Three is a pattern — don't extract until you've written it three times

Commandments most load-bearing for Finnest architecture

Every ADR in this project cites at least one of:

• #2 (no speculative abstractions) — constrains hexagonal port adoption (ADR-006-F)
• #4 (YAGNI) — closes scope on GraphQL, local LLM, ABAC, multi-region, Kafka until triggered
• #11 (ubiquitous language) — one word per concept across 21 OTP apps
• #13 (every decision needs an exit path) — MCP extraction, hexagonal ports, Docker portability
• #15 (prefer boring technology) — PostgreSQL everywhere, Oban, LiveView over JS framework
• #16 (data models outlive everything) — schema design discipline, soft deletes, UUIDs
• #21 (build for your team) — 3-person team rules out microservices; OTP modular monolith sized right
• #24 (log by ID, never PII) — audit logging, structured logs, agent log hashing
• #27 (never disable security defaults) — CSRF, HEEx escape, parameterised queries, session security
• #30 (no vendor lock-in) — ADR-0004 inherited; ports everywhere
• #31 (boundaries enforced by tooling) — Boundary library enforces cross-domain rules (AR-08)
• #34 (isolate volatility) — 21 OTP apps isolate what changes at different rates

Enforcement tiers

Each of the 177 guardrails has one tier:

Tier	Meaning	Example
CI	Automated CI pipeline — violations block merge	CQ-01 (mix format), AR-07 (Boundary check), SE-11 (deps audit)
PRE	Pre-commit local tooling	CQ-01, SE-12 (gitleaks)
REV	Required in PR review	CQ-03 (test-first), AR-18 (compliance auto-block), SE-13 (PII classification)
ADV	Documented best practice; not tooling-enforced	CQ-22 (pattern matching preference), AR-06 (no premature extraction)

Alternatives Considered

Alternative	Rejected because
No explicit philosophy — rely on team judgement	AI-assisted development requires explicit discipline; judgement varies per session
Copy another project's principles verbatim (e.g. Google SRE, Netflix, Shopify)	Those principles address different problems (scale, distributed systems, e-commerce); labour-hire + AI-native needs different rules
Fewer principles — pick top 10	42 isn't arbitrary; each addresses a distinct failure mode AI-assisted development encounters. Fewer means leaks
More granular — 80+ specific rules	Guardrails already provide the granularity (177 rules); Commandments are the layer that explains why

Consequences

Positive:

• Every architectural decision has a checkable rationale — "why did we do X?" → cite Commandments
• Code review has specific language — reviewers cite rule numbers, not just preferences
• New team members have a single source of truth for "how we work here"
• CI-enforced guardrails block drift automatically (17 of 177 are CI-tier)
• Principles are stable — Finnest's 1^st file looks like the 50^th (Commandment #5)

Negative:

• 42 Commandments is a lot to learn up front
• Risk of cargo-cult adherence — citing a rule without understanding the failure mode it prevents
• Some Commandments require judgement (e.g. #7 "three is a pattern") — can create disagreement

Mitigations:

• Each Commandment includes its "failure mode" and "test" — reviewers can cite both
• Gold-standard files (Commandment #32) embody the Commandments — new developers read code, not just rules
• Guardrails tier most rules to CI/REV rather than ADV — unambiguous enforcement

Tipping points for re-evaluation:

• A Commandment proves actively harmful in practice → amend the Commandment (update all three layers: philosophy, guardrails, CLAUDE.md)
• A failure mode emerges that no Commandment addresses → add Commandment #43+

Relationship to Guardrails

This ADR is the meta-ADR — every other guardrail flows from the Commandments. The 177 guardrails in 10-GUARDRAILS.md each map to a commandment via the "Principle" column.