Hey there!
Let’s talk about something that I tried my hands on recently and has changed how I work with AI coding agents.
AI coding agents are brilliant at writing code. They’re much less brilliant at remembering why they wrote it. Ask one to build a feature in a single chat and you’ll often get something that looks great but quietly misses half your requirements. And once the chat is gone, so is all the reasoning behind it. Sound familiar?
A new family of tools has popped up to fix exactly this. They put a structured workflow between your idea and the code. The three I keep seeing are GitHub Spec Kit*,* OpenSpec and the *** BMAD Method***. They share a goal but feel very different in weight, ceremony and philosophy.
In this post I’ll compare them, and then we’ll build a small first project together with the lightest one.
You’ll often hear these tools called “spec-driven development”. But in practice, I’ve found the spec isn’t really the starting point. It’s more like an output of the workflow.
You start with a conversation. The agent then writes the specs for you, so there’s no hand-writing PRDs (Product Requirements Documents, the documents that describe what a product should do and why). What you get is a persistent, reviewable paper trail that outlives any single chat. That’s the real magic.
Spec Kit is GitHub’s own toolkit, with a CLI and a set of slash commands. The pipeline is clear: set your project principles (the “constitution”), write a specification, plan the technical approach, break it into tasks, then implement. There are optional steps for clearing up ambiguity and checking consistency too.
What’s great: It’s well structured, backed by GitHub, and works with lots of agents. The constitution gives you project-wide rules that every change has to respect.
What to watch for: It’s the heaviest of the lightweight options, with quite a bit of upfront ceremony. For small changes it can feel like overkill. And a small confession: the word “constitution” just grated on me. Trivial, I know, but it’s real! 😄
Best for: Teams who want formal governance and consistency across many contributors.
OpenSpec is the minimalist, and honestly my favourite of the bunch. Its lifecycle is simple: Explore → Propose → Review → Apply → Archive.
Each piece of work is called a “change”, which is just a folder of agent-generated files: proposal.md, design.md, tasks.md, plus “delta specs” describing what’s been added, modified or removed. When you archive a change, those deltas fold into your main specs, so they always reflect the system as it’s actually built.
What’s great:
What to watch for: It’s less opinionated about team process, and your specs can drift if you skip the sync/archive step.
Best for: Solo developers/scientist like me and small teams working on existing codebases.
BMAD (Breakthrough Method for Agile AI-Driven Development) takes a completely different route. Instead of a light spec loop, it simulates an entire agile team. You get specialised agent personas, like an analyst, product manager, architect, scrum master, developer and QA. Each one produces the artifacts for their role: a PRD, an architecture document, then detailed stories for the developer agent to implement.
What’s great: It’s comprehensive, covering everything from ideation to delivery, and it shines on greenfield projects where you want rigorous planning and clear handoffs.
What to watch for: It’s the heaviest by a distance. There’s lots to learn and lots of documents to review, which is overkill for a small feature or a quick fix.
Best for: Larger or greenfield projects, and anyone who loves thinking in agile roles.
My own rule of thumb is to match the tool to the size of the work. A full agile simulation for a one-day feature is wasted effort, and a thin workflow for a multi-month product might leave gaps.
One quick note: these tools evolve fast, so double-check each project’s docs for the latest commands and features.
Ready to get hands-on?
I will show you building a very tiny and simple Scientific Paper Tracker that I find very handy. It’s small enough that you can focus on learning the workflow instead of fighting the app. Also available at my GitHub
Step_1: Check Node.js
In VS Code create a new folder and open the bash terminal. Check Node.js version. You’ll need Node.js 20.19 or newer.
Step_2: Install OpenSpec
Step_3: Create your project
Step_4: Initialise OpenSpec
Follow the pop-up instruction on terminal and select your coding agent (Claude Code, Codex, Cursor, etc.). I have used Codex for this demo.
Step_5: Open the project
OpenSpec will create an openspec/ folder and the integration files for your agent. You should see roughly this:
6. Explore the idea
Open Coding Agent-CLI (for me its Codex). In your agent’s chat, tell it what you’re after:
Choose the LLM-model while typing /model in Codex-CLI . I selected GPT-6.1-Sol-medium which I find judicious choice in terms of speed and reasoning. Also check the $openspec-explore which provides lots of options for pre-prepared documentation. I am not covering them all, just try it out and check what works best for your requitements.
Remember, explore is thinking only. No code gets written yet, so just enjoy the conversation.
Step_7. Create the proposal
For instance I provided my agent following propsal
Once the idea feels solid, say:
You’ll typically end up with:
Step_8. Review before coding
This is my favourite step. Read through proposal.md, specs/ and tasks.md, and check that the requirements are simple and match what you want. I am sharing them all here for reproducibility.
Reviewing before any code exists is one of the most valuable habits in this whole workflow. If something’s off, edit it yourself or ask the agent to do.
Step_9. Apply the change
Start a fresh chat (everything the agent needs is saved on disk) and say:
Then sit back and watch the agent work through tasks.md, ticking off each item as it goes. It’s surprisingly satisfying!
Step_10: Test and archive
Once everything works:
OpenSpec moves the change into openspec/changes/archive/ and updates openspec/specs/ so your specs describe the system exactly as it was built.
Pro tip (that I learned after messing it up in my first try) : do this before merging your PR. Otherwise the sync and archive changes will need a separate PR.
The whole flow basically summarise as follow:
IDEA → Explore → Propose → [proposal.md, specs/, design.md, tasks.md] → Review → Apply → CODE → Test → Archive → openspec/specs/
A suggested stack for the demo
If you’re not sure what to build it with, this combo keeps things simple:
OpenSpec + Python + FastAPI + SQLite
With just four endpoints:
POST /papersGET /papersPATCH /papers/{id}DELETE /papers/{id}
A quick note on commands: the exact slash-command spelling depends on your coding agent. openspec init installs the right commands or skills for your tool. Claude Code commonly shows /opsx:…, while other tools expose OpenSpec through skills.
And now the reveal of my Scientific Paper Tracker, which looks like this:
Next steps
Once your tracker works, try a second change, like adding tags or search. Modify it the way you would like your app to behave. Point the agent at the archived spec from your first change and notice how quickly it picks up the context. That “specs as context primers” effect is where OpenSpec really starts to pay off.
If you remember only a few things from this post, make it these:
AI coding agents write code fast, but without structure they forget why they wrote it. Spec-driven tools fix that by putting a persistent, reviewable workflow between your idea and the code.
The big lesson is that the specs are a by-product of the workflow, not the starting point*.* You start with a conversation, the agent writes the artifacts, and you review them before any code exists. That review step, plus archiving each finished change so your specs always match what was really built, is what makes this approach pay off.
My practical advice: match the tool to the size of the work and use the lightest workflow that gives you enough structure. If you’re new to all this, try OpenSpec on a small project like the Paper Tracker. It takes under an hour, and by your second change you’ll see how much faster your agent picks up context.
I’d genuinely love to hear from you. After reading, drop a constructive feedback/ comment below and tell me:
Your experiences will help other readers pick the right approach, and I read every single comment. If you enjoyed this post, a clap 👏 and a share with a colleague who’s curious about AI-driven development would mean the world and also keep me motivated. Thanks for reading, and happy building!
Spec-Driven Development with AI Agents: Spec Kit vs OpenSpec vs BMAD (Plus a Hands-On OpenSpec… was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.