Spec-Driven Development (SDD) Conventions

April 17, 2026 · View on GitHub

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. The path can be configured in your project's AGENTS.md file (or similar project configuration). If not specified, the default location is .specs/ at the project root.

If no .specs folder exists at the project root and no path is specified in the agent file, search the project for an existing specs folder (e.g., specs/, docs/specs/, .github/specs/). If found, use that location; otherwise, create .specs/ at the project root.

Configuration Example (in AGENTS.md):

## Spec-Driven Development (SDD) Directory

Specs are located at: `docs/specs/`

Each feature gets its own subfolder inside the specs directory.

Folder Naming Pattern

{YYYY-MM-DD}--{kebab-case-title}
  • YYYY-MM-DD: creation date (ISO format), fixed at the time the spec was created
  • title: kebab-case feature name
  • Separators: double dashes --

Examples:

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

Folder Structure

project-root/
├── {specs-dir}/               ← Configurable path (default: .specs/)
│   ├── 2026-03-01--user-authentication/
│   │   ├── README.md          📋 Status, owner, original prompt
│   │   ├── plan.md            🗺️ Agent-generated implementation plan
│   │   └── work-logs.md       📝 Timeline & change history (optional)
│   │
│   ├── 2026-03-05--billing-integration/
│       └── ...
│
├── 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: creation date (same as folder name)
  • Last Updated: date of last modification
  • 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]

| Field            | Value                                                    |
| ---------------- | -------------------------------------------------------- |
| **Status**       | status                                                   |
| **Owner**        | @developer                                               |
| **Created**      | YYYY-MM-DD                                               |
| **Last 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.

IMPORTANT: plan.md does NOT contain status, created date, or other metadata - those live in README.md.

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.