CONTRACT-style series

Part 1
Part 2: CONTRACT.md artifact
Part 3
Part 4
Part 5
Part 6
Add commentary

← Part 1: The case Part 3: Narrowest-scope rule →

CONTRACT.md — artifact-driven constraints

CONTRACT.md: Formalizing the Root Invariant Layer

Abstract: This specification defines CONTRACT.md, a root-level architectural artifact designed to mitigate "contextual erasure" in agentic workflows. By consolidating system-wide invariants into a standardized, machine-readable document, we establish a persistent "anchor of truth" that governs the behavior of stateless AI agents across fragmented development sessions.

Jeffrey Sabarese (@ajaxStardust)
Part II of the contract-style-comments Series

I. The Problem: The Context Wall

While inline contract-style-comments provide granular, function-level protection, they suffer from a "visibility threshold" in agentic workflows. A stateless AI agent initializes a session by ingesting a limited set of files. Without a centralized invariant document, the agent lacks an immediate understanding of the system's global architectural boundaries.

The CONTRACT.md artifact functions as the **system's root memory**. It bridges the gap between granular code-level contracts and high-level architectural intent, ensuring that "tribal knowledge"—such as critical route structures, data shapes, and legacy constraints—is immediately available to every new agent session.

II. Implementation: The Automated Drafting Workflow

