CodeSpec is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the `specs` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install codespec

It will make the specs command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall codespec uninstalls.

Adding `codespec` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add codespec

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

codespec = "0.1.2"

The codespec library will be automatically available globally. Read the codespec library documentation.

Back to the crate overview.

Readme

CodeSpec

Spec-driven development — trace every requirement to a test, every file to a component.

Install

cargo install codespec

Quick Start

Tell your AI coding agent:

Install the codespec crate from crates.io and set up spec-driven development for this project.

The agent runs specs init, which prints everything it needs to scaffold specs, configure plugins, and start tracking coverage.

How It Works

1. You write down all the requirements of your software

The fundamental unit is a story. A story describes a single behavior — what the user does, what the system does back:

# Sign Up

As a user, I want to create an account,
so that I can access the platform.

- **Inputs:** Email address, password
- **Outputs:** Confirmation that the account was created

## Acceptance Criteria

### validate_email
When an invalid email is provided,
the system shall reject the request.

### hash_password
When an account is created,
the system shall store the password hashed, never in plain text.

### prevent_duplicates
When an email that already exists is provided,
the system shall reject the request.

Each acceptance criterion is a rule. Rules are identified as story::rule — for example, sign_up::validate_email.

2. Each requirement links to one or more tests

You annotate your tests to link them to rules. How you do that depends on your language and preference.

Rust — built-in support via the codespec-rust-macro crate:

#[test]
#[spec("sign_up::validate_email")]
fn rejects_invalid_email() {
    // ...
}

For other languages, you choose your own convention. Some examples:

Python — decorator:

@spec("sign_up::validate_email")
def test_rejects_invalid_email():
    ...

TypeScript — comment annotation:

// @spec sign_up::validate_email
test("rejects invalid email", () => {
  // ...
});

CodeSpec has a simple plugin system that handles test discovery. A plugin is just an executable that scans your codebase and reports which tests map to which rules. You can write a plugin for any language, any test framework, any convention.

3. You check coverage and run tests

$ specs coverage

=== Spec Coverage ===

