Design by Contract (DbC) skill for Claude Code. Contract-first development with automated design, review, and TDD test generation.
./install.shThis installs to $HOME/.claude/skills/dbc and $HOME/.claude/agents/, making the skill available across all projects.
./install.sh /custom/path/skills /custom/path/agents
./verify.sh /custom/path/skills /custom/path/agents./verify.shAlternatively, copy files manually:
cp -r .claude/skills/dbc ~/.claude/skills/
cp .claude/agents/dbc-*.md ~/.claude/agents/For project-level customization:
cp -r .claude/skills/dbc .claude/skills/
cp .claude/agents/dbc-*.md .claude/agents/Then customize .claude/agents/dbc-review-criteria.md for project-specific rules.
See INSTALL.md for detailed installation guide.
# Design contracts for a feature
/dbc design "add user authentication"
# Review existing contracts
/dbc review
# Implement verified stubs (one function at a time, bottom-up)
/dbc implement
# Full cycle: design → review → tests → implement
/dbc design --implement "add payment processing"
# Design without TDD tests
/dbc design --no-tdd "update inventory"
# Limit design→review cycles
/dbc design --max-iterations 5 "add payment processing"The standard development pattern looks like this:
- Developer reads the ticket
- Developer writes implementation code
- Developer writes tests for the implementation
- Reviewer reads the finished code and tries to catch issues
This flow has well-known failure modes:
- Implicit assumptions stay implicit. The developer knows
amountmust be positive, but nothing enforces or documents this. - Tests follow implementation, not specification. A conceptual error in the implementation gets encoded in the tests too — and both pass.
- Interface mismatches surface late. Function A assumes its caller validates input; function B assumes the callee does it.
- Code review lacks a reference point. Without explicit contracts, the reviewer has no specification to check against.
Design by Contract flips the order: you write the specification first, then the tests, then the implementation.
A contract is a formal agreement between a function and its callers, expressed in the function's docstring:
def validate_order(
order: Order,
account: Account,
*,
strict: bool = False,
) -> ValidationResult:
"""Validate an order against account limits and business rules.
Pre: order.status == OrderStatus.PENDING
Pre: account.is_active
Pre: order.total >= Decimal("0")
Post: result.is_valid or len(result.errors) > 0
Post: result.account_id == account.id
Raises:
AccountSuspendedError: If account is suspended.
OrderExpiredError: If order has passed its expiry time.
"""
... # implementation comes later| Part | Meaning | Responsibility |
|---|---|---|
Pre: |
What must be true before calling | The caller |
Post: |
What is guaranteed after returning | The function |
Raises: |
What exceptions can occur and when | The function |
┌─────────────────────────────────────────────────────────────────┐
│ /dbc design <feature> │
└───────────────────────────┬─────────────────────────────────────┘
│
① Context gathering
Read specs, domain docs, scan codebase
│
② Level-by-level contract design
Level 0: entry point
Level 1: internal helpers
→ typed stubs with Pre/Post/Raises
│
③ Automated review loop
┌───────┴──────────┐
│ dbc-reviewer │
│ FAIL? ├──→ fix → re-review
│ PASS │
└───────┬──────────┘
│
④ TDD test generation
→ test_*_contracts.py (all FAIL)
│
⑤ Implement (/dbc implement OR --implement)
┌───────┴───────────────────────────────────┐
│ Per-function agents (parallel per level) │
│ leaf functions first → GREEN │
│ │
│ dbc-impl-reviewer after each level │
│ FAIL? ──→ fix agents → re-review │
│ PASS ──→ next level │
└───────┬───────────────────────────────────┘
│
⑥ Done
| Scenario | Why DbC helps |
|---|---|
| Feature with 5+ interacting functions | Cross-contract consistency caught early |
| Calculations with precise invariants | Edge cases must be stated explicitly |
| Task chains and multi-step workflows | Each step's postconditions = next step's preconditions |
| Refactoring existing logic | Contracts are the specification to satisfy |
| Multi-developer features | Contracts define interfaces explicitly |
- Stable specifications survive context loss. Contracts are written to files before any implementation exists.
- Genuine RED → GREEN. Tests run against stubs, so every test is RED initially.
- Minimal agent context per function. Each implementer agent sees one function's stub — not the entire module. Parallel agents per level, reviewed after each level by
dbc-impl-reviewer. - Human review gate before code. Design errors cost nothing to fix at stub stage.
- Traceable failures. Every test carries the exact contract line as its docstring.
| Category | Rules | Key checks |
|---|---|---|
| Signature | S1–S8 | No Any, parameterized collections, explicit Optional |
| Preconditions | P1–P6 | Exist, verifiable, on inputs only, boundary constraints |
| Postconditions | Q1–Q6 | Exist, verifiable, meaningful, achievable |
| Exceptions | E1–E4 | Documented, specific types, conditions stated |
| Architecture | A1–A6 | Single responsibility, abstraction level, no circular deps |
| Completeness | C1–C4 | No orphans, types defined, edge cases |
| Project-specific | X1–X3 | Reuse existing types, follow patterns, correct module |
- INSTALL.md — Detailed installation guide
MIT