Code Contracts - hn Reader

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

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.

your-repo/

├── CONTRACTSrepository rules

└── payments/

├── CONTRACTSpayments rules

└── pay.rs@cc function contract

Contracts 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

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.

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 / Add to AGENTS.md

Use 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.

CLI tooling

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.