A new arXiv paper studied how developers really use spec-driven development (SDD) with coding agents. Implementation detail in a spec may help the agent, but it makes the spec prone to decay, and people mostly compare spec and code when a change is finished. Among the four Claude Code SDD skills we rank, one enforces that comparison with scripts.
What did the spec-driven development study find?
The paper is Spec-Driven Development as Prescribed and as Practiced (arXiv 2608.25202), by Shyam Agarwal, Anmol Singhal, Andrew Macvean, Bogdan Vasilescu and Travis Breaux. It was first posted on August 25, 2026, and the current version (v4) is dated October 15, 2026.
The authors note that most evidence about SDD so far comes from tool vendors. So they went to practitioners instead: a thematic analysis of Reddit discussions, interviews with 21 practitioners (eight of whom build SDD tools), and a look at 266 active, popular repositories. Those repos come from SpecMine, a corpus of 470,795 spec files from 73,030 public GitHub repositories, which the authors release with the paper.
The abstract reports five things that matter for agent skills:
- Practitioners agree a spec should capture intent, but many specs also carry implementation details.
- SDD gets used selectively, mostly for new features.
- People see more reliable agent behavior, and pay for it with more planning and review time.
- Implementation detail may help agents while making specs prone to decay.
- Participants described spec-code checks "mainly when changes are completed rather than over time."
We maintain a guide to spec-driven development skills for Claude Code, so we reread the SKILL.md of each of the four skills it ranks against those findings. Install counts below are from the skills.sh registry as of October 23, 2026.
Should a spec for a coding agent include implementation details?
The four skills disagree, and the disagreement lines up with the paper's trade-off.
spec-driven-development skill by addyosmani (GitHub: addyosmani/agent-skills) is the most installed, at 63,637 installs. Its spec has six required areas: objective, commands, project structure, code style, testing strategy and boundaries. Half of those describe how the thing gets built. You give the agent exact build and test commands with flags, a directory layout, and a real code snippet that shows your style. That is the "detail helps the agent" side of the trade-off.
spec-driven-implementation skill by warpdotdev (GitHub: warpdotdev/common-skills), at 28,685 installs, splits the two concerns into files. PRODUCT.md stays behavior-oriented and light on implementation. TECH.md holds the how, and gets written when warranted, for example when the work spans multiple subsystems, when architecture or extensibility matters, when there are real tradeoffs to document, or when reviewers gain more from the plan than from the raw code.
spec-driven-development skill from jasonkneen/kiro (GitHub: jasonkneen/kiro), at 426 installs, lists implementation details in requirements as a pitfall. Requirements say what, the separate design document says how.
If the paper's decay finding matches what you've seen in your own repo, the warpdotdev split is the practical takeaway: a product spec that rarely needs edits, and a tech spec you expect to churn.
When should you skip spec-driven development?
The study found SDD used selectively, mostly for new features. Every one of these skills tells the agent to do exactly that:
- warpdotdev's skill names an expected implementation of about 1,000 lines or more as a reason to write specs. It calls them often unnecessary for small, local bug fixes, straightforward refactors and narrow UI tweaks.
- addyosmani's skill excludes single-line fixes, typo corrections and changes whose requirements are already unambiguous.
- tlc-spec-driven sizes itself. A change that touches three files or fewer and fits in one sentence gets a one-line inline spec and skips the Design and Tasks phases.
- kiro's skill marks simple bug fixes, rapid prototypes and urgent hotfixes as less suitable.
So when practitioners say they only use SDD sometimes, that is the intended behavior, and the skill authors wrote it down.
How do SDD skills handle the extra planning and review cost?
The paper links SDD to more reliable agents and to higher planning and review cost. The skills pay that cost in different places.
addyosmani's skill pays it up front. Before writing the spec, the agent lists its assumptions so you can correct them. After saving the spec, it summarizes it, lists open questions and ends its turn. Planning starts only after you approve in a later turn, and a human reviews after each of Specify, Plan, Tasks and Implement. Its boundaries come in three tiers (Always, Ask first, Never), so decisions like schema changes or new dependencies are settled once in the spec instead of argued in every review. Tasks are capped at about 5 changed files each, which keeps each review small.
kiro's skill makes review cheaper per item. Each acceptance criterion uses EARS notation:
WHEN [event] THEN [system] SHALL [response]
A criterion in that shape turns straight into a test, and each task carries references back to the requirements it implements. Pair it with a test-first flow like the one in our TDD skill guide for Claude Code.
Which Claude Code skill checks the spec against the code?
tlc-spec-driven skill by tech-leads-club (GitHub: tech-leads-club/agent-skills), at 1,185 installs, is the one that hands the check to code. It ships Python scripts that validate the spec (EARS criteria, requirement IDs), the task list and each commit message. It requires one atomic commit per task. Every acceptance criterion gets a check with the test command that proves it. After the last task, a script runs all of those proofs at HEAD, and then a fresh verifier sub-agent, which never wrote the code, tries mutations to find rules that would stay green when they shouldn't.
Look at the timing, though. The proofs run once, after the last task. That is the pattern the paper describes: checks at completion, not over time. tlc has one partial answer. When you resume in a new session, it reconciles its .specs/ files against git, and the git evidence wins over a note.
warpdotdev and addyosmani treat decay as a process problem. warpdotdev's skill wants PRODUCT.md and TECH.md updated in the same PR as the code that changed them. When a spec cites code, it pins the commit SHA and links the exact lines, so a stale reference is easy to spot. addyosmani's skill says to update the spec before you implement a changed decision, commit the spec, and link the relevant spec section from each PR.
None of the four runs a continuous spec-versus-code check on every push. That is the gap the paper points at. tlc's scripts need only the Python 3.8+ standard library, which makes them the obvious place to start if you want to try it. We haven't wired them into CI ourselves.
How do you install these spec-driven development skills?
npx skills add https://github.com/addyosmani/agent-skills --skill spec-driven-development
npx skills add https://github.com/warpdotdev/common-skills --skill spec-driven-implementation
npx skills add https://github.com/jasonkneen/kiro --skill spec-driven-development
npx skills add https://github.com/tech-leads-club/agent-skills --skill tlc-spec-driven
If your team already uses GitHub's Spec Kit, there are two more options. The speckit-plan skill from dceoy/speckit-agent-skills (GitHub: dceoy/speckit-agent-skills) has 2,443 installs. The spec-kit-skill by feiskyer (GitHub: feiskyer/claude-code-settings, 665 installs) checks for the specify CLI and guides setup.
Which one should you pick?
Start with addyosmani's skill for a gated default. Move to warpdotdev's when your team writes specs per ticket and you want product intent kept apart from implementation detail. Pick tlc-spec-driven when you want scripts to hold the gates and run the final spec-code check. After the spec is approved, a pattern like subagent-driven development for Claude Code can take over execution.
For the wider field, see the best skills for docs and planning ranking, the docs and planning category, or the full list of Skillselion guides.
Disclosure: we run Skillselion, the directory these install counts come from. It's a live catalog, refreshed daily from skills.sh, GitHub and MCP registries, ranked by real installs. We are not affiliated with Anthropic, OpenAI or Cursor, or with the paper's authors.
Top comments (0)