A fork-friendly Spec-Driven Development (SDD) template. Clone, rename, and start shipping with discipline from day one.
SDD is a lightweight method that asks one question before any code is written: what are we actually trying to build, and why? Every non-trivial change starts as a written spec (the what), gets paired with a plan (the how), and is broken into atomic tasks (the when) — all version-controlled alongside the code they describe.
It is not waterfall. Specs are living documents, refined as you learn. The goal is not a 50-page upfront design — it is a small, durable artifact that:
- Forces you to think before you type.
- Gives reviewers (and future-you) the why the code can never carry.
- Makes AI coding agents dramatically more useful by giving them ground truth.
- Survives team turnover better than tribal knowledge.
The rule of thumb: if a change takes more than a couple of hours, it deserves a spec. If it does not, just open a PR.
Because writing the scaffolding for a new project — README, CONTRIBUTING, issue templates, ADR layout, CI starter, SDD folder structure — is boring, repetitive, and easy to get wrong. This repo gives you a working, opinionated skeleton you can adapt in 10 minutes.
There are three ways to bootstrap a project from this repository. Pick the one that fits.
- Open https://github.com/aslancarlos/sdd-template.
- Click the green Use this template → Create a new repository button.
- Pick a name, owner, and visibility for your new repo.
- Clone the new repo locally and personalize it (see Personalize below).
gh repo create my-project \
--template aslancarlos/sdd-template \
--public \
--clone
cd my-projectUse --private instead of --public if you do not want the new repo public.
For when you do not want the GitHub link between template and new repo, or when you are not using GitHub.
git clone https://github.com/aslancarlos/sdd-template.git my-project
cd my-project
rm -rf .git
git init -b mainAfter you have the new repo locally, replace the placeholders:
# 1. Replace template-wide placeholders (macOS sed syntax shown; on Linux drop the empty '' after -i)
grep -rl 'sdd-template' . --exclude-dir=.git | xargs sed -i '' 's/sdd-template/my-project/g'
grep -rl '<your-org>' . --exclude-dir=.git | xargs sed -i '' 's|<your-org>|my-org|g'
grep -rl '<your-name>' . --exclude-dir=.git | xargs sed -i '' 's/<your-name>/Jane Doe/g'
grep -rl 'YYYY-MM-DD' . --exclude-dir=.git | xargs sed -i '' "s/YYYY-MM-DD/$(date +%Y-%m-%d)/g"
# 2. Update LICENSE year and holder, and CODE_OF_CONDUCT contact
$EDITOR LICENSE CODE_OF_CONDUCT.md SECURITY.md
# 3. Replace the example spec with your first real one
mv specs/001-example-url-shortener specs/001-<your-feature-slug>
$EDITOR specs/001-<your-feature-slug>/spec.md specs/001-<your-feature-slug>/plan.md specs/001-<your-feature-slug>/tasks.md
# 4. Adapt the Makefile to your stack (Python / Node / Go / Rust ...)
$EDITOR Makefile CLAUDE.md
# 5. First commit
git add .
git commit -m 'chore: initialize project from sdd-template'
git push -u origin mainFor per-stack adaptation guides (Python, Node/TypeScript, Go, Rust), see USAGE.md.
.
├── README.md you are here
├── USAGE.md detailed adoption guide (per-stack adaptation)
├── CLAUDE.md instructions for the Claude AI agent
├── AGENTS.md instructions for AI agents generally
├── CONTRIBUTING.md how to propose changes
├── CHANGELOG.md Keep a Changelog format
├── CODE_OF_CONDUCT.md Contributor Covenant 2.1
├── SECURITY.md how to report vulnerabilities
├── LICENSE MIT (replace as you wish)
├── .editorconfig editor-agnostic style baseline
├── .gitignore common ignores across stacks
├── .gitattributes line endings, linguist hints
│
├── .github/
│ ├── CODEOWNERS who owns what
│ ├── dependabot.yml dependency updates
│ ├── PULL_REQUEST_TEMPLATE.md
│ ├── ISSUE_TEMPLATE/
│ │ ├── bug_report.yml
│ │ ├── feature_request.yml
│ │ ├── spec_proposal.yml SDD-specific: propose a new spec
│ │ └── config.yml
│ └── workflows/
│ └── ci.yml example CI workflow (lint, test, build)
│
├── docs/
│ ├── README.md docs index
│ ├── architecture.md system architecture (template)
│ ├── runbook.md operations playbook (template)
│ ├── glossary.md domain terms
│ ├── onboarding.md new contributor day-1 guide
│ ├── style-guide.md writing & code conventions
│ └── decisions/ ADRs (Architecture Decision Records)
│ ├── README.md
│ ├── template.md
│ ├── 0001-record-architecture-decisions.md
│ └── 0002-use-spec-driven-development.md
│
├── specs/ SDD core
│ ├── README.md how the SDD workflow works here
│ ├── constitution.md inviolable project principles
│ ├── templates/
│ │ ├── spec.md
│ │ ├── plan.md
│ │ └── tasks.md
│ └── 001-example-url-shortener/ a fully worked example feature
│ ├── spec.md
│ ├── plan.md
│ └── tasks.md
│
└── examples/ runnable snippets (placeholder)
└── README.md
┌───────────────────────────────────────────────┐
│ │
v │
┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐│
│ IDEA │──▶ │ SPEC │──▶ │ PLAN │──▶ │ TASKS ││
└────────┘ └────────┘ └────────┘ └───┬────┘│
│ │
┌────▼───┐ │
│ CODE │ │
└────┬───┘ │
│ │
┌────▼───┐ │
│REVIEW &│ │
│ MERGE │─┘
└────────┘
- Idea — a hunch, ticket, complaint, opportunity.
- Spec (
specs/NNN-slug/spec.md) — problem, outcome, requirements, out-of-scope, acceptance criteria. - Plan (
plan.md) — architecture, tradeoffs, dependencies, rollback. - Tasks (
tasks.md) — atomic, ordered, each with a Definition of Done. - Code — small PRs that reference the spec.
- Review & merge — back to step 1 with what you learned.
Read specs/README.md for the full workflow and specs/constitution.md for the inviolable principles.
- Spec Kit — GitHub's take on SDD.
- Architecture Decision Records — Michael Nygard's ADR pattern.
- Keep a Changelog — humans first, machines second.
- Conventional Commits — structured commit messages.
- The Twelve-Factor App — operational hygiene.
MIT — see LICENSE. Replace with your preferred license if needed.
Issues and PRs welcome. Please read CONTRIBUTING.md first. By participating you agree to the Code of Conduct.