Using Spec-Driven Development

Introduction

This blog shares experiences and insights from adopting Claude Code and spec-driven development frameworks, specifically Spec-Kit. The post covers what Spec-Kit is, how to use it, and the benefits it brings to structuring development, reducing guesswork, and improving collaboration between humans and coding agents.

What is spec-driven development

The author began with LLM-assisted coding when ChatGPT launched, copying code between browser and IDE. Larger projects revealed context window degradation issues. Separate chat instances helped temporarily, but fundamental disconnects remained—particularly with cross-file references where LLMs would hallucinate methods and attributes.

Claude Code changed this by bringing the LLM directly into the codebase, providing real context about actual methods and attributes. However, this freedom introduced new problems: context limitations persisted, and untracked changes across files became common. Token limits further complicated matters.

Spec-Kit

Spec-driven development uses code specification documents as the foundation for executable tasks. Traditionally, developers read specs then began work, with the spec losing importance as the codebase evolved. LLMs now enable developers to invest more cycles in detailed upfront planning.

For more information, check out their Git repo.

/Speckit.Constitution

This establishes guiding principles for the coding agent. A constitution prompt typically reads: “Create principles based on quality, testing, user experience, and performance.”

Similar to a CLAUDE.md file, the constitution acts as rule-based guidance for the LLM. However, the constitution is project-oriented and changes infrequently, whereas CLAUDE.md documents coding conventions and operational guidance, evolving as projects grow.

The distinction: CLAUDE.md explains how the AI should operate; the Constitution defines what must be done and what must never be done.

/Speckit.specify

This command lets users define what the project is—through a user experience lens, not technical terms. Think like a product manager, focusing on outcomes rather than the tech stack.

Claude generates a Spec Markdown document providing a high-level project overview grounded in user scenarios and test cases, including robust requirements validatable after development.

/Speckit.Clarify

This refines requirements or user scenarios not fully covered initially. As the creator of Claude Code notes, “pour your energy into the plan.”

An automatically generated quickstart.md file typically includes project setup commands, usage guidance, and test automation details—delivering well-documented solutions without busywork.

/Speckit.Plan

Run once the spec is complete. Plan uses requirements, user scenarios, and the tech stack to generate detailed implementation steps in smallest practical units. It includes architecture overviews, component descriptions, and key technical decisions with rationale.

Claude and Speckit update the CLAUDE.md file during refinement to capture critical information about requirements and tech stack decisions.

/Speckit.tasks

Tasks reads the Plan and produces dozens of concrete implementation steps, organized by category or user story. This prevents “slopification” by enforcing structured, documented, and rationalized change—unlike native LLM development with untracked changes.

My first time using Speckit, I was in awe watching it create its own implementation checklist based on a thorough Plan, then execute it while checking off tasks progressively.

/Speckit.analyze

Analyze is an overlook command. After /Speckit.tasks but before /Speckit.implement, tasks can be analyzed for consistency and coverage across the codebase.

Here, one HIGH priority issue creating inconsistency across the codebase was easily resolved using this detailed analysis. This would’ve been compounded without taking one extra step to resolve it.

Integrating with Git for version control

Spec-Kit, built by the GitHub team, integrates tightly with Git version control. When a spec is created, it prefers working in a separate repository branch.

Changes develop in isolation, then merge into the main branch, keeping main clean while preserving spec-based branches as clear, auditable units of work.

Takeaways

• Introduce features or bug-fixes through specs to add structure and reduce guesswork and repeated reworking
• Use CLAUDE.md and Constitution.md to require thorough test cases and clear decision rationale
• Spend most energy on Planning to avoid cleanup cycles—address user scenarios, requirements, and edge cases upfront, using /Speckit.clarify and /Speckit.analyze to verify gaps and consistency