Skip to content

CodexSpec Logo

Welcome to CodexSpec

PyPI version Python License: MIT

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

CodexSpec is a toolkit that helps you build high-quality software using a structured, specification-driven approach. It flips the script on traditional development by making specifications executable artifacts that directly guide implementation.

Why CodexSpec?

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

Aspect Claude Code Only CodexSpec + Claude Code
Multi-language Support Default English interaction Configure team language for smoother collaboration and reviews
Traceability Hard to trace decisions after session ends All specs, plans, and tasks saved in .codexspec/specs/
Session Recovery Plan mode interruptions are hard to recover from Multi-command split + persisted docs = easy recovery
Team Governance No unified principles, inconsistent styles constitution.md enforces team standards and quality

Human-AI Collaboration

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

Problem Solution
Unclear requirements Interactive Q&A to clarify before building
Incomplete specifications Dedicated review commands with scoring
Misaligned technical plans Constitution-based validation
Vague task breakdowns TDD-enforced task generation

Key Features

  • Constitution-Based - Establish project principles that guide all decisions
  • Interactive Clarification - Q&A-based requirement refinement
  • Review Commands - Validate artifacts at each stage
  • TDD-Ready - Test-first methodology built into tasks
  • i18n Support - 13+ languages via LLM translation

Quick Start

# Install
uv tool install codexspec

# Create a new project
codexspec init my-project

# Or initialize in existing project
codexspec init . --ai claude

Full Installation Guide

Workflow Overview

Idea -> Clarify -> Review -> Plan -> Review -> Tasks -> Review -> Implement
            ^              ^              ^
         Human checks    Human checks    Human checks

Every artifact has a corresponding review command to validate AI output before proceeding.

Learn the Workflow

License

MIT License - see LICENSE for details.