Spec-driven development in practice: what months of AI-first delivery taught us
AI coding agents can write a feature in an afternoon. The hard part is making that feature match what the product owner meant, survive real hardware, and still make sense to the next developer.

Since summer 2026, our team has shipped production work on a connected-device product with an AI-first, spec-driven workflow. Claude writes most of the code, a written spec keeps it honest, and engineers own every decision. This post covers what we tried, what we measured, and the workflow we settled on.
Why AI agents need a spec
Spec-driven development (SDD) puts a short, reviewable specification between the ticket and the code. The agent proposes what it will build, a human corrects it, and only then does implementation start.
With a human developer, an unclear ticket costs a few questions at standup. With an AI agent, it costs a confident, well-structured implementation of the wrong thing. A spec turns that risk into a review step: mistakes get caught in a page of text, not in a thousand-line diff.
It also leaves a record. Every change carries its proposal, design decisions and requirements, so months later anyone can see why the code looks the way it does.

With an AI agent, an unclear ticket costs a confident, well-structured implementation of the wrong thing.
We built the same feature twice before choosing our tools
Before standardizing, we implemented one real feature twice: a firmware-upgrade flow for a connected device. It touched both a shared device-protocol library and the app layer on top. One run used GitHub’s Spec Kit with the Superpowers plugin, the other used OpenSpec. That gave us four pull requests to compare line by line.
| Aspect | Spec Kit + Superpowers | OpenSpec |
|---|---|---|
| Process | Up to 9 named steps, from constitution to converge | 5 steps: explore, propose, apply, sync, archive |
| Spec style | User stories and acceptance criteria, one folder per feature | Short Given/When/Then requirements, written as deltas to living specs |
| Brainstorming | Deep, surfaced many edge cases | Lighter, fewer edge cases surfaced |
| Tests on the app layer | 800+ lines, every block traced to a requirement | None |
| Code structure | Solid, with some waste | Cleaner in places |
| Time and tokens | High | Noticeably lower |
What the diffs showed:
- Rigor isn’t free. The heavier process produced a method written only to tick a task box and never called. It also left a code comment claiming a hardware check that the run’s own notes said never happened.
- Lighter can be cleaner. OpenSpec separated wire-protocol types from the service contract, and shared one error-handling helper where the other run repeated the logic.
- Test discipline came from the plugin, not the spec tool. The OpenSpec run shipped about 300 lines of new business logic with no tests. In the library, where both runs tested well, the gap disappeared.
- Waiting is a real cost. The longer pipeline meant long stretches of the developer watching the agent generate documents, without proportionally better code.
An honest caveat: this was one ticket, steered by one engineer, on different days. It informed a decision; it doesn’t prove one tool is better. We chose OpenSpec as our spec framework and added Superpowers for the discipline it lacks.
Our workflow: OpenSpec, powered by Superpowers
Every ticket moves through four phases, and each one ends at a human gate. We connect the two tools with superspec, an open-source OpenSpec schema that wires Superpowers skills into the spec pipeline.
- 1PlanBrainstorm, then proposal, design, delta specs and tasksGate: proposal review
- 2BuildImplement, test on mocks, then on real hardwareGate: works on the device
- 3CheckVerify against the spec, self-review, teammate reviewGate: clean review
- 4CloseArchive the change, merge, sync the ticketGate: specs match what shipped
The proposal review is the main human gate; review findings loop back into the build phase until the change is clean.
Plan. We refine the ticket, then run a Superpowers brainstorming session with the UX designs, the API documentation and related tickets attached. OpenSpec then writes a proposal, design notes, delta specs and a task list. It plans; it never touches code. Open questions go to the grooming meeting, and the decisions flow back into the spec.
Build. Claude implements on the feature branch in one synchronous session. We test in a mock environment first, with playground controls for every state, then on real hardware. Bugs go through systematic debugging: find the root cause, fix it, update the spec if behavior changed.
Check. Before anyone reviews the pull request, a verify step checks the code against every task, requirement and design decision. Then comes a self-review in a fresh session, then a teammate’s review. Findings go back into the build loop.
Close. We archive the change before merging, so the updated specs land together with the code. Then we sync the ticket with what actually shipped, including any scope that moved.
What engineers still own
The agent writes most of the code. Engineers own the parts where being wrong is expensive.
- Grounding. Our costliest early errors were invented API methods and response types that the device documentation never mentioned. Now we link the authoritative docs and ask “where in the doc do you see this?” for every unsourced claim.
- Design fidelity. Agents drift from the UX design on spacing, sizes and states. We attach the designs at implementation time and ask for a design-versus-screenshot comparison before manual testing.
- Hardware truth. Real device logs, pasted into the session or read live while debugging online, beat any assumption about how firmware behaves.
- Scope. When we want a spec or ticket edit, we say “no code changes”. Clear instructions prevent well-meant side effects.
Five lessons for teams adopting spec-driven development
- Pick the spec tool for your process, not its output volume. Heavier frameworks give a richer, Scrum-friendly paper trail and suit greenfield work. Lighter ones move faster on an evolving codebase with comparable code.
- Add test discipline on purpose. No spec tool guaranteed tests in our trial. Decide what is mandatory, such as end-to-end tests for user flows, and check it at verify time.
- Keep the spec alive. A spec that isn’t updated during implementation turns into fiction. Archiving it before merge keeps the main specs true.
- Match concurrency to your orchestration model. With a developer steering each ticket, one synchronous session is slower but uses fewer tokens and is easier to review, so it is our default. If you are building a full AI harness, parallel agents are the point, and the review gates belong inside the harness.
- Fix your test suite first. Broken tests confuse agents. We repair them in dedicated tickets before building on top.
Build with a team that already runs it
AI-first development doesn’t mean letting an agent run unsupervised. It means giving the agent a clear spec, checking its work against that spec, and keeping engineers accountable for every decision.
That is how akwit builds connected digital products today. If you are exploring spec-driven development, or want a partner who already runs it on production work, get in touch.
Get in touch
