Code Contracts

Overview

Code Contracts is a simple open format for specifying structured assumptions and requirements colocated with code, to support faster and better agent-driven software development. A contract is written as an @cc directive inside a documentation comment, generally attached to a function, class, or method declaration:

/**
 * @cc [owner:spolu,label:product] balance-pre-and-fail
 * `from.balance` is expected to be greater than or equal to `invoice.amount`, fails with
 * `InsufficientBalanceError` otherwise.
 */
export async function payInvoice(invoice: Invoice, from: Account): Promise<PaidInvoice> {
  ...
}

Why Code Contracts

Code contracts are written and used by both humans and agents to reason about code. They serve three purposes:

• Specification — unlike separate product or system specification files, which drift from code and are harder to discover, contracts are embedded locally. Humans reason about behavior without inspecting implementation details; agents use them to guide implementations and surface assumptions to humans and future agents.
• Attention — they reduce the cycles needed to reason about code by surfacing assumptions and invariants in a structured way, freeing human attention as a bottlenecked resource.
• Verification — their structure and granularity let tooling enforce compliance and ease maintenance over time, giving agents a verification signal that improves performance.

Tooling

The cc-check command-line interface (npm install --global @spolu/cc-check) provides:

• cc-check format [file-like] — reports malformed @cc syntax and duplicate contract IDs in a supported source or CONTRACTS file. Without a path, it recursively inspects every supported file in the current directory. It never rewrites files or assesses contract prose or implementation compliance.
• cc-check list <file-like|location-like> — lists contracts attached to declarations throughout a source file, or contracts applicable to the declaration containing a source location and its ancestors. Directory-scoped contracts from ancestor CONTRACTS files are included by default; pass --no-global to exclude them.

Specification and Grammar

@cc directives are extracted from documentation comments in any supported source language; comment delimiters and decorations (/**, */, //, ///, Python docstring triple quotes, leading *) are removed before parsing. Each directive defines one contract, generally colocated with a function, class, or method definition.

Contracts not attached to a declaration live in a file named CONTRACTS, applying to all code in that file's directory and its descendants — typically directory-scoped rules such as architectural boundaries, dependency constraints, or security practices:

@cc [owner:spolu,label:architecture] database-access-thru-resources
Database accesses must happen exclusively through `Resource`-like interfaces.

@cc [owner:spolu,label:security] no-sensitive-data-logging
Credentials, tokens, secrets and user data must not be logged.

A directive is @cc followed by optional bracketed metadata and a contract ID: @cc [owner:spolu,label:product] balance-post. Metadata keys are extensible; owner, notify, and label are well-known. A contract may have multiple owners, notification recipients, and labels; semicolons separate multiple values within one attribute ([owner:spolu;tdraier,label:product]) rather than repeating the key, though repeated keys remain valid.

The prose body is non-empty and extends to the end of the documentation comment, the next @cc directive in a CONTRACTS file, or the end of that file. It may span any number of lines; the core format prescribes no vocabulary, sentence shape, modality, or requirements notation, though Markdown is generally expected.

Contract IDs are unique and stable within the declaration they are attached to (the same ID may recur on a different declaration); in a CONTRACTS file, IDs are unique and stable within that file and across all parent CONTRACTS files. A documentation comment carries exactly one @cc directive, but multiple consecutive contract comments may attach to the same declaration.

Owner and Notify Semantics

owner lists GitHub usernames to notify when an existing contract is changed or removed; contract introductions do not notify owners. notify lists GitHub usernames to notify on every discovered violation of that contract. Owners are not automatically notified about violations unless also listed in notify. Review agents split semicolon lists, combine repeated keys, and deduplicate usernames.