Specification
Specifications stay next to code, easy to discover and less likely to drift. Humans can reason about behavior without reading implementations; agents get explicit assumptions to guide changes.
An open format for specifying structured assumptions and requirements colocated with code to support faster and better agent-driven software development.
/**
* @cc insufficient-funds
* If the balance is less than the amount,
* payment MUST fail with InsufficientFunds
* and leave the balance unchanged.
*/
async function pay(account, amount) {
// implementation
}Specifications stay next to code, easy to discover and less likely to drift. Humans can reason about behavior without reading implementations; agents get explicit assumptions to guide changes.
Human attention for code review is scarce. Contracts make assumptions and invariants explicit, so reviewers can understand changes and check their requirements with less effort.
Structured, granular requirements make compliance easier to check and maintain over time. That verification signal helps agents catch mistakes and improve their implementations.
01 / The format
One directive. One obligation. Colocated with code.
@cc workspace-isolation@cc makes the requirement discoverable.Use a documentation comment for a function, class, or method. Use a CONTRACTS file for rules that apply to a directory and everything beneath it.
Colocation gives humans and agents the requirements where they work, so code and intent can be reviewed together.
One @cc per documentation comment. In a CONTRACTS file, the next directive starts the next contract.
contracts_file = { contract, NL } ;
contract = directive, NL, prose ;
directive = "@cc", SP, [ metadata, SP ], contract_id ;
metadata = "[", attribute, { ",", attribute }, "]" ;
attribute = key, ":", value ;
contract_id = token ;
key = token ;
value = token ;
prose = prose_line, { NL, prose_line } ;SP is one or more spaces; NL is a line break. A token contains no whitespace, commas, colons, or square brackets. Comment decorations are removed before parsing. Prose is non-empty.
IDs are stable and unique within their declaration, or within a CONTRACTS file and its ancestors. Separate multiple metadata values with ;, for example owner:alice;bob.
02 / Verify
Contracts give your agent a specification to work from—and your next review something precise to check.
Ask your agent to check a diff, file, directory, or repository against its applicable contracts.
$code-contracts verifyThe balance is debited before the invoice update. If that update fails, the payment is only partially applied.
Evidence, a source location, and a concrete consequence.
Review agents notify owner recipients when existing contracts change or are removed, and notify notify recipients when they find violations.
r? @teammate cc
cc-verify: violations found!
A comment review on the inspected commit. Relevant findings stay with the PR.
03 / Setup
Add the skill. Write a contract. Run $code-contracts verify.
npx skills add https://github.com/spolu/code-contractsUse the `code-contracts` skill for every code change and code review. Follow its contract discovery,
writing, and enforcement procedures before submitting commits or pull requests.npm install --global @spolu/cc-checkcc-check format
cc-check list payments/pay.ts:42format checks contract syntax and duplicate IDs. list discovers applicable contracts for a declaration. Your agent reviews the requirements and implementation.