Claude Code - Spec Driven Development Pattern/Repo Template

November 6, 2025 · View on GitHub

A template repository for structuring Claude Code projects with automated specification generation from free-form prompts.

Purpose

This repository provides a file structure and automation pattern for organizing Claude Code projects. It transforms unstructured project descriptions into organized specifications and context files that Claude Code can reliably parse.

Repository Structure

Claude-Spec-Starter/
├── .claude/
│   ├── commands/
│   │   ├── build-repo.md       # Initialize repository from prompt.md
│   │   ├── refine-spec.md      # Refine existing specification
│   │   ├── validate-setup.md   # Verify repository structure
│   │   ├── add-context.md      # Add contextual information
│   │   └── gitkeep.md
│   └── settings.local.json     # Claude Code permissions
├── spec/
│   └── starter.md              # Generated development specification
├── context/
│   └── index.md                # Generated contextual information
├── decisions/
│   └── README.md               # Decision records documentation
├── iterations/
│   └── README.md               # Spec iteration snapshots
├── scripts/
│   ├── spec-diff.sh            # Compare spec versions
│   └── archive-iteration.sh    # Create iteration snapshots
├── archive/
│   └── prompt.md               # Original prompt after processing
├── prompt.md                   # User-provided project description (input)
├── CLAUDE.md                   # Repository instructions for Claude Code
└── README.md

Mechanism

The template uses a slash command (/build-repo) to parse and organize project information:

User creates prompt.md with project description
/build-repo command processes the file
Technical specifications extracted to spec/starter.md
Context and preferences extracted to context/index.md
Project summary added to CLAUDE.md
Original prompt.md moved to archive/

Installation

# Clone the repository
git clone https://github.com/danielrosehill/Claude-Spec-Starter.git your-project-name
cd your-project-name

# Remove original git history
rm -rf .git

# Initialize new repository
git init
git add .
git commit -m "Initial commit from Claude-Spec-Starter"

Setup

Required Step

After installation, run the /build-repo command to initialize the repository structure:

claude-code
/build-repo

This processes prompt.md and generates the organized file structure.

File Descriptions

`prompt.md`

User-created file containing the complete project description. Should include:

Project goals
Technical requirements
User preferences
Feature descriptions
Constraints

`spec/starter.md`

Generated technical specification containing:

Technical requirements
Architecture decisions
Feature specifications
Implementation guidance

Created by /build-repo from prompt.md.

`context/index.md`

Generated context file containing:

User preferences (languages, tools, approaches)
Constraints and limitations
Domain context
Background information

For complex projects, additional context files can be created in context/ with descriptive filenames.

`CLAUDE.md`

Repository-level instructions for Claude Code defining:

File structure
Location of specifications
Version handling for specs
Context retrieval patterns

Updated automatically by /build-repo.

`.claude/commands/`

build-repo.md - Initial setup command that:

Parses prompt.md (typically from voice input)
Separates technical specs from context
Distributes information to appropriate files
Updates CLAUDE.md
Archives processed prompt

refine-spec.md - Refinement command that:

Updates existing specifications with new information
Handles iterative additions from voice sessions
Maintains consistency with original vision

validate-setup.md - Validation command that:

Checks repository structure integrity
Verifies all required files exist
Reports on project readiness

add-context.md - Context management command that:

Adds new contextual information
Handles voice-driven preference updates
Organizes context into appropriate files

`decisions/`

Directory for tracking architectural and technical decisions made during development. Use the provided template to document why certain approaches were chosen.

`iterations/`

Directory for storing snapshots of major specification versions with metadata. Helps track project evolution over time.

`scripts/`

spec-diff.sh - Compare specification versions

./scripts/spec-diff.sh                    # Compare two most recent
./scripts/spec-diff.sh starter.md v2.md   # Compare specific versions

archive-iteration.sh - Create iteration snapshots

./scripts/archive-iteration.sh "added-mobile-support"

Usage

Initial Setup

Create prompt.md with project description (typically via voice-to-text)
Run /build-repo to process and organize information
Run /validate-setup to verify structure
Begin development

Working with Voice Prompts

This template is designed for voice-driven development:

Initial prompt.md is typically captured via speech-to-text
Claude Code is aware of common STT transcription errors
Use /refine-spec to add details from follow-up voice sessions
Use /add-context to capture additional preferences

Managing Specifications

Direct editing:

Edit spec/starter.md for minor updates

Iterative refinement:

Run /refine-spec to integrate new requirements
Create versioned specs for major changes: spec/v2.md, spec/v3.md
Claude Code references the highest version number

Tracking evolution:

Run ./scripts/archive-iteration.sh "description" to snapshot current state
Compare versions with ./scripts/spec-diff.sh

Managing Context

Add context information:

Run /add-context for new preferences or constraints
Edit context/index.md directly for small changes
Create modular context files for complex projects

Decision Tracking

Document important architectural choices:

Create decision records in decisions/ directory
Use date-prefixed filenames: YYYY-MM-DD-description.md
Reference the template in decisions/README.md

Customization

Adding Slash Commands

Create .md files in .claude/commands/:

touch .claude/commands/deploy.md

Check spec/ for the latest specification (highest version number or starter.md)
Read all files in context/ for user preferences
Use this information to inform development decisions

Specification Versioning

Specs are versioned by filename:

spec/starter.md - Initial specification
spec/v2.md - Second iteration
spec/v3.md - Third iteration

Claude Code automatically selects the highest version number.

Requirements

Claude Code CLI
Git (for version control)
Markdown-compatible editor

Author

Daniel Rosehill

danielrosehill.com
public@danielrosehill.com