Principles

Brief and Alive

Documentation must be short enough to read in one sitting and current enough to be trusted. When the system changes, the doc is replaced, not appended. No historical backfill.

Structured for Both Humans and AI

Numbered folders, README indexes, one concept per file. AI reads the README, identifies the relevant file, and loads only that file. Small files load into AI context entirely. Large files get truncated.

Opinionated, Not Neutral

“Use X. Y is wrong because Z.” Actionable. “Consider X or Y depending on your needs.” AI picks arbitrarily. Every doc and instruction should have a clear recommendation.

Enforceable Over Advisory

If a rule matters, enforce it. Advisory < Instruction < Build rule < Runtime check. Move rules up the enforcement ladder whenever possible.

Concrete example with Guid.CreateVersion7() vs Guid.NewGuid():

Advisory: a doc says “prefer Guid.CreateVersion7().” AI follows this sometimes.
Instruction: an .instructions.md file with applyTo: '**/*.cs' says “Use Guid.CreateVersion7(). Guid.NewGuid() is wrong.” AI follows this every time the instruction is loaded.
Build rule: an analyzer that fails on Guid.NewGuid(). AI cannot produce code that violates this.

Tooling as Infrastructure

Every raw CLI command is an opportunity for error. Wrap multi-step operations into single make targets. Pre-commit hooks run quality checks automatically. AI operates inside a well-defined toolbox. The developer defines the toolbox.

Verification Over Trust

A passing test does not mean the system works. A successful HTTP response does not mean the internals are correct. The trace is the truth. Human-defined criteria with binary outcomes replace subjective AI scoring.

Read the full principles →