The fastest way to get bad code from Claude Code is to describe a feature in one chat message and say "go". The agent fills every gap with a guess, and you find out which guesses were wrong after 600 lines of diff. Spec-driven development flips the order: you and the agent agree on a written spec and a task list first, then it writes code against that.
Two open source repos have become the default ways to do this inside the tools you already use: GitHub's Spec Kit and Fission AI's OpenSpec. Both install slash commands into Claude Code (and Cursor, Copilot, Codex and others). They differ in weight. This guide sets up each one in Claude Code, runs a first feature, and helps you pick.
Option 1: GitHub Spec Kit
Spec Kit is a toolkit that gives coding agents structured processes and templates. Spec-driven development ships in the core, and bug fixing and idea assessment are optional extensions.
Install
You need Python 3.11+, uv and a supported coding agent. For Claude Code the integration key is claude:
uv tool install specify-cli
specify init my-project --integration claude
cd my-project
Already have a repo? Run this inside it instead:
specify integration install claude
Spec Kit installs its steps as Claude Code skills under .claude/skills/speckit-<command>/SKILL.md. Start Claude Code in the project folder.
Build a feature
Run these in Claude Code's chat, not your terminal, one at a time, and read each result before moving on. The example is straight from the README:
/speckit-constitution Create principles focused on code quality, testing, and maintainability.
/speckit-specify Build a photo organizer with albums grouped by date and a tile preview of each album.
/speckit-plan Use Vite with vanilla JavaScript. Keep images local and store metadata in SQLite.
/speckit-tasks
/speckit-implement
/speckit-converge
The constitution is a one-time step per project: your ground rules. After that, each feature goes specify, plan, tasks, implement, converge. Repeat implement and converge until converge reports Converged.
Fix a bug the same way
Spec Kit's bug extension is worth knowing even if you never write a full spec:
specify extension add bug
Then in Claude Code:
/speckit-bug-assess "Submitting an empty password crashes the login form." slug=login-crash
/speckit-bug-fix slug=login-crash
/speckit-bug-test slug=login-crash
Reports land in .specify/bugs/login-crash/, and the verdict is verified, partial or failed. Only verified means the fix held.
One Claude Code tip
Every Spec Kit skill is model-invocable by default, so all their descriptions sit in Claude's context and count toward the skill listing budget. In a project with many skills, the docs suggest making the core commands user-invoked only:
specify init my-project --integration claude --integration-options="--no-model-invocation"
Option 2: OpenSpec
OpenSpec describes itself as fluid not rigid, iterative not waterfall, and built for brownfield (existing code) as well as greenfield. Each change gets its own folder with a proposal, specs, a design doc and a task list.
Install
It is a single binary and does not need Node.js. On macOS and Linux:
curl -fsSL https://raw.githubusercontent.com/Fission-AI/OpenSpec/main/scripts/binary/install.sh | sh
Or use a package manager: brew install openspec, or npm install -g @fission-ai/openspec@latest (Node.js 20.19.0+). Then:
cd your-project
openspec init
openspec init asks which tools you use and prints the right command spelling for each. In Claude Code the commands are /opsx:explore, /opsx:propose and so on. Cursor and GitHub Copilot spell them /opsx-propose, and Codex uses $openspec-propose.
Build a feature
Not sure what to build yet? Start with explore, which reads your code and shapes a plan before anything is written:
/opsx:explore
Know what you want? Go straight to a proposal:
/opsx:propose add-dark-mode
That creates openspec/changes/add-dark-mode/ with proposal.md, a specs/ folder, design.md and tasks.md. The specs are plain Markdown requirements with WHEN and THEN scenarios. Review and edit them, then:
/opsx:apply
/opsx:archive
Apply works through the task list. Archive moves the change into openspec/changes/archive/ and updates your project's specs, so the next feature starts from an accurate picture.
Want more steps (/opsx:new, /opsx:continue, /opsx:ff, /opsx:verify)? Pick the expanded profile with openspec config profile and apply it with openspec update. Run openspec update after every upgrade too, so your slash commands stay current.
Two notes from the README: OpenSpec collects anonymous command-name telemetry, which you can turn off with export OPENSPEC_TELEMETRY=0. And it recommends clearing your context window before implementation starts.
Which one should you use?
Both put a reviewable plan between your idea and the code. The difference is ceremony.
- Pick Spec Kit if you want a thorough, staged process with explicit gates, a project constitution, and extras like the bug fixing and idea assessment workflows. It is backed by GitHub, and teams can customize it with presets, extensions and workflows.
- Pick OpenSpec if you work mostly on existing codebases and want a lighter loop you can bend: propose, apply, archive, and edit any artifact at any time. Its own README frames Spec Kit as "thorough but heavyweight" and itself as the lighter option, so weigh that as the maintainers' view.
A practical test: run one small, real feature through each in a scratch branch. The one whose artifacts you actually read is the one that will stick.
More like this
The exact steps for each, with a ready prompt, are on the Deduped pages for building a feature with spec-driven development in Spec Kit and planning a feature with AI before code in OpenSpec. For other skill packs and workflows that make Claude Code more reliable, see the best AI repos for coding agent skills.
Get one email every Monday with the week's hottest AI repos and exactly how to use them: subscribe free at dedupedai.com
Top comments (0)