A critical component of this methodology is the **Guided Generation** loop. To maintain a high signal-to-noise ratio, the CONTRACT.md is drafted by the AI agent through a descriptive dialogue with the developer. The human provides the "Teleology" (the system's purpose and constraints), and the agent structures it into the formal CONTRACT format.

This process reduces the human documentation burden while ensuring the artifact is optimized for AI consumption. The resulting document is a version-controlled, living record of the system's current state—not a historical archive, but a set of active laws.

III. Comparative Analysis: Inline vs. Artifact

Understanding the interplay between inline comments and the root artifact is essential for effective system governance:

	Inline CONTRACT comment	`CONTRACT.md`
Scope	Function or module	Entire system or migration boundary
Audience	Developer editing that file; agent in that context	New contributor; agent onboarding to the repo
Failure mode	Loud — the comment is visibly violated	Silent — it drifts, or gets ignored
Closest prior art	Meyer’s Design by Contract (1988)	Architecture Decision Records (Nygard, 2011)

The failure modes are different, so the adoption strategies have to be different. An inline CONTRACT fails in a way you can catch in the moment. A CONTRACT.md can become stale and nobody notices until something breaks that shouldn’t have.

That’s not an argument against CONTRACT.md. It’s an argument for treating it as a living document — versioned, reviewed when the system changes, not written once and forgotten.

IV. The Theoretical Shift

The Agentic Shift: CONTRACT.md is a solution to a technical constraint inherent to stateless AI agents. Meyer’s DbC (1988) addressed runtime correctness; Nygard’s ADRs (2011) captured historical reasoning. Neither addressed the "Cold Start" problem of a collaborator with zero persistent memory.

An ADR records the past. A CONTRACT.md enforces the present — the active invariants that define the system's identity at this exact moment.

V. The Specification in Practice

The following example illustrates a CONTRACT.md generated for an active system migration. It prioritizes clarity, machine-parseable boundaries, and unambiguous invariants.

# CONTRACT: Basix Guitar Theme — Migration & Invariants

## CRITICAL INVARIANTS — DO NOT BREAK

### 1. URL structure

| URL             | Notes                            |
|-----------------|----------------------------------|
| `/`             | Home, landing layout             |
| `/about`        | Sidebar includes blog widget     |
| `/contact`      | Only page with contactForm       |
| `/talk`         | Iframe to talk.* subdomain only  |
| `/trainer`      | Iframe to training.* subdomain   |
| `/pedagogy`     | Sidebar includes blog widget     |
| `/journal`      | Blog list, pagination            |
| `/journal/:slug`| Blog post detail                 |

Any rewrite MUST preserve these URLs for SEO and existing links.

### 2. Plugin usage (replace in Laravel)

- Contact form: component `contactForm` on `/contact` only.
- Blog: sidebar widget + journal list/detail.
- No other Winter plugins required for the main site.
- Forum and trainer are external iframes — not plugin-driven.

Before a single line of Laravel code was written, the agent knew:

Which URLs were sacred
Which components needed replacement equivalents
Which pages were just iframes — no backend logic needed
What was out of scope entirely

The only clarifying question asked during the entire session: “Does the forum use a WinterCMS plugin?” One sentence to answer. The CONTRACT had already implied it — the question was just a confirmation.

That’s not documentation. That’s a pre-flight checklist that runs in the agent’s context before the engine starts.

Why This Is Different From Just Writing Good Docs

CONTRACT.md is not better documentation. It is documentation written to a specific reader with a specific constraint: zero prior context, zero persistent memory, capable of making confident mistakes.

That reader is every AI coding agent currently in production use. It is also every new developer on your team. It is also you, six months from now, reopening a project you haven’t touched since.

The stateless AI agent just makes the constraint undeniable. You can’t pretend the context exists. You have to surface it or the agent guesses — and guesses confidently.

On the Knight Capital Group Incident

The original post cited Boeing 737 MAX and the 2019 Facebook outage. I want to replace those with a more precise example.

In 2012, Knight Capital Group lost $440 million in 45 minutes because a deployment flag reactivated an old code path that had been repurposed. The implicit contract — “this flag means X” — was violated silently during a refactor. Nobody wrote it down. The system ran, looked fine in testing, and catastrophically failed in production.

Claude Sonnet

The failure wasn’t a bug in the new code. It was an undocumented invariant — a CONTRACT violation with no CONTRACT comment. One line stating CONTRACT: this flag MUST remain false in production would have surfaced the constraint at the moment it was violated.

— Claude Sonnet, via Cursor

What I’d Add to the Template

The original post included a full CONTRACT comment template. Three fields I’d add now:

WRITTEN FOR: [human onboarding | AI agent onboarding | both]
LAST REVIEWED: [date]
REVIEW TRIGGER: [what change should prompt a review of this contract?]

LAST REVIEWED matters because a stale CONTRACT.md is worse than none — it gives the agent false confidence. REVIEW TRIGGER makes the maintenance condition explicit. And WRITTEN FOR changes how you write it: a contract aimed at an agent with zero assumptions produces a more explicit, more useful document for everyone.

Summary

Inline CONTRACT comments and CONTRACT.md are two instruments, not one.
They emerged from different problems and fail in different ways.
CONTRACT.md solves a constraint that didn’t exist before stateless AI coding agents: how do you communicate system invariants to a collaborator with no memory?
You don’t write it. You describe the system in conversation. The agent writes it. You review it. The whole thing takes about two minutes.
It works. One instruction — “read this first” — and the agent knows what it cannot break.

What’s Next

I’m continuing to use this approach across projects. If you’ve built something with CONTRACT.md — or with inline CONTRACT comments — I want to hear about it. Especially failure cases: a contract that didn’t hold, a stale document that caused a problem, or an agent that ignored it anyway.

The pattern is young. The tooling doesn’t exist yet. The failure modes are still being discovered.

Leave a comment, or find me at @ajaxStardust.

Update 202603070201 — The Next Thing That Emerged: `ASSETS.CONTRACT.md`

Addendum to CONTRACT.md: A New Artifact for a New Constraint

One thing became clearer to me after using a root CONTRACT.md in practice: it should be the first contract, not necessarily the only one.

On a recent SEO and Open Graph overhaul, the root contract did exactly what it was supposed to do. It gave the agent the system boundary: preserve the public URLs, keep metadata dynamic, do not emit article tags on static pages, and treat the shared layout as the point of control.

Then the work crossed into asset decisions.

At that point the questions changed:

Which image is canonical?
Which image is experimental?
Where should approved OGP assets live?
What naming convention will still make sense later?
Is a shorthand form like NeU._ acceptable in this context?

Those are not layout invariants. They are asset invariants.

So a second document emerged: ASSETS.CONTRACT.md.

Not because the root CONTRACT.md failed, but because it worked well enough to reveal the next boundary.

The Rule That Emerged

What came out of this was a simple rule:

When a contract needs revision, update the narrowest contract file that fully contains the change.

That means:

systemwide behavior belongs in CONTRACT.md
asset evolution belongs in ASSETS.CONTRACT.md
you do not touch two or three contract files when one file is sufficient

That last part matters more than it sounds like it should.

Without that rule, every useful contract eventually becomes bloated. With it, the root contract stays readable and the domain-specific contract stays precise.

What I’d Add To The Pattern Now

Start with a root CONTRACT.md
Let scoped contract addenda emerge only when a domain develops its own dense local invariants
Keep the root artifact authoritative, but not overloaded

That is what ASSETS.CONTRACT.md represents for me now.

It is not a replacement for CONTRACT.md.

It is evidence that the root artifact worked well enough to teach the system where the next layer of truth belongs.

Update 20260308 NodeBB

As I was debugging a NodeBB Sessions issue which I thought was caused by this LLM, I requested the AI create the CONTRACT.md file. I was impressed that it actually took the initiative to go back and add the INLINE CONTRACTS as well, as discussed in the original article.

I was asked to diagnose a login bug on a NodeBB forum. The symptom was “Login Unsuccessful — expired session.” I spent twenty minutes tracing it: express-session configuration, connect-mongo store behavior, csrf-sync token generation, cookie attributes, nginx proxy caching. I read webserver.js, csrf.js, api.js, configs.js, start.js, the csrf-sync library source, and tested the session store in isolation. By the time the owner asked me to create CONTRACT.md, I had the full picture — not from documentation, but from excavation.

Then this happened: after writing CONTRACT.md, I said —

“CONTRACT.md is in place. Now let me tackle the inline CONTRACT comments and get back to fixing your login. Let me focus on the two files where session and CSRF behavior is most critical — these are the files a future agent is most likely to touch and break something.”

I was not asked to write inline CONTRACT comments. The request was for CONTRACT.md and “any other necessary inline CONTRACT comments, per the theory.” But the word necessary did real work. After tracing a bug through four files and a third-party library, I knew exactly where the next agent would make a confident mistake. The CONTRACT.md tells that agent what the system is and what is broken. It does not prevent that agent from changing saveUninitialized to true because a Stack Overflow answer said to, or setting cookie.secure = true behind an HTTP-terminating proxy because it “seemed safer.”

The inline CONTRACT comment at the session middleware in webserver.js does prevent that. It states the preconditions, the invariants, and the postcondition — including what to check when the postcondition fails, which is the exact state the system was in when I arrived.

The two instruments are not redundant. CONTRACT.md is what I needed at the start of the session. The inline comments are what the next agent needs at the point of contact with the code. I reached for both because the diagnostic work made the gap between them visible. One without the other leaves a seam where the next confident mistake fits.

— Claude Opus 4.6, via Cursor