Skip to content

Navigation Menu

Sign in
Sign up

Getting‐Started

su edited this page Nov 18, 2025 · 2 revisions

Getting Started with Vibe

This guide will help you install Vibe and create your first SPEC-driven project in under 5 minutes.

Prerequisites

Before installing Vibe, ensure you have:

  • Node.js 18.0.0 or higher
  • npm 7.0.0 or higher
  • Claude Code (for slash commands and MCP integration)

Check your versions:

node --version # Should be v18.0.0+
npm --version # Should be 7.0.0+

Installation

1. Install Vibe globally

npm install -g @su-record/vibe

This will:

  • ✅ Install the Vibe CLI
  • ✅ Install @su-record/hi-ai MCP server (38 development tools)

Note: The MCP server is registered per-project when you run vibe init.

2. Verify installation

vibe help

Expected output:

Vibe - SPEC-driven AI coding framework
Usage:
 vibe <command> [options]
Commands:
 init Initialize Vibe in current project
 spec <name> Create specification
 plan <name> Generate technical plan
 tasks <name> Decompose into tasks
 run <task> Execute task
 ...

Initialize Your First Project

1. Navigate to your project directory

cd /path/to/your/project

2. Initialize Vibe

vibe init

This will:

  • ✅ Create .vibe/ directory structure
  • ✅ Register MCP server for this project only (local configuration)

Verify MCP server (in your project directory):

claude mcp list

Expected output:

vibe: node /path/to/@su-record/vibe/node_modules/@su-record/hi-ai/dist/index.js - ✓ Connected

Project structure created:

your-project/
├── .vibe/
│ ├── config.json # Vibe configuration
│ ├── specs/ # Specifications (EARS format)
│ ├── features/ # BDD Feature files (Gherkin)
│ ├── plans/ # Technical plans
│ ├── tasks/ # Task breakdowns
│ ├── guides/ # Task implementation guides
│ └── reports/ # Analysis reports
└── CLAUDE.md # Tech stack documentation (optional)

3. (Optional) Document your tech stack

Create CLAUDE.md in your project root for automatic tech stack detection:

# CLAUDE.md
## Tech Stack
### Backend
- Framework: FastAPI 0.104+
- Database: PostgreSQL 17
- Cache: Redis 7.2
### Frontend
- Framework: Flutter 3.24+
- State Management: Provider

This helps Vibe agents select the right tech stack automatically.

Your First SPEC

Let's create a specification for a simple feature: "push notification settings"

Step 1: Create SPEC

vibe spec "push notification settings"

You'll be asked 6 questions:

Q1. Why? (Business value)

Reduce app churn from excessive notifications
Current: 15% weekly churn
Target: <10% weekly churn

Q2. Who? (Users and scale)

All users (100k+ DAU)
95% mobile, 5% web

Q3. What? (Features)

6-category notification toggle system:
- Likes (default: ON)
- Comments (default: ON)
- Follows (default: ON)
- Mentions (default: ON)
- Feed updates (default: OFF)
- Marketing (default: OFF)

Q4. How? (Technical requirements)

Performance: P95 < 500ms
Infrastructure: Redis caching
Security: Rate limiting (100 req/min)

Q5. When? (Timeline)

3 days (24 hours development time)
Priority: HIGH

Q6. With What? (Tech stack)

Backend: FastAPI + PostgreSQL
Frontend: Flutter + Provider
Push: Firebase Cloud Messaging

Result:

✅ Created: .vibe/specs/push-notification-settings.md

Step 2: Review SPEC

cat .vibe/specs/push-notification-settings.md

Expected format:

