codev

Open source · Claude Code

Spec-driven development for Claude Code.

codev adds a thin layer of specifications to your repository, so that you and Claude Code agree on what must be built before a line of code is written — and so that architecture decisions, once made, stop being re-debated on every change.

Read the documentation Documentation en français

View the source on GitHub

A change adds one requirementspecs/ui/theme/spec.md
## ADDED Requirements

### Requirement: The chosen theme is remembered

The application SHALL restore the theme the user last picked, on every device they sign in from.

#### Scenario: Returning user

- **GIVEN** a user who picked the dark theme on their laptop
- **WHEN** they sign in on their phone
- **THEN** the application renders with the dark theme

Getting started

Install codev

No Rust toolchain needed. Both scripts verify the SHA-256 of the binary they download.

macOS and Linux

curl -sSL https://raw.githubusercontent.com/mairistem/codev/main/install.sh | sh

Windows (PowerShell)

iwr -useb https://raw.githubusercontent.com/mairistem/codev/main/install.ps1 | iex

Then, in your project: codev init

Follow the quickstart Other ways to install

How it works

Plans before code, decisions that hold

Every change follows the same cycle — propose, apply, sync, archive — with one Claude Code skill per step.

  • Changes are deltas

    A change declares ADDED, MODIFIED, REMOVED or RENAMED requirements against the current specs, so codev works on existing code, not only on new projects.

  • Decisions are sealed and accepted

    An architecture decision takes effect when you accept it; codev seals its text with a hash, and changing it means superseding it.

  • Plans challenged before your review

    /codev-propose checks traceability, re-reads the plan as a skeptical reviewer, joined by experts for the domains it touches, and hands you at most five points to challenge.

  • Docs and tests in every plan

    Every spec scenario is covered by an automated test in a task, and the documentation the change affects is updated in a task.

  • Your team’s language

    Artifacts are written in the language your team sets; their structure stays machine-readable.

  • Shared conventions

    A project can inherit context, rules and decisions, read-only, from a shared folder or a git repository pinned to a commit.

  • A complete project from codev init

    Skills, CLAUDE.md and, on GitHub, a CI workflow and a pull request template; codev doctor tells you what is still missing.

  • Release notes generated

    Each proposal carries a release note; codev changelog assembles those of the changes archived since the last release.

  • Updates in one command

    codev self-update installs the latest release after verifying its checksum, then refreshes the project’s skills.

See the workflow

Roles

How a plan is built

/codev-propose takes one role after another, each with criteria it checks before moving on. Then it stops: the plan is yours to approve.

  1. Analystunderstands the request
  2. Investigatorreads the code first
  3. Product ownerwhy and what
  4. QA analystobservable behavior
  5. Architecthow, within the decisions
  6. Tech leadtasks and their tests
  7. Tracerevery scenario covered
  8. Skepticpoints to challenge
  9. You approvethen ask for /codev-apply

Read about roles Measured, not assumed Les rôles, en français

Built with codev

codev is developed with codev

Every change to this repository is planned, reviewed and archived with the tool itself, and every pull request runs codev validate --strict. Its _codev/ folder is a real-world example you can browse.

The living specs Every archived change A review record The architecture decisions