White paper · Developers · July 2026

The Contract in the Repo

Governed context for coding agents: why your CLAUDE.md does not work, and what to do instead.

Inside this paper

  • The problem you already haveWhy a rules file stops being followed.
  • The rest of the stackProse without enforcement, or enforcement without semantics.
  • The ideaVersioned contracts in every repository.
  • Six documentsWhich are authored, generated and imported.

Instruction files are prose the model samples, not rules it obeys.

The problem you already have

You wrote a rules file for your coding agent. It started at 40 lines. It is 400 now. Somewhere around line 80 the agent stopped following it — not all of it, just an unpredictable subset, which is worse. You know this because last Tuesday it typed a monetary value as a float again, and the rule about that has been in the file since March.

This is not a prompt-engineering failure. Instruction files are prose the model samples, not rules it obeys. They have no schema, no versioning, no enforcement, and no way to know when they have gone stale — a rule from six months ago that no longer matches the code is still shaping every response today. And you are probably maintaining three near-copies of the same file that drift from each other as well as from the code.

The rest of the stack has the same shape

LayerWhat it doesWhere it stops
Spec-driven developmentGoverns generationThe spec dies at merge, with nothing reconciling specs against the code they produced
Code graphs and context serversImprove what the agent seesRetrieval is not authority: the graph says what exists, not what is permitted
Architecture lintThe one deterministic layer that worksChecks structure — who imports whom — never semantics
AI code reviewReviews the diffNon-deterministic: same diff, different findings on different runs
Every layer is either prose without enforcement or enforcement without semantics.

The idea in one paragraph

Put a small set of SIGN™ documents in every repository — structured, human-readable, versioned contracts that state what the module is, its architecture, its dependencies, its public surfaces, its standards, and its decisions. Compile them in CI. Generate what can be generated from code, so those parts cannot drift.

Six documents in every repository

01

Overview

What the service is, for whom, deployed how.

Authored
02

Architecture

Layers, boundaries, invariants.

Authored
03

Dependencies

The dependency graph, from csproj or package.json.

Generated from code
04

Interfaces

Public surfaces from code or OpenAPI, drift-checked.

Generated from code
05

Standards

Repo-specific deltas only; shared standards referenced, never copied.

Authored
06

Decisions

One per decision; imports land as drafts until a person promotes them.

Imported

The generated documents are emitted from the code on every compile, so they cannot drift from it.

Read the full paper

The complete paper: the rules-file problem, the stack analysis, and the six-document contract in full.

Related

Explainer

Code

A coding agent drifts from the standard in a single session, then works from the governed contract instead.

Explainer

What is SIGN™

Prose an agent has to interpret, next to the same rule expressed as SIGN™.