Every contract has a file and two tests

Why

An agent working on one side of a boundary between components cannot see the other side. If it renames a field, its own tests still pass, and the consumer on the other side reads an empty value and skips it. Nothing reports the error.

The worked example in the kit is a Python extraction service that writes field names into a JSON document, and a .NET rules engine that reads them. Nothing connected the two. Each rule’s unit tests hand-wrote their own field names, so a rename on either side would have failed without any error.

How

What counts as a contract. An API route and its payload. A queue message. A set of field names one service writes and another reads. A generated manifest. The test: if two of these are true, it is a contract. Two deployable units depend on it. Changing it needs a coordinated release. A mismatch fails silently.

What counts as a contract change. Renaming, removing or retyping a field is a contract change. Adding an optional field that every consumer already ignores is not. When unsure, treat it as a contract change.

Every contract gets three things.

1. A file in the repository, under contracts/, that states the shape in a machine-readable form. Generated where possible, never edited by hand.
2. A test on the producing side that fails when the file no longer matches what the code writes. This tells you the file is stale.
3. A test on the consuming side that fails when the code reads something the file does not contain. This tells you a consumer reads a field that no longer exists.

You need both tests. One test alone leaves one direction of failure silent.

In the worked example, the guard is a generated manifest of every field name each document type produces, a test in the Python service that fails when the checked-in manifest is stale, and a test in the .NET project that fails when any rule reads a field no flattener produces, naming the rule and the document type. A README under contracts/ lists each file, the command that regenerates it, and its two tests. That README is the whole documentation of the boundary.

The rule for tasks. A task that changes a contract runs first, alone, and merges before any task that depends on it starts. The task template’s Contract: line makes this visible in the tracker. The instruction file tells the agent: before changing anything under contracts/, or renaming, removing or retyping a field another component reads, stop and say so.