Code Agreements

Code Agreements

How I want code written, across all of my projects.

What this is

These files are read before writing code, so that guidance given once doesn't have to be given again. Some of it was set down up front; most of it accumulates as things get settled during development sessions — usually when I correct, simplify, or rename something.

Each entry records what was actually settled, with the reasoning attached, so a future session can read it and skip the argument. It is not a style guide written from first principles.

What to read

Always read `general.md`. It applies to every language, and it holds the design, comment, and process guidance that is easiest to assume you already know.

Then read the file for **every** language the change touches — plural, not one. A change spanning a C# backend and a TypeScript front end needs `csharp.md` and `typescript-react.md` both.

Layout

File	Holds
general.md	Language-agnostic design and process guidance
csharp.md	C# / .NET
typescript-react.md	TypeScript, React, and the web front end

Route an entry by where it **applies**, not where it came up: a design principle that surfaced in C# still belongs in `general.md`.

The bar for a new entry

These files are read in full before every coding task, so each rule taxes every future session whether or not it applies. A new entry has to be **unguessable** (a competent implementer wouldn't arrive at it unaided) and **recurrent** (it fires often, not just conceivably). Most candidates fail one or the other. One entry is a normal yield from a session; five means a session's narrative is being converted into rule-shaped prose.

The entries that earn their keep are mostly preferences — arbitrary, unguessable, two lines. Things I _discovered_ whil