Documenting contracts

REQUIRED BACKGROUND: the technical-writing skill (hard rules, truth rules, style).

Overview

A contract document is read by a stranger who cannot see the code and is about to depend on it. Core principle: document the wire, exhaustively, with each detail at its own level; the caller's language is the wire format and domain terms, never the implementation's types. Contract surfaces are reference kind, so the core Reference rule applies: every endpoint, every field, every error. An omission here is a hole a caller falls into.

When to invoke, and not

Invoke when documenting anything machines call or parse: REST and RPC endpoints, message queues and topics, webhooks, CLI commands, file formats. The api-reference.md of a legacy campaign (documenting-legacy-codebases) is this skill's document. Do NOT invoke for internal code interfaces, which the code documents itself, or for configuration references, which belong in config-reference.md under the core Reference rule. Judging whether the contract is well designed is out of scope: this skill documents the contract that exists.

One home versus generated specs

When an OpenAPI or AsyncAPI spec exists, or the code generates one, that spec owns the field tables. The markdown then documents only what the spec cannot say (semantics, side effects, ordering, omitted-versus-null) and links the spec; hand-maintaining field tables beside a generated one builds a second home that drifts. The catalog below is for the common legacy case where no machine spec exists, and writing one is not this document's job.

The four detail levels

Most bad contract documents mix these; this template gives each level its own home, and the writer moves detail found at the wrong level into the level that owns it: