Spec-Driven Development with Spec Kit

Before you build a new feature, you’re going to describe it in plain English first — a spec — before any code gets written. It’s the tooled version of the “explain it back” rule from Using This Template: if you can’t describe what you’re building, the AI shouldn’t be writing it yet.

The commands

Both Claude Code and Codex CLI are already set up for this — same steps, slightly different syntax:

Step	Claude Code	Codex CLI	What it does
Set your ground rules (once)	/speckit-constitution	$speckit-constitution	Writes your project’s principles
Describe the feature	/speckit-specify	$speckit-specify	Writes a spec, starts a new branch
Plan how to build it	/speckit-plan	$speckit-plan	Writes a technical plan
Break it into steps	/speckit-tasks	$speckit-tasks	Writes a task list
Build it	/speckit-implement	$speckit-implement	Writes the code

Run constitution once. For every feature after that, run specify → plan → tasks → implement, in order.

Skip the rest for now

There are four more commands (clarify, checklist, analyze, converge) for messier or bigger features. Ignore them until you actually hit the problem they solve — the five steps above are all you need to start.

Set your own ground rules

Run /speckit-constitution and tell it what matters for this project — you write these yourself, there’s no fixed list to memorize. A few worth starting with:

• Postgres and Redis live on Aiven — nothing here should assume a local database.
• No secret should stay at its template default (changethis) past initial setup.
• New endpoints get a schema and a test, not “add tests later.”

Working on more than one feature at once

/speckit-specify already creates a new branch for each feature — that’s the “starts a new branch” column above, you don’t do it yourself. One feature at a time, that’s all you need: branch, build, merge, repeat.

If you want two features going at once — two Claude Code or Codex CLI sessions running in parallel — a single folder can only have one branch checked out at a time. A git worktree checks a second branch out into its own folder, so each session gets its own files:

# from the repo root, after /speckit-specify has created e.g. 003-archive-item
git worktree add ../archive-item 003-archive-item

Open that folder in a second terminal and run Claude Code or Codex CLI there. It’s a full checkout, so run uv sync / bun install in it once before starting. When the feature’s done:

git checkout main
git merge 003-archive-item
git worktree remove ../archive-item

Worktrees, not separate Codespaces

You don’t need a second Codespace for this — add the worktree inside the one you already have and open a second terminal tab for it. GitHub’s free tier is 120 core-hours a month, which on the default 2-core machine works out to roughly 60 hours of actual use — plenty to get started, worktrees included.

Try it: archive an item instead of deleting it

/speckit-specify Let users archive an item instead of deleting it. Archived
items are hidden from the list but can be restored.

/speckit-plan Add an is_archived field to Item; add archive/restore
endpoints; filter archived items out of the default list.

/speckit-tasks

/speckit-implement

Read the spec after that first command, before moving on. That’s your chance to fix a wrong assumption while it’s still one sentence — not a pile of generated code.

One thing to know

If the result comes out wrong, Spec Kit can’t tell you whether the spec was unclear or the AI just didn’t follow it. You still have to read the code and decide. That’s why you read the diff either way.