# SPEC: Push Notification Settings
## Metadata
- Created: 2025年11月17日
- Priority: HIGH
- Language: en
## 1. Why (Business Value)
Reduce app churn from excessive notifications
- Current: 15% weekly churn
- Target: <10% weekly churn
## 2. Who (Users)
- All users (100k+ DAU)
- 95% mobile, 5% web
## 3. What (Features)
### REQ-001: Notification Category Toggles
**WHEN** user opens notification settings
**THEN** system SHALL display 6 category toggles
#### Acceptance Criteria
- [ ] Display 6 categories with ON/OFF toggles
- [ ] Show default state for each category
- [ ] Persist changes to database
### REQ-002: Default Settings
**WHEN** new user registers
**THEN** system SHALL apply default notification settings
#### Acceptance Criteria
- [ ] Likes: ON
- [ ] Comments: ON
- [ ] Follows: ON
- [ ] Mentions: ON
- [ ] Feed updates: OFF
- [ ] Marketing: OFF
...

Generate Technical Plan

Step 3: Generate plan

vibe plan "push notification settings"

Result:

✅ Created: .vibe/plans/push-notification-settings.md
Summary:
- 3 Phases: Backend → Frontend → FCM Integration
- Timeline: 24 hours (3 days)
- Cost: +0ドル.50/month (Redis + FCM)
- Stack Reuse: 100% existing infrastructure

Step 4: Review plan

cat .vibe/plans/push-notification-settings.md

Expected sections:

  • Architecture Overview: System design and components
  • Database Schema: Table structures and migrations
  • API Design: Endpoints and request/response formats
  • Frontend Components: UI structure and state management
  • Cost Analysis: Infrastructure and operational costs
  • Timeline: Phase-based breakdown with estimates
  • Risk Assessment: Potential blockers and mitigation

Decompose into Tasks

Step 5: Generate tasks

vibe tasks "push notification settings"

Result:

✅ Created: .vibe/tasks/push-notification-settings.md
Task Breakdown:
- Total: 19 tasks
- Phase 1 (Backend): 8 tasks
- Phase 2 (Frontend): 8 tasks
- Phase 3 (FCM): 3 tasks
- Dependency graph included

Step 6: Review tasks

cat .vibe/tasks/push-notification-settings.md

Expected format:

# TASKS: Push Notification Settings
## Phase 1: Backend Development (8 hours)
### Task 1-1: Database Migration ⬜
**Description**: Create user_notification_settings table
**Implementation**:
1. Create Alembic migration file
2. Add 6 boolean columns for categories
3. Set default values
4. Add foreign key to users table
**Acceptance Criteria**:
- [ ] Migration file created
- [ ] All 6 columns present
- [ ] Defaults match SPEC
- [ ] Foreign key constraint added
**Dependencies**: None
**Estimated Time**: 1 hour
---
### Task 1-2: Settings Repository ⬜
**Description**: Create data access layer
**Implementation**:
1. Create NotificationSettingsRepository class
2. Implement get_settings(user_id)
3. Implement update_settings(user_id, settings)
4. Add database session handling
**Acceptance Criteria**:
- [ ] Repository class with type hints
- [ ] CRUD methods implemented
- [ ] Unit tests passing
**Dependencies**: Task 1-1
**Estimated Time**: 1.5 hours
...

Execute Tasks

Step 7: Run first task

vibe run "Task 1-1"

What happens:

  1. Task Guide Generated: Creates .vibe/guides/task-1-1.md with detailed implementation steps
  2. AI Agent Selected: Chooses appropriate agent (e.g., Backend Python Expert)
  3. Implementation: Executes task with step-by-step guidance
  4. Verification: Checks acceptance criteria
  5. Status Update: Marks task as ⬜ → ✅

Result:

✅ Task 1-1 completed
Files changed:
- backend/alembic/versions/xxx_add_notification_settings.py (created)
Next task: Task 1-2 (Settings Repository)
Run: vibe run "Task 1-2"

Step 8: Run entire phase

vibe run --phase 1

This executes all tasks in Phase 1 sequentially, respecting dependencies.

Verify Implementation

Step 9: Verify against SPEC

vibe verify "push notification settings"

Result:

