Mostly Done.
Contents

3 Turn principles into executable contracts

A repository can contain excellent prose about correctness and still ship violations of every sentence. A principle becomes operational only when breaking it produces a failure that stops the work. Your codebase is strongest where its most important beliefs have names in the test suite.

3.1 Name the thing that must remain true

Consider an editor whose architecture document declares the source text authoritative. The claim gets teeth from named suites: one defends byte-lossless projection transitions, one defends a caret-line viewport invariant, one requires patch rendering and full rendering to agree.

The names matter. They give future agents a vocabulary for the architecture. Do not move the caret’s line when the projection changes is easier to preserve as a named invariant than as an emergent property spread across event handlers.

Rendered output takes the same treatment. A diagram engine can convert visual complaints into named geometry rules such as label-on-fixture, label-crowds-edge, and edges-doubled. These two labels are crowding each other becomes a regression test named after the observed defect, plus a linter rule that can detect similar geometry elsewhere. Taste becomes executable.

3.2 Ratchets, not snapshots

A good regression test is a ratchet. It lets quality improve and prevents a known failure from returning.

For a rendering defect, the strongest pattern has two layers: fix the generator so it no longer produces the bad geometry, then add a linter or invariant that rejects the same class of bad geometry if another generator produces it later. The first layer corrects the present example. The second protects the concept.

A diagram engine repaired label crowding this way. The generator reserves a 14-point label stub on each side of an edge; the linter rejects any scene where the stub falls below 10 points. The gap is deliberate. The generator aims for comfort while the ratchet forbids only the known failure. A hostile fixture reconstructs the original crowded scene and confirms the linter still catches it.

The distinction matters because agents are excellent at satisfying a narrow failing test. If the test encodes only the exact fixture, an agent can produce a local patch that leaves the underlying family of defects untouched. A named invariant changes the optimization target.

3.3 Contracts should compare the fields that matter

An executable contract creates false confidence when its comparison is incomplete.

Take an editor with an incremental parser whose equivalence helper reparses the document source from scratch and compares the incremental result field by field: blocks, outline, footnotes, stats, source hash, and review metadata. The last field earned its place. The helper originally omitted it, so a fast path could leave a suggestion mark’s absolute byte range unshifted while the whole suite stayed green. A real semantic difference passed as equality until the comparison named the field.

The repair went beyond adding the assertion. A companion test records the safety decision that typing near a live mark abandons the fast path entirely, because the block-shifting optimization cannot update an absolute range. If the fast path runs anyway, two comparisons now fail instead of zero.

An equivalence test proves only that the fields it names agree. Derive the contract from semantics, not convenience, and review the comparison helper as part of your trust boundary.

3.4 Guardrails should be hard enough to lean on

The strongest repositories treat pre-commit gates as ground truth. Complexity ceilings, pinned linters, tests, and race checks are not suggestions. The work changes until it passes, and --no-verify is not a route around the system.

That hardness creates leverage. You can delegate broadly because the repository rejects certain classes of debt automatically. An agent can refactor a high-complexity function during an unrelated change because the gate makes the debt visible at the moment it becomes relevant.

Hard guardrails also create friction. Suppose a complexity gate with no baseline blocks the same class of edit several times. The correct response is neither blind obedience nor bypass: respect the gate for the immediate work, and record the repeated papercut as a defect in the guardrail itself.

A guardrail that cannot be criticized becomes ritual. A guardrail that can be bypassed casually becomes theater. Obey it now; improve it deliberately.

3.5 Make extension obligations explicit

Consider an editor built from typed blocks and guarded by two invariant suites. Its most useful repository rule fits in one line: when adding a block type, extend both suites. The rule turns architecture into a checklist at the point of change. The agent does not need to infer every hidden obligation from the whole codebase; the repository says which contracts define completeness.

You can write the same kind of obligation for your own domains:

Keep the list short enough to remember and strict enough to catch drift.

3.6 A contract hierarchy

Not every property deserves the same kind of check. A useful hierarchy:

  1. type and schema contracts for shape;
  2. unit invariants for local semantics;
  3. property and differential tests for broad input spaces;
  4. integration tests for boundaries between components;
  5. golden or perceptual checks for rendered output;
  6. release checks for the artifact users actually receive.

Agents can satisfy the lower levels while missing the higher ones, which is why agentic work needs all six. A parser can type-check and pass its unit fixtures yet disagree with a reference implementation on escaped input. A branch can pass every test while the merged tree fails, and a release workflow can succeed while the live site serves an old version.

The goal is a short, named path from each important claim to the nearest executable contradiction.

use ← and → to turn pages