A contract makes expected behavior visible before implementation. For an API endpoint, it can define which responses callers may expect; for a feature, it can also set constraints and exclusions. That boundary gives developers, AI tools, and reviewers a way to distinguish requested behavior from plausible-looking additions. section 3.2.1 section 4.5.4 section 3.3.2
An order endpoint with a narrow contract
Suppose GET /orders/:id specifies 200 when an order exists and 404 when it does not. A generated handler may temporarily return 501 while its logic is unfinished; 501 is a scaffold signal, not a new contracted outcome. Failing tests for 200 and 404 then guide implementation. Adding 400, 409, or 422 responses, ID validation, caching, or a tax calculation calls for a decision rather than silent acceptance. section 3.2.1 section 3.3.2
Listing 3.1 Handler skeleton with no design decisions
export async function getOrder(req: Request, res: Response) {
// TODO: Implement order retrieval logic
// TODO: Handle 404 case when order not found
res.status(501).json({ error: "Not implemented" });
}
The handler marks the two required behaviors as TODOs and returns a temporary 501 instead of inventing implementation details. section 3.2.1
Use the contract as a working boundary, not a claim that every decision is final:
- Give a generator the contract and narrow instructions. Ask for disposable scaffolding or tests rather than an apparently complete implementation with unrequested behavior. section 3.2.1 section 3.6
- In a pull request, expose the request, contract, and decisions. Ask where each added response, rule, or abstraction came from; passing tests alone cannot answer that question. section 3.3.2
- Refine the contract when implementation reveals real constraints. A webhook specification, for example, can explicitly require built-in HMAC verification, a 200 response on internal errors, and no idempotency tracking in that handler. section 4.5.4
Contracts also cross team boundaries. If services settle on incompatible event formats, downstream consumers must build adapters. Some agreements are harder to see: retry behavior, eventual-consistency assumptions, and feature flags may shape an integration without appearing in one repository. Make shared formats and integration assumptions explicit, assign ownership for standards that affect multiple teams, and revisit them as the system changes. A contract is useful when it makes both implementation choices and their consequences visible. section 11.2.2 section 13.4.1

























































