$code-contracts

Code Contracts

An open format for specifying structured assumptions and requirements colocated with code to support faster and better agent-driven software development.

Add to your agent
Small enough to live next to your code.
payments.tsfunction scope
/**
 * @cc [owner:spolu,label:product] 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
}
Plain text. Versioned with your code.

Specify the failure, and what it must leave untouched.

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.

Attention

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.

Verification

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

Contract format

One directive. One obligation. Colocated with code.

@cc [owner:spolu,notify:spolu,label:security] workspace-isolation
Code MUST NOT allow a workspace to read or modify another workspace's data.
Directive
@cc makes the requirement discoverable.
Metadata / optional
Owners, notification recipients, and labels.
Stable ID
A name to reference across changes and reviews.
Requirement
Plain language. Concrete enough to find a violation.

Put the rule where it belongs.

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.

Tooling for TypeScript, Python, Go, and Rust.

your-repo/
├── CONTRACTSrepository rules
└── payments/
    ├── CONTRACTSpayments rules
    └── pay.ts@cc function contract
Formal grammar

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.

Read the full specification

02 / Verify

Agentic contract verification

Contracts give your agent a specification to work from—and your next review something precise to check.

A In your agent

Verify on demand.

Ask your agent to check a diff, file, directory, or repository against its applicable contracts.

agent sessionexample
$code-contracts verify
Read the diff and applicable contractsTrace changed behavior and its callers↳ payment-atomicity violation

The balance is debited before the invoice update. If that update fails, the payment is only partially applied.

payments/pay.ts:42

Evidence, a source location, and a concrete consequence.

B In your pull request

Review pull requests.

Review agents notify owner recipients when existing contracts change or are removed, and notify notify recipients when they find violations.

Simplify payment updatesexample
you commented

r? @teammate cc

Review Code Contracts (…)
github-actions bot

cc-verify: violations found!

  • payment-atomicity: Partial payment.

A comment review on the inspected commit. Relevant findings stay with the PR.

Set up the review bot

03 / Setup

Install the skill

Add the skill. Write a contract. Run $code-contracts verify.

01 / Install the skill
npx skills add https://github.com/spolu/code-contracts

02 / In your agent$code-contracts verify

Read the skill
Want syntax checks and contract discovery from the CLI?
Optional tooling
npm install --global @spolu/cc-check
cc-check format
cc-check list payments/pay.ts:42

format checks contract syntax and duplicate IDs. list discovers applicable contracts for a declaration. Your agent reviews the requirements and implementation.