I’ve been using Claude Code extensively, and one thing kept bothering me: jumping straight into implementation without proper planning. I know the planning mode exist but I wanted something more than that. We’ve all been there-you start coding a feature, realize halfway through that you missed a requirement, then refactor, then discover an edge case that break your design.
So I built a plugin to fix that. Inspired by Kiro’s spec-driven approach, I created a Claude Code plugin that forces you (in a good way) to think through Requirements, Design, and Tasks before writing a single line of code.
The Problem with “Just Start Coding”
When you ask Claude to build a feature, it’s eager to help. Sometimes too eager. It’ll start writing code immediately, making assumptions about:
What the user actually wants
How the feature should behave in edge cases
What the data model should look like
How it integrates with existing code
The result? You end up with code that works for the happy path but fails apart when reality hits.
Enter Spec-Driven Development
The idea is simple: before implementation, create a formal specification that covers:
Requirements - What should the system do? (Using EARS notation)
Design - How will we build it? (Architecture, data models, APIs)
Tasks - What are the discrete steps? (Trackable, dependency-aware)
Only after these three phases are complete do you start writing code. And here’s the key: Claude can still do all the heavy lifting, but now it’s guided by a structured spec.
How the Plugin Works
Installation
Add this to your
~/.claude/settings.json{
"enabledPlugins": {
"spec-driven@spec-driven": true
},
"extraKnownMarketplaces": {
"spec-driven": {
"source": {
"source": "github",
"repo": "Habib0x0/spec-driven-plugin"
}
}
}
}Restart Claude Code, and you’ll have access to five new commands.
The Commands
/spec <feature-name>- Start a new spec with the 3-phase workflow/spec-refine- Update requirements or design/spec-tasks- Regenerate tasks from the spec/spec-status- Check Progress/spec-validate- Validate completeness and consistency/spec-exec- Run on autonomous implementation iterationspec-loop- Loop implementation until all tasks complete
Walkthrough: Building a User Authentication Feature
Let’s say you want to add user authentication to your app. Instead of asking
Claude to “add login functionality,” you run:
/spec user-authentication Claude will guide you through each phase.
Phase 1: Requirements
First, Claude asks clarifying questions:
What authentication methods? (email/password, OAuth, magic links?)
What user roles exist?
Password requirements?
Session handling?
Then it writes user stories with EARS notation (Easy Approach to
Requirements Syntax):
### US-1: User Login
**As a** registered user
**I want** to log in with my email and password
**So that** I can access my account
#### Acceptance Criteria (EARS)
1. WHEN a user submits valid credentials
THE SYSTEM SHALL authenticate the user and create a session
2. WHEN a user submits invalid credentials
THE SYSTEM SHALL display an error message without revealing which field
was incorrect
3. WHEN a user fails authentication 5 times
THE SYSTEM SHALL lock the account for 15 minutesNotice how each criterion is testable and unambiguous. No vague words like “quickly’ or “properly”
Phase 2: Design
With requirements locked, Claude produces the technical design:
• Architecture Overview — Components and their relationships
• Data Models — User schema, session schema
• API Design — Endpoints, request/response formats
• Sequence Diagrams — Login flow, token refresh flow
• Security Considerations — Password hashing, rate limiting, CSRF protection
This phase catches architectural issues before you write code. “Wait, should
we use JWTs or server-side sessions?” gets answered here, not during a
midnight debugging session.
Phase 3: Tasks
Finally, Claude breaks down the design into trackable tasks:
### T-1: Set up authentication dependencies
- **Status**: pending
- **Requirements**: US-1, US-2
- **Description**: Install bcrypt, jsonwebtoken, set up middleware
structure
- **Acceptance**: Dependencies installed, middleware skeleton in place
- **Dependencies**: none
### T-2: Implement User model
- **Status**: pending
- **Requirements**: US-1
- **Description**: Create User schema with email, passwordHash,
loginAttempts, lockedUntil
- **Acceptance**: Model created with validation, indexes on email
- **Dependencies**: T-1
### T-3: Implement login endpoint
- **Status**: pending
- **Requirements**: US-1
- **Description**: POST /auth/login with rate limiting and account lockout
- **Acceptance**: All US-1 acceptance criteria pass
- **Dependencies**: T-1, T-2These tasks sync to Claude Code’s built-in todo system, so you can track progress as you implement.
The Spec Files
Everything gets saved to
.claude/specs/user-authentication/.claude/specs/user-authentication/
├── requirements.md # User stories + EARS criteria
├── design.md # Architecture documentation
└── tasks.md # Implementation tasksWhen you later work on this feature, Claude automatically loads these files as context. It knows what you’re building, why, and what’s left to do.
Why EARS Notation?
EARS (Easy Approach to Requirements Syntax) forces you to write testable requirements. The format is:
WHEN [condition/trigger]
THE SYSTEM SHALL [expected behavior]Variations include:
WHILE [state]- For ongoing conditionsIF [condition], WHEN [trigger]- For conditional behaviorTHE SYSTEM SHALL NOT- For negative requirements
This eliminates ambiguity. Compare:
X “The system should handle errors gracefully”
√ “WHEN an API request fails after 3 retries, THE SYSTEM SHALL display a user-friendly error message and log the failure details”
Validation
Before implementation, run /spec-validate. The plugin checks:
All user stories have EARS acceptance criteria
Design addresses every requirement
Tasks trace back to requirements
No circular dependencies in tasks
No vague language (”fast”, “easy”, “properly”)
If something’s missing, you fix it in the spec—not in the code.
Phase 4: Autonomous Execution
Planning is great, but at some point you need to build the thing. The latest update adds two execution modes that let Claude implement your spec autonomously-one task at a time, with commits along the way.
This is based on the “Ralph Loop” technique: build a prompt from your spec files, hamd it to Claude with —gangerously-skip-permissions, or —permissions-mode AcceptEdits, and let it work. Each iteration, Claude picks the highest-priority task, implements it, runs tests, updates the spec, and commits. Simple and effective.
Single Iteration: spec-exec
spec-exec.sh —spec-name user-authentication Claude reads your spec, picks one task, implements it, and commits. You review the result, then run it again for the next task. Good for when you want to stay in the loop.
Loop Until Done: spec-loop
spec-loop.sh —spec-name user-authentication —max-iterations 20 This wraps the same login in a while loop, Each iteration re-reads the spec files (picking up changes from previous run), runs Claude, and checks the output for a completion signal. When Claude sees all tasks are done, it outputs <promise>COMPLETE</promise> and the loop exists.
You get progress output each round:
=== Spec Loop: Iteration 1 / 20 ===
... Claude implements T-1, commits ...
--- Iteration 1 done. Continuing... ---
=== Spec Loop: Iteration 2 / 20 ===
... Claude implements T-2, commits ...
--- Iteration 2 done. Continuing... ---
=== Spec Loop: Iteration 3 / 20 ===
... Claude sees all tasks complete ...
All tasks complete!Ctrl+C to stop early. The —max-iterations flag (default: 50) prevents runaway loops.
Why This Works
The spec is the contract. Each Claude invocation gets the full context-requirements, design,, and the current state of tasks. It knows what’s been done and what’s left. Because the spec files are updated and committed each iteration, the next run picks up exactly where the last one left off.
No state files, no database, no complex orchestration. Just spec files, a bash script, and Claude.
When to Use this
Spec-Driven development adds overhead. It’s not for every task. Use it when:
Building a new feature with multiple components
The requirements aren’t crystal clear
Multiple people will work on the implementation
You need documentation for future reference
The feature touches security, payments, or other sensitive areas
Skip it for:
Quick bug fixes
One-line changes
Prototypes you’ll throw away
Try it out
The plugin is open source:
GitHub: github.com/Habib0x0/spec-driven-plugin
https://github.com/Habib0x0/spec-driven-plugin
Install it, run /spec on your next feature, and let me know what you
think. I’m particularly interested in:
• Edge cases I haven’t handled
• Improvements to the EARS templates
• Integration ideas (Jira? Linear? GitHub Issues?)
Resources
https://www.anthropic.com/engineering/effective-harnesses-for-long-running-agents
https://www.aihero.dev/events/turn-ai-agents-into-autonomous-software-engineers-with-ralph
https://ghuntley.com/loop/
This plugin was inspired by Kiro https://kiro.dev’s spec-driven development functionality.