English | 中文 | 日本語 | Español | Português | 한국어 | Deutsch | Français

A Spec-Driven Development (SDD) toolkit for Claude Code

CodexSpec helps you build high-quality software through a structured, specification-first approach. Instead of jumping straight to code, you define what to build and why before deciding how to build it.

📖 Documentation | 中文文档 | 日本語ドキュメント | 한국어 문서 | Documentación | Documentation | Dokumentation | Documentação

• Why Choose CodexSpec?
• What is Spec-Driven Development?
• Design Philosophy: Human-AI Collaboration
• 30-Second Quick Start
• Installation
• Core Workflow
• Available Commands
• Comparison with spec-kit
• Internationalization
• Contributing & License

Why use CodexSpec on top of Claude Code? Here's the comparison:

Spec-Driven Development (SDD) is a "specifications first, code later" methodology:

Traditional:  Idea → Code → Debug → Rewrite
SDD:          Idea → Spec → Plan → Tasks → Code

Why use SDD?

CodexSpec is built on the belief that effective AI-assisted development requires active human participation at every stage.

CodexSpec structures development into reviewable checkpoints:

Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
                         │                  │                │
                    Review spec        Review plan      Review tasks
                         │                  │                │
                      ✅ Human            ✅ Human          ✅ Human

Every artifact has a corresponding review command:

• spec.md → /codexspec:review-spec
• plan.md → /codexspec:review-plan
• tasks.md → /codexspec:review-tasks
• All artifacts → /codexspec:analyze

This systematic review process ensures:

• Early error detection: Catch misunderstandings before code is written
• Alignment verification: Confirm AI's interpretation matches your intent
• Quality gates: Validate completeness, clarity, and feasibility at each stage
• Reduced rework: Invest minutes in review to save hours of reimplementation

# 1. Install
uv tool install codexspec

# 2. Initialize project
#    Option A: Create new project
codexspec init my-project && cd my-project

#    Option B: Initialize in existing project
cd your-existing-project && codexspec init .

# 3. Use in Claude Code
claude
> /codexspec:constitution Create principles focused on code quality and testing
> /codexspec:specify I want to build a todo application
> /codexspec:generate-spec
> /codexspec:spec-to-plan
> /codexspec:plan-to-tasks
> /codexspec:implement-tasks

That's it! Read on for the complete workflow.

• Python 3.11+
• uv (recommended) or pip

# Using uv (recommended)
uv tool install codexspec

# Or using pip
pip install codexspec

codexspec --version

# Create new project
uvx codexspec init my-project

# Initialize in existing project
cd your-existing-project
uvx codexspec init . --ai claude

# Using uv
uv tool install git+https://github.com/Zts0hg/codexspec.git

# Specify branch or tag
uv tool install git+https://github.com/Zts0hg/codexspec.git@main
uv tool install git+https://github.com/Zts0hg/codexspec.git@v0.5.6

# 1. Install uv (if not already installed)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Restart PowerShell, then install codexspec
uv tool install codexspec

# 3. Verify installation
codexspec --version

# Using uv
uv tool install codexspec --upgrade

# Using pip
pip install --upgrade codexspec

CodexSpec is also available as a Claude Code plugin. This method is ideal if you want to use CodexSpec commands directly in Claude Code without the CLI tool.

# In Claude Code, add the marketplace
> /plugin marketplace add Zts0hg/codexspec

# Install the plugin
> /plugin install codexspec@codexspec-market

After installing via Plugin Marketplace, configure your preferred language using the /codexspec:config command:

# Start interactive configuration
> /codexspec:config

# Or view current configuration
> /codexspec:config --view

The config command will guide you through:

1. Selecting output language (for generated documents)
2. Selecting commit message language
3. Creating the .codexspec/config.yml file

Comparison of Installation Methods

Note: The plugin uses strict: false mode and reuses the existing multi-language support via LLM dynamic translation.

CodexSpec breaks development into reviewable checkpoints:

Idea → /specify → /generate-spec → /spec-to-plan → /plan-to-tasks → /implement
                         │                  │                │
                    Review spec        Review plan      Review tasks
                         │                  │                │
                      ✅ Human            ✅ Human          ✅ Human

