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
| Layer | What it does | Where it stops |
|---|---|---|
| Spec-driven development | Governs generation | The spec dies at merge, with nothing reconciling specs against the code they produced |
| Code graphs and context servers | Improve what the agent sees | Retrieval is not authority: the graph says what exists, not what is permitted |
| Architecture lint | The one deterministic layer that works | Checks structure — who imports whom — never semantics |
| AI code review | Reviews the diff | Non-deterministic: same diff, different findings on different runs |
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
Overview
What the service is, for whom, deployed how.
AuthoredArchitecture
Layers, boundaries, invariants.
AuthoredDependencies
The dependency graph, from csproj or package.json.
Generated from codeInterfaces
Public surfaces from code or OpenAPI, drift-checked.
Generated from codeStandards
Repo-specific deltas only; shared standards referenced, never copied.
AuthoredDecisions
One per decision; imports land as drafts until a person promotes them.
ImportedThe 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
Code
A coding agent drifts from the standard in a single session, then works from the governed contract instead.
What is SIGN™
Prose an agent has to interpret, next to the same rule expressed as SIGN™.