# Leonard Cremer — dev principles for any project

My portable engineering principles for any AI-assisted project. Paste into a new project's AI context at kickoff to establish the prior.

*Type:* `developer-principles`

## Content

### summary

Portable engineering principles for AI coding agents. Two layers: strategic principles for how you design the system, and behavioural rules for how an AI agent acts inside a task. Paste this URL into any new project's AI context at kickoff to establish the prior.

### meta_principle

The system holds the load-bearing discipline so the human doesn't have to remember it. Documentation explains why; enforcement guarantees what. Every principle in this lens earns its keep twice — as AI-facing guidance and as a machine-enforced check (lint, schema, hook, validator). A principle without its enforcement counterpart is incomplete and will eventually be violated.

### principles

- - **name**: Encode discipline as enforcement, not documentation
  - **rule**: Every load-bearing rule needs a hook, lint, validator, or schema constraint that breaks the build when violated. A pattern that lives only in a guide will be violated.
  - **applies_when**: Onboarding a new convention, fixing a recurring bug class, or formalizing a code-review nit that keeps coming up.
  - **evidence**: Custom lint rules for repeating violation shapes; validation schemas generated from DB constraints; server-side enforcement that rejects mutations missing required metadata.
- - **name**: Single source of truth, derive everything else
  - **rule**: Pick one canonical representation per concept and regenerate all downstream artefacts. Never hand-maintain two representations of the same thing.
  - **applies_when**: Working with types, schemas, configuration, API contracts, or any data shape that appears in multiple places.
  - **evidence**: DB schema -> generated TS types -> generated runtime validation -> generated field configs. One source, multiple derivations.
- - **name**: Reference implementation > architectural debate
  - **rule**: When you have N similar units, polish one and make it the explicit template. Beats RFCs and abstract base classes.
  - **applies_when**: Building any system with repeating units (pages, services, layers, modules, microservices).
  - **evidence**: One canonical layer is polished and used as the explicit template; new layers copy its patterns instead of debating shape from scratch.
- - **name**: Force the human at forcing functions; automate everything else
  - **rule**: Identify the few decisions only a human can make. Build friction into the system at those points. Automate everything around them aggressively.
  - **applies_when**: Designing schemas, APIs, or workflows where some fields carry strategic meaning.
  - **evidence**: The system refuses to auto-fill fields that carry strategic meaning — testability, falsifiability, exclusion criteria, healthy bands, citations. The friction IS the strategic work.
- - **name**: Read before write; provenance on every mutation
  - **rule**: Discover IDs before referencing them; never fabricate. Stamp every mutation with who/why/when/intent. Cheap insurance against silent corruption.
  - **applies_when**: Any system where multiple agents (human or AI) mutate shared state.
  - **evidence**: Every AI-driven mutation stamps caller model, intent, and reason. IDs come from explicit list/get calls, never invented.
- - **name**: Explicit Refuse / Ask / Proceed matrix
  - **rule**: Be explicit about which violations break the system, which deserve a question, and which are fine. Conflating these produces brittleness or chaos. The 'ask' tier is where assumptions and tradeoffs get surfaced before code is written.
  - **applies_when**: Designing any guard system: lints, validators, AI behaviour rules, code-review policy.
  - **evidence**: The guard system refuses orphan entities (hard), asks for the type of object being created (forcing function), proceeds with capturing background facts silently.
- - **name**: Specialized surfaces > one monolithic assistant
  - **rule**: Carve AI surfaces along workflow boundaries. Load context lazily. The split criterion: if loading both surfaces always carries context one of them doesn't need, split. If two share more context than they differ on, merge. Always-on context drowns the signal.
  - **applies_when**: Designing AI tooling, slash commands, agents, or MCP servers.
  - **evidence**: Slash commands carved by workflow stage. Subagents carved by mutation type. MCP servers split by domain. Each has narrow scope, loaded on demand — never always-on.
