An intelligent requirements gathering system for Claude Code that progressively builds context through automated discovery, asks simple yes/no questions, and generates comprehensive requirements documentation.
This system transforms the requirements gathering process by:
- Codebase-Aware Questions: AI analyzes your code first, then asks informed questions
- Simple Yes/No Format: All questions are yes/no with smart defaults - just say "idk" to use defaults
- Two-Phase Questioning: 5 high-level questions for context, then 5 expert questions after code analysis
- Automated Documentation: Generates comprehensive specs with specific file paths and patterns
- Product Manager Friendly: No code knowledge required to answer questions
# Start gathering requirements for a new feature
/requirements-start add user profile picture upload
# Continue active requirement OR view/list specifications
/requirements-current # Continue active requirement
/requirements-current dark-mode # View specific specification
/requirements-current --all # List all specifications
# End current requirement gathering
/requirements-end
# Universal focus correction and task reminder
/requirements-focus# Begin implementing the active specification
/requirements-implement
# Or implement a specific completed specification
/requirements-implement user-authenticationclaude-requirements/
├── commands/ # Claude command definitions
│ ├── requirements-start.md # Begin new requirement gathering
│ ├── requirements-current.md # Central hub: continue/view/list specs
│ ├── requirements-focus.md # Universal focus correction
│ ├── requirements-implement.md # Begin implementation from spec
│ └── requirements-end.md # Finalize requirement gathering
│
├── requirements/ # Requirement documentation storage
│ ├── .current-requirement # Tracks active requirement
│ ├── index.md # Summary of all requirements
│ └── YYYY-MM-DD-HHMM-name/ # Individual requirement folders
│ ├── metadata.json # Status and progress tracking
│ ├── 00-initial-request.md # User's original request
│ ├── 01-discovery-questions.md # 5 context questions
│ ├── 02-discovery-answers.md # User's answers
│ ├── 03-context-findings.md # AI's code analysis
│ ├── 04-detail-questions.md # 5 expert questions
│ ├── 05-detail-answers.md # User's detailed answers
│ └── 06-requirements-spec.md # Final requirements
│
└── examples/ # Example requirements
User: /requirements-start add export functionality to reports
AI analyzes the entire codebase structure to understand the architecture, tech stack, and patterns.
The AI asks 5 yes/no questions to understand the problem space:
Q1: Will users interact with this feature through a visual interface?
(Default if unknown: YES - most features have UI components)
User: yes
Q2: Does this feature need to work on mobile devices?
(Default if unknown: YES - mobile-first is standard)
User: idk
AI: ✓ Using default: YES
[Continues through all 5 questions before recording answers]
AI autonomously:
- Searches for specific files based on discovery answers
- Reads relevant code sections
- Analyzes similar features in detail
- Documents technical constraints and patterns
With deep context, asks 5 detailed yes/no questions:
Q1: Should we use the existing ExportService at services/ExportService.ts?
(Default if unknown: YES - maintains architectural consistency)
User: yes
Q2: Will PDF exports need custom formatting beyond the standard template?
(Default if unknown: NO - standard template covers most use cases)
User: no
[Continues through all 5 questions before recording answers]
Generates comprehensive spec with:
- Problem statement and solution overview
- Functional requirements from all 10 answers
- Technical requirements with specific file paths
- Implementation patterns to follow
- Acceptance criteria
User: /requirements-implement
AI analyzes the specification and:
- Loads project context (CLAUDE.md if available)
- Verifies specification completeness
- Plans implementation phases and subagent coordination
- Creates implementation strategy
Based on scope, AI either:
- Single Agent: Handles simple specs in current session
- Coordinated Agents: Delegates complex work to specialized subagents
- Frontend components → UI specialist
- Backend APIs → Service specialist
- Database changes → Data specialist
- Testing → QA specialist
- Tests against acceptance criteria from specification
- Validates implementation follows project patterns
- Ensures all requirements are satisfied
- Reports final status and integration points
Begins gathering requirements for a new feature or change.
Example:
/requirements-start implement dark mode toggle
Central hub for requirements management.
No arguments - Continue Active:
📋 Active Requirement: dark-mode-toggle
Phase: Discovery Questions
Progress: 3/5 questions answered
Next: Q4: Should this sync across devices?
With spec-id - View Specific:
/requirements-current dark-mode
📋 Requirement: Dark Mode Toggle
Status: Complete | Ready for implementation
[Shows complete specification details]
With --all flag - List All:
/requirements-current --all
📚 All Requirements:
🔴 ACTIVE: profile-upload (Discovery 3/5)
✅ COMPLETE: dark-mode, user-auth
⚠️ INCOMPLETE: notifications (paused 3 days ago)
Finalizes current requirement, even if incomplete.
Options:
- Generate spec with current info
- Mark incomplete for later
- Cancel and delete
Shows all requirements with their status.
Output:
✅ COMPLETE: dark-mode-toggle (Ready for implementation)
🔴 ACTIVE: user-notifications (Discovery 3/5)
⚠️ INCOMPLETE: data-export (Paused 3 days ago)
Universal focus correction and task reminder.
In requirements mode: Reminds AI to gather specs, not implement Outside requirements: General focus and task reminder
Use when AI:
- Asks open-ended questions
- Starts implementing code
- Gets distracted from current task
- Asks multiple questions at once
Begin implementation based on completed specification.
No argument - Active Spec:
/requirements-implement
🚀 IMPLEMENTATION MODE: user-authentication
📖 Project context loaded from CLAUDE.md
📋 Implementation plan: 4 phases, 12 tasks
🤖 Coordination: Using frontend + backend subagents
With spec-id - Specific Spec:
/requirements-implement dark-mode
🚀 IMPLEMENTATION MODE: dark-mode-toggle
📋 Scope: Simple single-agent implementation
⚠️ No CLAUDE.md found - using generic patterns
- Requirements Gathering: Systematic specification creation
- Smart Implementation: Context-aware code generation
- Subagent Coordination: Specialized agents for complex work
- Quality Assurance: Testing against acceptance criteria
Every question includes an intelligent default based on:
- Best practices
- Codebase patterns
- Context discovered
- Phase 1: Analyzes codebase structure first
- Phase 2: 5 high-level questions for product managers
- Phase 3: Autonomous deep dive into relevant code
- Phase 4: 5 expert questions based on code understanding
- All files created automatically
- Progress tracked between sessions
- Can resume anytime
- Links to development sessions
- References PRs and commits
- Searchable requirement history
- Be Specific: Clear initial descriptions help AI ask better questions
- Use Defaults: "idk" is perfectly fine - defaults are well-reasoned
- Stay Focused: Use
/remindif AI goes off track - Complete When Ready: Don't feel obligated to answer every question
- One Feature at a Time: Keep requirements focused
- Think Implementation: Consider how another AI will use this
- Document Decisions: The "why" is as important as the "what"
- Link Everything: Connect requirements to sessions and PRs
- Clone this repository:
git clone https://github.com/rizethereum/claude-code-requirements-builder.git- Copy the commands to your project:
cp -r commands ~/.claude/commands/
# OR for project-specific
cp -r commands /your/project/.claude/commands/- Create requirements directory:
mkdir -p requirements
touch requirements/.current-requirement- Add to
.gitignoreif needed:
requirements/
/requirements-start add user avatar upload
# AI analyzes codebase structure
# Answer 5 yes/no questions about the feature
# AI autonomously researches relevant code
# Answer 5 expert yes/no questions
# Get comprehensive requirements doc with file paths
/requirements-start fix dashboard performance issues
# Answer questions about scope
# AI identifies problematic components
# Answer questions about acceptable solutions
# Get targeted fix requirements
/requirements-start improve mobile navigation experience
# Answer questions about current issues
# AI analyzes existing navigation
# Answer questions about desired behavior
# Get detailed UI requirements
- Fork the repository
- Create your feature branch
- Add new commands or improve existing ones
- Submit a pull request
- Add requirement templates for common features
- Create requirement validation commands
- Build requirement-to-implementation tracking
- Add multi-language question support
MIT License - Feel free to use and modify for your projects.
Inspired by @iannuttall's claude-sessions project, which pioneered the concept of structured session management for Claude Code.
Remember: Good requirements today prevent confusion tomorrow!