Spec-Driven AI Development
Separates what to build (SPEC.md) from how the AI should work (CLAUDE.md). Specs define features and constraints, CLAUDE.md defines workflow and conventions.
Description
A pattern emerging from production Claude Code users: maintain a SPEC.md that defines the product — features, constraints, user stories, acceptance criteria — completely separate from CLAUDE.md which defines how the AI agent should work on the codebase. CLAUDE.md references SPEC.md via @imports. The spec becomes the source of truth for what the product does, while CLAUDE.md stays focused on development workflow, commands, and conventions. This mirrors how human teams work: product specs from PMs, coding standards from engineering. It also means non-technical stakeholders can update SPEC.md without touching agent configuration.
Who is this for
Product-focused teams where non-engineers contribute to specifications, or projects where feature requirements change frequently while coding standards stay stable.
Why files are split this way
Product specifications and development workflow are different concerns that change at different rates and are owned by different people. Mixing them in one file creates merge conflicts and makes both harder to maintain. SPEC.md can be updated by anyone who knows the product. CLAUDE.md is maintained by engineers who understand the codebase.
What changed from the previous setup
Product requirements mixed into CLAUDE.md alongside coding conventions, causing merge conflicts when either changed.
Related patterns
Universal AGENT.md with Symlinks
One AGENT.md file as the single source of truth, with symlinks to CLAUDE.md, .cursorrules, .windsurfrules, and copilot-instructions.md.
Multi-Editor Frontend Setup
Frontend-optimized AI config covering design system tokens, component conventions, and testing patterns across Cursor, Copilot, and Claude Code simultaneously.
Turborepo Per-Package AI Context
Root-level CLAUDE.md with per-package CLAUDE.md files that Claude auto-loads when working in subdirectories. Works with Turborepo, Nx, and pnpm workspaces.