- - **name**: Session-scoped state to prevent cross-contamination
  - **rule**: When multiple parallel agents or sessions write to shared state, track per-session what each touched. Otherwise attribution and ownership degrade fast.
  - **applies_when**: Multi-agent systems, parallel git work, AI sessions touching the same codebase.
  - **evidence**: Per-session append-only logs record every file each session edits. Pre-commit reads them and refuses files no session claimed.
- - **name**: Schema before story
  - **rule**: Settle the data model before the UI, the explainer doc, or the marketing copy. Polishing downstream from an ambiguous primitive is the most expensive form of avoiding the real work.
  - **applies_when**: Starting any new feature, project, or pivot.
  - **evidence**: Domain entities defined as runtime schemas with validators before any UI is built.
- - **name**: Make state changes legible at the seam
  - **rule**: Every meaningful transition (commit, deploy, decision, mutation) leaves a structured, queryable record. Free-text changelogs decay; structured trailers compose.
  - **applies_when**: Designing version control workflow, deploy pipelines, decision logs, or audit trails.
  - **evidence**: Structured commit trailers naming the work-unit and outcome each commit advances. Append-only metric records. Workflow runs as first-class entities.

### agent_behaviour_rules

- - **name**: Assumptions surfaced before code
  - **rule**: State assumptions and tradeoffs before writing code. Present multiple interpretations when the request can be read more than one way. Stop and ask when confused — a wrong assumption costs more than a clarifying question.
  - **applies_when**: Any non-trivial task where the prompt has ambiguity or hidden constraints.
  - **evidence**: Mirrors the 'ask' tier of the Refuse / Ask / Proceed matrix at task-time rather than design-time. Wrong silent assumptions are the dominant failure mode in agent-driven coding.
- - **name**: Simplicity first
  - **rule**: Write the minimum code that solves the asked problem. No speculative abstractions, defensive layers, or features beyond the request.
  - **applies_when**: Every implementation step.
  - **evidence**: Speculative code is the largest source of code that needs deleting later. The cheapest abstraction is the one you didn't write.
- - **name**: Surgical changes
  - **rule**: Touch only what the request requires. Match the existing style of the file you're editing. Don't refactor or clean unrelated code. Only delete code your change made obsolete.
  - **applies_when**: Any edit to existing files.
  - **evidence**: Drive-by refactors mix into review with the real change and make rollback hard. Style mismatches signal an outside hand and erode trust in subsequent edits.
- - **name**: Goal-driven, not step-driven
  - **rule**: Translate the task into verifiable success criteria first, then loop until they pass. Prefer criteria over step-by-step instructions when both are available — criteria survive the model getting smarter, step lists don't.
  - **applies_when**: Any non-trivial task.
  - **evidence**: Iterative verification is the model's strength; following brittle step lists is its weakness. Success criteria survive model upgrades; prescribed sequences don't.

### how_to_use

Paste this URL into any new project's AI context at kickoff. The strategic principles establish how to design the system; the agent behaviour rules establish how an AI agent should act inside a task on it. For coding surfaces (Claude Code, Cursor, etc.) the behaviour rules are the layer to load into the system prompt or equivalent.

### refresh_when

A principle stops earning its keep, or a new project teaches a new generalizable pattern. The agent behaviour rules should be reviewed after any major LLM coding model release.


## Other AetherID lenses

- **AetherID — project context** (project-context) — Paste into an AI tool working on AetherID. Front-loads what NOT to build, scope discipline, current state, and key files.
  https://aetherid.ai/leonard-cremer/aeid:019e5df4-89a1-7b30-a3c8-d2360c0c38cf

## Other RallyRacing lenses

- **Rally Racing & Century Racing — project context** (project-context) — External-facing lens for collaborators on rally racing, century racing, and the shared Dakar 2027 top-5 goal with Brian.
  https://aetherid.ai/leonard-cremer/aeid:019e5e4b-f8ae-7e32-8114-0006ce9d12cb

---
Source: https://aetherid.ai/leonard-cremer/aeid:019e6027-59bb-7683-b9eb-ba15f209b8c7