# Principles

Four principles governing engineering choices across all Corviduo
projects. Common lodestar: **fitness-for-purpose**. Each principle
rejects a different substitute goal that disguises itself as virtue.

These are user-level defaults that originate at `~/.claude/CLAUDE.md`,
duplicated here so they live with the codebase and are visible to
humans browsing the repo (or AI tooling that doesn't load the
user-level CLAUDE.md). When the user-level statement is amended,
this file is backported.

---

## 1. Excellence over uniqueness

Pick the shape that's right for the problem, not the shape that's new.
If uniqueness is a byproduct of excellence, so be it; do not target it.

*Rejects:* novelty-as-goal.

## 2. Explicit over implicit

Make load-bearing assumptions, constraints, and coupling visible.
Idiomatic implicitness (language conventions, well-known protocols)
is fine — the rule targets *invisible* implicitness, not all of it.
Cost of explicitness is verbosity; cost of invisible implicitness is
undetectable coupling. Pay the cost where auditability beats the tax.

*Rejects:* cleverness-as-goal.

## 3. Elegance is a byproduct, not a target

Excellent engineering often produces elegant results; targeting
elegance directly tends to produce cleverness, which is a different
thing. Review test: *"fit-for-purpose, debuggable, consistent"* —
not *"feels nice."*

*Rejects:* beauty-as-goal.

## 4. Action-relevance over thoroughness

Before investigating, ask whether the answer would change the action.
If both outcomes lead to the same default, skip the question.

*Rejects:* thoroughness-as-goal.

---

## What this file is, and isn't

These principles are *what to optimize for*. They sit above two other
layers:

| Layer | Where it lives | What it answers |
|---|---|---|
| **Principles** (this file) | `PRINCIPLES.md` + `~/.claude/CLAUDE.md` § Core principles | *What to optimize for* across all work |
| **Behavioral guidelines** | `CLAUDE.md` § BEHAVIORAL GUIDELINES | *How to operate session-to-session* (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution) |
| **Workflow mechanics** | `CLAUDE.md` § Project conventions + the contract format, TDD cycle, etc. | *Project-level mechanics* (contracts-first, TDD vertical slices, no-backwards-compat-until-v1.x, persistent-memory commit-along) |

Don't conflate the three layers. Workflow rules tell you what to do
mechanically; behavioral guidelines tell you how to think during a
session; principles tell you what *good* looks like across all of it.

A workflow rule can be amended without touching the principle that
motivates it. A principle changes rarely — when one does, it ripples
through every other layer.