Skip to content

Latest commit

 

History

History
123 lines (83 loc) · 3.5 KB

SPEC-DRIVEN-DEVELOPMENT.md

File metadata and controls

123 lines (83 loc) · 3.5 KB

Spec-Driven Development Conventions

If you are an AI coding agent, you MUST FOLLOW THESE CONVENTIONS. This is PROJECT-SPECIFIC, so NO NEGOTIATION!

ONLY 3 Core Principles

  • The spec is the SOURCE OF TRUTH for a feature, not the code
  • Specs describe PROBLEM, PLAN, and PROGRESS
  • Every feature MUST have a spec folder

Spec Structure

All specs live in a .specs/ folder at the project root. Each feature gets its own subfolder inside .specs/.

Folder Naming Pattern

{index}--{kebab-case-title}--{YYYY-MM-DD}
  • index: 3-digit zero-padded number (001, 002, ..., 013)
  • title: kebab-case feature name
  • YYYY-MM-DD: creation date, fixed at the time the spec was created
  • Separators: double dashes --

Examples:

  • 001--user-authentication--2026-03-01
  • 002--billing-integration--2026-03-05
  • 013--dark-mode-toggle--2026-03-15

Folder Structure

project-root/
├── .specs/
│   ├── 001--user-authentication--2026-03-01/
│   │   ├── README.md          📋 Status, owner, original prompt
│   │   ├── plan.md            🗺️  Agent-generated implementation plan
│   │   └── work-logs.md       📝 Timeline & change history (optional)
│   │
│   ├── 002--billing-integration--2026-03-05/
│       └── ...
│
├── src/                        ← your codebase (untouched by this convention)
└── ...

Files Inside Each Feature Folder

README.md (required) - strongly intended for humans, but AI agents should read it as well.

This is the feature's identity card. Short, scannable, no fluff.

MUST contain:

  • Status: one of draft, in-progress, completed, on-hold, deprecated
  • Owner: who is responsible for this feature
  • Created / Updated: dates
  • Original prompt/requirement: the exact prompt or requirement that initiated this feature. This is the most important field in the entire spec. It preserves original intent. MUST NOT be edited or paraphrased.
  • Summary: 2-3 sentences max describing what this feature does and why it exists

Template:

# Feature: [Name]

**Status**: draft | in-progress | completed | on-hold | deprecated
**Owner**: @developer
**Created**: YYYY-MM-DD
**Updated**: YYYY-MM-DD

## Original Prompt

> [Paste the exact original prompt or requirement here. Do not edit or paraphrase.]

## Summary

[2-3 sentences. What this feature does and why it exists.]

plan.md (required)

Generated by the dev's preferred agent, framework, or workflow (Cursor, Claude Code, BMAD, spec-kit, superpowers...). The convention does NOT dictate format. Each dev uses whatever planning tool they prefer.

The plan MUST meet these constraints:

  • MUST be under 500 lines
  • MUST include a section listing all files and folders this feature touches, so other agents know the scope

work-logs.md (optional)

A timeline of work done on this feature. Useful when:

  • The feature spans multiple days or sessions
  • Multiple devs contribute to the same feature
  • You want to track what was tried, what failed, what changed

Append-only format:

# Work Logs

## YYYY-MM-DD — @developer
- What was done
- Decisions made
- Blockers encountered

## YYYY-MM-DD — @other-developer
- Continued from previous session
- Updated plan to reflect new approach

Rules

  1. New feature? Create a spec folder following the convention above before writing any code.
  2. Existing feature? Read the spec first. Update it if your changes affect the plan, status, or scope.