OpenSpec vs Spec Kit: stop AI coding agents from drifting off spec
You prompt an AI agent to add CSV export to an Angular app. Keep it to visible rows. Use existing table data. Add no new dependencies. Three rounds of follow-up prompts later, the implementation pulls a CSV library and fetches every matching order from the API.
Nothing in those choices looks wrong in isolation. Together, they break every constraint you set. This is implementation drift, and it is the core problem spec-driven development (SDD) aims to address.
️ What SDD Actually Does
SDD puts requirements in written files kept in the repository instead of relying on a running conversation. The AI agent and human reviewer reference the same documents throughout the work. Prompts still happen, but each one focuses on the current problem rather than re-establishing every constraint from scratch.
The workflow creates four practical controls: a record of what may change and what must not, a reviewed technical plan before any code ships, a handoff document readable by a future session or a different developer, and a checklist to catch deviations between implementation and agreed scenarios.
Two tools implement this workflow differently: OpenSpec and Spec Kit.
OpenSpec: Change-Centric
OpenSpec organises work around a single proposed change. Its loop is Explore, Propose, Review, Apply, and Archive. Each change lives in openspec/changes/<change>/ and produces four core files:
- proposal.md: why the change is needed, what it touches, what it adds or modifies
- specs/<name>/spec.md: changed requirements and testable scenarios under ADDED, MODIFIED, or REMOVED headings
- design.md: technical approach, alternatives, and trade-offs (created when the change warrants it)
- tasks.md: ordered work items with checkbox progress tracking
A separate openspec/specs/ folder holds the current agreed system behaviour. Archiving a completed change updates those main specs and keeps the change documents as history.
Spec Kit: Feature-Centric
Spec Kit gives each feature a guided path: Specify, Plan, Tasks, Implement, and Converge. Shared project principles live in a constitution.md file. Feature documents follow a parallel structure:
- spec.md: user stories, requirements, edge cases, and acceptance scenarios with no technical design mixed in
- plan.md: technical approach, dependencies, code structure, and constraints checked against the constitution
- tasks.md: ordered implementation steps linked back to the user stories
An optional Analyze step checks consistency between spec, plan, and tasks before coding starts. Converge compares the resulting code against those documents and surfaces missing work. Both steps still require human review and tests that actually run against the code.
Making Acceptance Criteria Concrete
For the Angular CSV example, one scenario does real work:
Given 50 orders match the filter and 10 are visible on the current page, when I export, the file contains exactly those 10 orders in the same order.
If the file contains 50 orders, the implementation fails a requirement that was agreed before a single line of code was written. The plan can explicitly exclude new API calls and new dependencies. That constraint now has a test.
Which One to Pick
The author’s recommendation: use OpenSpec when managing individual changes while keeping system specs current. Use Spec Kit when a team wants a guided feature process with shared project principles and separate consistency checks.
Both tools work on new and existing projects. For small fixes, the documents cost more time than they save. For any feature with several constraints, start with a short spec, review the plan, and define the acceptance scenarios before touching the code.
I’m founder of BizStack at Cagri Sarigoz LLC and a passionate advocate for entrepreneurs.
With over 14 years in tech, marketing, and AI, including my role as Head of SEO at CitizenShipper and co-founder of TaleBot at Intale AI, I’m dedicated to sharing genuine, useful product insights and tips.
At BizStack, I aim to cut through the digital noise to provide clear, actionable advice.
And more than all else, I’m a father to a (always) little girl and a husband.
Contact me at [email protected] for assistance.