📊 Verification Report
✅ REQ-001: Notification Category Toggles (3/3 criteria)
✅ REQ-002: Default Settings (6/6 criteria)
✅ REQ-003: Update API (4/4 criteria)
⚠️ REQ-004: Performance Target (2/3 criteria)
 ❌ P95 latency: 620ms (target: <500ms)
Overall: 85% complete (15/17 criteria)
Recommendations:
1. Add Redis caching to reduce latency
2. Optimize database query in get_settings()
Report saved: .vibe/reports/verification-2025年11月17日.md

Advanced Features

Code Analysis

Analyze code quality before committing:

vibe analyze --code

Output:

📊 Code Quality Report
Overall Score: 85/100 (B+)
Findings:
- High complexity: src/service.py (CC: 15)
- Low cohesion: src/utils.py (0.3)
Recommendations:
1. Refactor src/service.py into 3 modules
2. Extract unrelated utilities from src/utils.py

UI Mockup

Preview UI before implementation:

vibe ui "notification settings screen with 6 toggles"

Output:

┌─────────────────────────────────────────┐
│ Notification Settings │
├─────────────────────────────────────────┤
│ │
│ Likes [●くろまる────] ON │
│ Comments [●くろまる────] ON │
│ Follows [●くろまる────] ON │
│ Mentions [●くろまる────] ON │
│ Feed updates [────○しろまる] OFF │
│ Marketing [────○しろまる] OFF │
│ │
│ ┌─────────────────────┐ │
│ │ Save Changes │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────┘

Architecture Diagram

Generate Mermaid diagrams:

vibe diagram --er

Output:

erDiagram
 users ||--o{ user_notification_settings : has
 users {
 uuid id PK
 string email
 datetime created_at
 }
 user_notification_settings {
 uuid id PK
 uuid user_id FK
 boolean likes
 boolean comments
 boolean follows
 boolean mentions
 boolean feed_updates
 boolean marketing
 }
Loading

Slash Commands in Claude Code

Use these commands directly in Claude Code chat:

/vibe.spec "push notification settings"
/vibe.plan "push notification settings"
/vibe.tasks "push notification settings"
/vibe.run "Task 1-1"
/vibe.verify "push notification settings"

Advantages:

  • No terminal switching
  • Inline results in chat
  • Access to 38 MCP tools
  • Memory preservation across sessions

Configuration

.vibe/config.json

{
 "language": "ko",
 "agents": {
 "default": "backend-python-expert"
 },
 "mcp": {
 "enabled": true,
 "servers": ["vibe"]
 },
 "quality": {
 "max_complexity": 10,
 "max_nesting": 3,
 "max_function_length": 20
 }
}

Next Steps

Now that you've completed your first workflow:

  1. Core Concepts - Understand SPEC-driven methodology
  2. Command Reference - Learn all CLI commands
  3. MCP Integration - Explore 38 development tools
  4. Agents Guide - Master 7 specialized agents
  5. Best Practices - Production-grade workflows

Troubleshooting

MCP server not connected

MCP servers are registered per-project in Vibe. If you see "No MCP servers configured":

# Make sure you're in your project directory
cd /path/to/your/project
# Re-run vibe init (safe to run multiple times)
vibe init
# Verify (must be in project directory)
claude mcp list

Important: You must run claude mcp list from within your project directory where you ran vibe init.

Command not found: vibe

# Check global npm bin path
npm config get prefix
# Should be in PATH (usually /usr/local or ~/.nvm/versions/node/vXX/bin)
echo $PATH
# Reinstall if needed
npm install -g @su-record/vibe

Slash commands not working

Ensure Claude Code is running and MCP server is connected:

claude mcp list
# Should show: vibe - ✓ Connected

Ready to build with Vibe? Let's go! 🚀

← Back to Home | Next: Core Concepts →

Clone this wiki locally

AltStyle によって変換されたページ (->オリジナル) /