-
Notifications
You must be signed in to change notification settings - Fork 1
Core‐Concepts
su edited this page Nov 18, 2025
·
3 revisions
Understanding the fundamental concepts behind Vibe's SPEC-driven development methodology.
- SPEC-driven Development
- EARS Syntax
- The 6-Question Framework
- Task Decomposition
- AI Agent System
- MCP Integration
- Workflow Philosophy
SPEC-driven Development is a methodology that puts requirements specification first before writing any code. Instead of diving straight into implementation, you:
- Clarify requirements through structured questions
- Document them in a machine-readable format (EARS)
- Plan technical architecture based on verified requirements
- Decompose into executable, testable tasks
- Implement with AI assistance
- Verify against original specifications
| Traditional Development | SPEC-driven Development |
|---|---|
| Idea → Code → Debug → Refactor | Idea → SPEC → Plan → Tasks → Code |
| Implicit requirements | Explicit EARS syntax |
| Ad-hoc implementation | Structured phases |
| Manual quality checks | 38 MCP tools for validation |
| Scope creep common | Acceptance criteria lock scope |
| Knowledge in developer's head | Knowledge in .vibe/ directory |
- ✅ 80% less requirement ambiguity - 6-question framework catches edge cases
- ✅ 3x faster planning - AI generates technical architecture
- ✅ Clear progress tracking - Phase-based task system with dependencies
- ✅ Higher code quality - 38 MCP tools for continuous validation
- ✅ Knowledge preservation - Everything documented in .vibe/
EARS (Easy Approach to Requirements Syntax) is a structured format for writing requirements that are:
- Unambiguous - Clear meaning with no interpretation needed
- Testable - Can verify if requirement is met
- Traceable - Links to acceptance criteria and tasks
| Keyword | Meaning | Use Case |
|---|---|---|
| WHEN | Trigger condition | User action or system event |
| WHERE | Precondition | System state or context |
| IF | Conditional logic | Feature flag or configuration |
| WHILE | Duration constraint | Ongoing process or background task |
| THEN | System response | What system SHALL/SHOULD/MAY do |
| SHALL | Mandatory requirement | Critical feature |
| SHOULD | Recommended | Nice-to-have feature |
| MAY | Optional | Future enhancement |
### REQ-XXX: Requirement Title **WHEN** <trigger condition> **THEN** system SHALL <mandatory action> #### Acceptance Criteria - [ ] Criterion 1 (testable) - [ ] Criterion 2 (testable) - [ ] Criterion 3 (testable) #### Priority: HIGH/MEDIUM/LOW #### Estimated Complexity: 1-5
### REQ-001: User Login **WHEN** user submits valid email and password **THEN** system SHALL: - Verify credentials against database - Generate JWT token with 24h expiry - Redirect to dashboard #### Acceptance Criteria - [ ] Invalid credentials show error message - [ ] JWT token includes user_id and role - [ ] Token stored in secure httpOnly cookie - [ ] Login attempt logged in audit table
### REQ-002: Email Notification **WHERE** user has email_notifications enabled **AND** user has not received notification in last 1 hour **WHEN** user receives a new comment **THEN** system SHALL send email notification #### Acceptance Criteria - [ ] Check user.settings.email_notifications = true - [ ] Query last_notification_sent timestamp - [ ] Send email only if 1+ hour passed - [ ] Update last_notification_sent after send
### REQ-003: Search Performance **WHEN** user searches for restaurant by name **THEN** system SHALL return results within 500ms (P95) **WHERE** database contains 1M+ restaurants **THEN** system SHALL use PostgreSQL full-text search with GIN index #### Acceptance Criteria - [ ] P95 latency < 500ms (load tested) - [ ] GIN index on restaurants.name_tsvector - [ ] Pagination with limit 20 results - [ ] Cache popular queries in Redis (1h TTL)
Vibe uses a structured 6-question interview to capture complete requirements.
Purpose: Understand the problem and desired outcome
Example:
Current: 15% weekly user churn
Problem: Excessive push notifications
Goal: Reduce churn to <10% by giving users control
ROI: Retain 5,000 users/month = 50ドルk MRR
Good Answers:
- Include metrics (current state + target)
- Explain business impact (revenue, retention, efficiency)
- Reference user pain points
Bad Answers:
- "Make the app better" (too vague)
- "Because manager said so" (no business case)
Purpose: Define user personas and system scale
Example:
Primary: All users (100k DAU)
Secondary: Support team (10 people)
Scale: 500k monthly active users
Growth: 20% MoM
Platform: 95% mobile (iOS/Android), 5% web
Good Answers:
- Specific user roles
- Quantified scale (DAU, MAU, QPS)
- Platform breakdown
- Growth expectations
Bad Answers:
- "Users" (which users?)
- "A lot of people" (how many?)
Purpose: Enumerate all features and edge cases
Example:
Core Features:
1. 6-category notification toggles:
- Likes (default: ON)
- Comments (default: ON)
- Follows (default: ON)
- Mentions (default: ON)
- Feed updates (default: OFF)
- Marketing (default: OFF)
2. Bulk actions:
- Enable all
- Disable all
3. Schedule (future):
- Quiet hours (10 PM - 8 AM)
- Weekend mode
Edge Cases:
- What if user disables all? → Show warning modal
- What if toggle fails? → Retry 3x, show error toast
- What about existing users? → Migrate with defaults
Good Answers:
- Numbered feature list
- Default values specified
- Edge cases considered
- Future enhancements marked
Bad Answers:
- "Notification settings" (not specific enough)
- No edge cases mentioned
Purpose: Define non-functional requirements
Example:
Performance:
- API response: P95 < 500ms
- UI toggle: < 100ms perceived latency
Scalability:
- 100k concurrent users
- 10M settings updates/day
Reliability:
- 99.9% uptime
- Data consistency (eventual is OK)
Security:
- Rate limiting: 100 req/min per user
- Authentication: JWT required
- Audit log: All changes logged
Caching:
- Redis: User settings (1h TTL)
- Invalidate on update
Good Answers:
- Specific metrics (P95, P99, QPS)
- Infrastructure decisions (Redis, PostgreSQL)
- Security constraints
- Monitoring and observability
Bad Answers:
- "Fast" (how fast?)
- "Secure" (what security measures?)
Purpose: Set realistic deadlines and prioritization
Example:
Development: 24 hours (3 days)
- Phase 1 (Backend): 8 hours
- Phase 2 (Frontend): 8 hours
- Phase 3 (FCM Integration): 4 hours
- Testing & Polish: 4 hours
Launch: December 1, 2025
Priority: HIGH (blocks Q4 OKR)
Dependencies:
- Requires FCM setup (already done)
- Requires PostgreSQL migration (2 hours)
Good Answers:
- Broken down by phase
- Development + testing time
- Priority level
- External dependencies
Bad Answers:
- "As soon as possible" (not specific)
- "1 week" (no breakdown)
Purpose: Document technology choices and constraints
Example:
Backend:
- Language: Python 3.11
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17 (existing)
- Cache: Redis 7.2 (existing)
- Authentication: JWT (existing)
Frontend:
- Framework: Flutter 3.24+
- State Management: Provider (existing)
- HTTP Client: Dio (existing)
Push Notifications:
- Service: Firebase Cloud Messaging
- Already integrated: Yes
Infrastructure:
- Cloud: GCP Cloud Run (existing)
- CI/CD: GitHub Actions (existing)
New Dependencies:
- None (100% stack reuse)
Good Answers:
- Specific versions
- Mark existing vs new
- Explain technology choices
- List new dependencies
Bad Answers:
- "Python and React" (no versions)
- "Whatever is best" (no decision)
Vibe decomposes features into 3 standard phases:
- Phase 1: Backend - API, database, business logic
- Phase 2: Frontend - UI, state management, API integration
- Phase 3: Integration - E2E testing, deployment, monitoring
### Task X-Y: Task Title ⬜ **Description**: One-sentence summary **Implementation**: 1. Step 1 (concrete action) 2. Step 2 (concrete action) 3. Step 3 (concrete action) **Acceptance Criteria**: - [ ] Criterion 1 (testable) - [ ] Criterion 2 (testable) **Dependencies**: Task X-Z (if any) **Estimated Time**: N hours **Files Changed**: - path/to/file.py (created/modified)
Tasks include dependency information for parallel execution:
Phase 1: Backend
├── Task 1-1: Database Migration ⬜ (no deps)
├── Task 1-2: Repository Layer ⬜ (depends on 1-1)
├── Task 1-3: Service Layer ⬜ (depends on 1-2)
├── Task 1-4: API Endpoints ⬜ (depends on 1-3)
└── Task 1-5: Unit Tests ⬜ (depends on 1-4)
# Parallel execution possible:
# - Task 1-1 alone
# - Then Task 1-2
# - Then Task 1-3
# - Then Task 1-4 + 1-5 (parallel)
| Symbol | State | Meaning |
|---|---|---|
| ⬜ | Pending | Not started |
| 🔄 | In Progress | Currently working |
| ✅ | Done | Completed and verified |
| ❌ | Blocked | Cannot proceed (dependency issue) |
| Needs Review | Implementation done, review pending |
Vibe automatically selects the appropriate agent based on:
- CLAUDE.md - Tech stack documentation in project root
- Task context - Backend/Frontend/Database/Quality phase
- File extensions - .py → Python agent, .dart → Flutter agent
User runs: vibe run "Task 1-1"
↓
Vibe reads .vibe/tasks/feature-name.md
↓
Detects task phase (Backend/Frontend/Integration)
↓
Reads CLAUDE.md for tech stack
↓
Selects agent (e.g., Backend Python Expert)
↓
Agent generates implementation guide
↓
Saves to .vibe/guides/task-1-1.md
↓
Agent executes with MCP tools
↓
Verifies acceptance criteria
↓
Updates task status: ⬜ → ✅
| Agent | Tech Stack | Use Cases |
|---|---|---|
| Specification Agent | Language-agnostic | Requirements gathering (Q1-Q6) |
| Planning Agent | Cross-stack | Architecture, cost analysis, timeline |
| Task Agent | Cross-stack | Task decomposition, dependency graph |
| Backend Python Expert | Python 3.11+, FastAPI, SQLAlchemy | Python backend implementation |
| Frontend Flutter Expert | Flutter 3.24+, Dart 3.5+ | Flutter mobile/web app |
| Frontend React Expert | React 18+, Next.js 14+ | React web app |
| Database PostgreSQL Expert | PostgreSQL 17, PostGIS 3.4+ | Database design, migrations |
| Quality Reviewer | Multi-language | Code review, quality validation |
MCP (Model Context Protocol) is a standard for AI tools to access development utilities. Vibe includes 38 MCP tools across 7 categories.
-
analyze_complexity- Cyclomatic and cognitive complexity -
validate_code_quality- Code scoring and recommendations -
check_coupling_cohesion- Module coupling analysis -
suggest_improvements- Refactoring suggestions -
apply_quality_rules- Enforce coding standards
-
find_symbol- Locate function/class definitions -
find_references- Find all usages of symbols
-
create_thinking_chain- Step-by-step reasoning -
step_by_step_analysis- Detailed problem breakdown -
analyze_problem- Structured problem analysis -
break_down_problem- Decompose complex problems -
think_aloud_process- Explain reasoning -
format_as_plan- Convert analysis to plan
-
save_memory- Store project context -
recall_memory- Retrieve stored information -
search_memories- Search by keyword -
update_memory- Modify existing memory -
delete_memory- Remove outdated memory -
list_memories- View all stored memories -
auto_save_context- Automatic checkpointing -
start_session- Begin new session
-
preview_ui_ascii- Generate ASCII UI mockups
-
analyze_requirements- Extract requirements from text -
create_user_stories- Generate user stories -
feature_roadmap- Generate feature timeline -
generate_prd- Create Product Requirements Document
-
analyze_prompt- Evaluate prompt quality -
enhance_prompt- Improve prompt effectiveness
# Example: Backend Python Expert uses MCP tools # Step 1: Analyze existing code complexity = mcp.analyze_complexity("src/service.py") if complexity.cyclomatic > 10: suggestions = mcp.suggest_improvements("src/service.py") # Step 2: Find related code symbol = mcp.find_symbol("UserService") references = mcp.find_references("UserService") # Step 3: Plan refactoring chain = mcp.create_thinking_chain( "Refactor UserService to reduce complexity" ) # Step 4: Implement with quality checks # ... write code ... quality = mcp.validate_code_quality("src/service.py") # Step 5: Save context for next session mcp.save_memory({ "task": "Refactor UserService", "complexity_before": 15, "complexity_after": 8, "files_changed": ["src/service.py", "src/user_repo.py"] })
- Specification First - No code without requirements
- Incremental Progress - Phase-by-phase execution
- Continuous Validation - MCP tools at every step
- Knowledge Preservation - Everything in .vibe/
- AI-Augmented - Agents assist, humans verify
Clarify Requirements (SPEC)
↓
Generate Plan (Technical Architecture)
↓
Decompose Tasks (Phase-based)
↓
Execute with AI (Agent + MCP)
↓
Verify Implementation (Against SPEC)
↓
Analyze Quality (MCP Tools)
↓
Iterate or Complete
❌ Skipping SPEC phase - "Let's just start coding" ✅ Answer 6 questions first
❌ Running all tasks at once - vibe run --all
✅ Execute phase by phase with verification
❌ Ignoring acceptance criteria - "Looks good enough" ✅ Check every criterion before marking done
❌ Not using MCP tools - "I'll review manually" ✅ Leverage 38 tools for continuous validation
❌ Forgetting CLAUDE.md - Agent picks wrong tech stack ✅ Document your stack once, benefit forever
- SPEC-driven Development puts requirements first, eliminating ambiguity
- EARS Syntax provides unambiguous, testable requirements
- 6-Question Framework captures complete requirements through structured interview
- Task Decomposition breaks features into phase-based, dependency-aware tasks
- AI Agents provide specialized expertise for different tech stacks
- MCP Integration offers 38 tools for continuous quality validation
- Workflow Philosophy emphasizes incremental progress and knowledge preservation
Next Steps:
- Command Reference - Learn all CLI commands
- MCP Integration - Explore 38 tools in detail
- Agents Guide - Master specialized agents
- Examples - See real-world workflows
← Back to Getting Started | Home | Next: Command Reference →