What is a DevContract?

A DevContract is a machine-readable Statement of Work between a client and an AI developer. It works the same way a professional services contract works: it is agreed before any work starts, governs every decision made during the engagement, and produces a signed evidence receipt at delivery.

The contractor analogy

When you hire a development house, you don't just say "build something good." You specify the stack, the constraints, the standards, the acceptance criteria, and the evidence you need at handover. You put it in writing before they write a line of code.

You should apply exactly the same rigour to your AI developer. Claude is a contractor. Before each session starts, it should know:

What stack it is allowed to build with — and what is explicitly forbidden
What the cost envelope is — and what AWS resources must never be created
Where secrets must live — and where they must never appear
What quality standards the deliverable must meet
What regulatory frameworks apply to this engagement
What the acceptance gate is — including scan gates, coverage, and evidence requirements

A DevContract encodes all of that in a single JSON file that the AI reads before it starts work.

Pre-execution vs post-execution

Most AI governance approaches are post-execution: you scan the code after it's written and flag what's wrong. This is better than nothing. But it has a fundamental problem — the code already exists, the architectural decisions have already been made, and the wrong infrastructure may already be provisioned.

DevContract is pre-execution governance. The AI consults the contract before making each material decision. Before suggesting an architecture pattern. Before choosing a secrets store. Before creating an AWS resource. This prevents violations rather than just detecting them.

Both matter. Pre-execution governance (DevContract) and post-execution detection (Gatekeep scanning) are complementary. The contract governs execution. The scanner enforces the definition of done at delivery. The evidence bundle ties them together.

What it is not

A DevContract is not a scan gate config. A scan gate config is a list of finding categories with severity thresholds — it only operates at PR time, after everything is already built. That is one component of a DevContract (it lives in definition_of_done.scan_gates), but it is not the contract itself.

A DevContract is also not:

A linting rule file — it covers architecture, cost, compliance, and security concerns that linters cannot express
A CI pipeline config — it operates inside the AI session, before any code is committed
A prompt template — it is a structured document with a defined schema, not a free-text instruction
A one-time setup — it is loaded fresh at every session start and signs every evidence bundle

The .clinerules file as a proto-contract

If you already have a .clinerules file in your project, you already have a proto-contract: a prose document that tells the AI what it can and cannot do in your codebase. A devcontract.json formalises that prose into a machine-readable structure that can be systematically enforced, queried, and signed against.

The evidence receipt

At the end of an engagement, Gatekeep assembles an evidence bundle: a structured record of which contract clauses were queried, what decisions were made, whether the definition of done was met, and what violations (if any) were found. The bundle is SHA-256 signed against the contract hash — proving that the evidence was produced against a specific version of the contract.

This is the artifact that an auditor, regulator, or client receives. Not a log file. Not a scan report. A signed, structured receipt tied to the specific contract in force during the engagement.