Acceptance criteria: 3
Covered:             2
Overall:             67%

  authentication              [##############......] 2/3 (67%)

--- Uncovered criteria (1) ---

  sign_up::prevent_duplicates  (problem/modules/authentication/features/sign_up/stories/sign_up.md)

$ specs test

Runs all configured plugins, parses JUnit XML output, and gives you a compact pass/fail summary.

Prompt Tests

Some rules can't be verified with code — naming quality, architectural consistency, whether docs match implementation. Prompt tests handle these.

A prompt test is a test.md file that lives next to the story it verifies:

stories/
  my_story.md
  my_story/
    my_rule/
      test.md

The test.md contains instructions telling an AI agent what to check. The system sends the acceptance criterion + the test guidelines to the configured agent, which inspects the codebase and returns pass or fail.

Configure which agent runs prompt tests:

specs agent set claude       # or: codex, cursor
specs agent set --command "my-custom-agent"

Run them:

specs prompt-test stories/my_story/my_rule/test.md   # single test
specs test --all                                      # plugins + prompt tests

Prompt tests are slow and expensive — they invoke an AI agent. Only run them after all other tests pass.

Solution Space

The solution space documents architectural constraints — the invisible rules that, if violated, don't break tests but silently degrade the system.

Containers are things that run independently (a CLI, a server, an app). Components are architectural pieces that outlive their current implementation. Every component declares which files it owns:

# Request Validator

Validates incoming HTTP requests into domain objects.

## Files

- `src/validation/**/*.rs`
- `src/middleware/validate.rs`

## Constraints

- Must not import from handler modules.
- Must return structured error types, never raw strings.

Every project file must belong to at least one component. specs validate enforces this — your solution space is either a complete map of the codebase or it fails validation.

Plugins

Each plugin needs two things: discovery (which tests map to which rules) and a run command (how to execute them).

Discovery

Discovery tells CodeSpec which tests cover which acceptance criteria. There are two modes:

Regex discovery — CodeSpec scans your test files directly. You give it a glob pattern and a regex. The first capture group is the rule name.

# specs/config.yml
plugins:
  - name: rust
    discover:
      glob: "crates/**/tests/**/*.rs"
      pattern: '#\[spec\("([^"]+)"\)\]'
    run: "cargo +nightly test -- -Z unstable-options --format junit"

This scans all .rs files under tests/ and finds #[spec("story::rule")] annotations. No external tooling needed.

Command discovery — for cases where regex isn't enough, you can point to any executable that outputs JSON:

plugins:
  - name: custom
    discover: "./my-discover-script"
    run: "./my-test-runner"

The command must print a JSON array to stdout:

[
  {
    "rule": "sign_up::validate_email",
    "test_file": "tests/auth/test_signup.py",
    "test_name": "test_rejects_invalid_email"
  }
]

Both modes produce the same internal format. You can mix regex and command plugins in the same config.

Test annotations

You annotate tests to link them to rules. The annotation convention is up to you — the regex pattern in your config is what finds them.

Rust — using the codespec-rust-macro crate:

#[test]
#[spec("sign_up::validate_email")]
fn rejects_invalid_email() {
    // ...
}

Python — comment:

# @spec(sign_up::validate_email)
def test_rejects_invalid_email():
    ...

TypeScript — comment:

// @spec(sign_up::validate_email)
test("rejects invalid email", () => {
  // ...
});

Running tests

The run command must output JUnit XML to stdout. Most test frameworks support this natively or via a reporter.

$ specs test

3 passed, 1 failed

FAIL test_rejects_invalid_email (tests)
  assertion failed: expected 400, got 200
  ... (full output at ~/.codespec/reports/1740700200/failures/test_rejects_invalid_email.stderr.txt)

CodeSpec parses the JUnit XML and gives a compact summary. Full error output is saved to ~/.codespec/reports/ so agents only read what they need.

You can run a single plugin with specs test --plugin rust, or all plugins with specs test.

Validation

specs validate checks:

Story format — user story line, inputs, outputs, acceptance criteria with at least one rule
EARS format — every rule starts with an EARS keyword and contains "shall"
Naming — snake_case filenames and rule identifiers
Titles — H1 must match the filename
File size — 200 lines max per file
Structure — every module and feature directory has its .md file
Components — ## Files and ## Constraints sections required
Containers — ## Constraints section required
File coverage — every project file covered by at least one component

Output is JSON, for CI integration or feeding back to agents.

Commands

Start a project:

specs init my-project

Write specs, then check they're valid:

specs validate

Annotate your tests, then check coverage:

specs coverage

Run tests:

specs test                    # all plugins
specs test --plugin rust      # single plugin
specs test --all              # plugins + prompt tests

Configure the AI agent for prompt tests:

specs agent set claude

Run a single prompt test:

specs prompt-test path/to/test.md

Read the full spec standard:

specs man

Directory Structure

specs/
  config.yml
  overview.md
  problem/
    modules/
      {module}/
        {module}.md
        domain/
          {concept}/
            {concept}.md
        features/
          {feature}/
            {feature}.md
            stories/
              {story}.md
  solution/
    solution.md
    containers/
      {container}/
        {container}.md
    components/
      {component}/
        {component}.md

Problem space is requirements — what the system does. Solution space is architecture — how the system is built.

Reference

specs man prints the full spec standard reference — every format rule, naming convention, and config option in one place.

Inspiration

C4 Model (Simon Brown) — containers and components as architecture abstractions
EARS — unambiguous, testable requirement patterns
Domain-Driven Design — shared vocabulary that eliminates ambiguity
User Stories / BDD — structured acceptance criteria

Installing the specs executable

Adding codespec library as a dependency

Installing the `specs` executable

Adding `codespec` library as a dependency