Every generation command includes automatic review, generating a review report. You can:

1. Review the report
2. Describe issues to fix in natural language
3. System automatically updates specs and review reports

%%{init: {
  'theme': 'base',
  'themeVariables': {
    'lineColor': '#888888',
    'primaryColor': '#2d2d2d',
    'primaryTextColor': '#ffffff',
    'primaryBorderColor': '#666666'
  },
  'flowchart': {
    'curve': 'stepBefore',
    'nodeSpacing': 50,
    'rankSpacing': 40
  }
}}%%
flowchart TB
    classDef rectStyle fill:#2d2d2d,stroke:#666,stroke-width:1px,color:#fff,width:220px;
    classDef diamondStyle fill:#3d3d3d,stroke:#888,stroke-width:2px,color:#fff;

    A["Generate Spec/Plan/Tasks"]:::rectStyle --> B["Auto Review"]:::rectStyle
    B --> C{"Issues Found?"}:::diamondStyle

    C -->|Yes| D["Describe Fix in Natural Language"]:::rectStyle
    D --> E["Update Spec + Review Report"]:::rectStyle

    E --> B

    C -->|No| F["Continue to Next Step"]:::rectStyle

    linkStyle 2,4 stroke:#aaa,stroke-width:1px;

codexspec init my-awesome-project
cd my-awesome-project
claude

/codexspec:constitution Create principles focused on code quality, testing standards, and clean architecture

/codexspec:specify I want to build a task management application

/codexspec:generate-spec

/codexspec:spec-to-plan Use Python FastAPI for backend, PostgreSQL for database, React for frontend

/codexspec:plan-to-tasks

/codexspec:analyze

/codexspec:implement-tasks

CodexSpec is inspired by GitHub spec-kit with key differences:

1. Review-First Culture: Every major artifact has a dedicated review command
2. Constitution Governance: Principles are validated, not just documented
3. TDD by Default: Test-first methodology enforced in task generation
4. Human Checkpoints: Workflow designed around validation gates

CodexSpec supports multiple languages through LLM dynamic translation. No translation templates to maintain - Claude translates content at runtime based on your language configuration.

During initialization:

# Create Chinese output project
codexspec init my-project --lang zh-CN

# Create Japanese output project
codexspec init my-project --lang ja

After initialization:

# View current configuration
codexspec config

# Change output language
codexspec config --set-lang zh-CN

# Set commit message language
codexspec config --set-commit-lang en

version: "1.0"

language:
  output: "zh-CN"        # Output language
  commit: "zh-CN"        # Commit message language (defaults to output)
  templates: "en"        # Keep as "en"

project:
  ai: "claude"
  created: "2025-02-15"

Project structure after initialization:

my-project/
├── .codexspec/
│   ├── memory/
│   │   └── constitution.md    # Project constitution
│   ├── specs/
│   │   └── {feature-id}/
│   │       ├── spec.md        # Feature specification
│   │       ├── plan.md        # Technical plan
│   │       ├── tasks.md       # Task breakdown
│   │       └── checklists/    # Quality checklists
│   ├── templates/             # Custom templates
│   ├── scripts/               # Helper scripts
│   └── extensions/            # Custom extensions
├── .claude/
│   └── commands/              # Claude Code slash commands
└── CLAUDE.md                  # Claude Code context

CodexSpec supports a plugin architecture for custom commands:

my-extension/
├── extension.yml          # Extension manifest
├── commands/              # Custom slash commands
│   └── command.md
└── README.md

See extensions/EXTENSION-DEVELOPMENT-GUIDE.md for details.

• Python 3.11+
• uv package manager
• Git

# Clone repository
git clone https://github.com/Zts0hg/codexspec.git
cd codexspec

# Install dev dependencies
uv sync --dev

# Run locally
uv run codexspec --help

# Run tests
uv run pytest

# Lint code
uv run ruff check src/

# Build package
uv build

Contributions are welcome! Please read the contributing guidelines before submitting a pull request.

MIT License - see LICENSE for details.

• Inspired by GitHub spec-kit
• Built for Claude Code