Content
# VibeCoding System 🚀
[](https://github.com/vibecoding/vibecoding-template) [](https://www.npmjs.com/package/vibecoding-system) [](https://opensource.org/licenses/MIT)
> **Conversation-Driven Development Framework for Rapid MVP/POC Creation**
## Tool List
### 🎯 **Setup Guide** (Read in order)
1. **[Complete IDE Setup Guide](IDE_SETUP_GUIDE.md)** - Primary setup document, supports all MCP Host
2. **[Cursor MCP Specific Instructions](CURSOR_MCP_CLARIFICATION.md)** - Must-read for Cursor users
3. **[MCP Setup Guide](MCP_SETUP_GUIDE.md)** - In-depth configuration and troubleshooting
4. **[Deployment Guide](DEPLOY_MCP_GUIDE.md)** - Production environment deployment
### 🛠️ **Tools and Command Reference**
- **[Complete Tool Reference Manual](VIBECODING_TOOLS_REFERENCE.md)** - Detailed description of all 34+ tools
- **[Concise Command System Design](VIBECODING_COMMAND_REDESIGN.md)** - UX-driven command redesign
- **[MCP Configuration Examples](mcp-config-examples.json)** - Configuration examples for various scenarios
### 🏗️ **Architecture and Advanced**
- **[Project Structure Description](folder_structure.md)** - Project architecture and file organization
- **[API Reference](#-api-reference)** - Complete API documentation
- **[Architecture](#-architecture)** - System architecture details
## 🚀 Complete Initialization Process
### 📦 Step 1: System Installation and Setup
```bash
# 1. Clone VibeCoding template
git clone https://github.com/Zenobia000/vibeCoding-mcp.git
cd vibeCoding-template
# 2. Install dependencies and build the system
npm install && npm run build
# 3. Verify system status
npm run vibecoding status
# Expected output: ✅ All VibeCoding services are enabled
# 4. Test prompt system
npm run test:prompts
# Expected output: 🎉 FULLY OPERATIONAL - All prompts are ready!
```
### 🏗️ Step 2: Create Your Project Folder
#### **🚀 Method 1: One-click Enhanced Project Creation (Recommended)**
```bash
# Create a new project directory
mkdir my-awesome-project
cd my-awesome-project
# 🚀 One-click create VibeCoding enhanced project structure (with professional template)
# 🌟 Recommended to use v3 version (complete integration of v1+v2 advantages)
node /path/to/your/vibeCoding-template/scripts/create-enhanced-project-v3.cjs
# Other version options:
# v2 version (architecture optimization, following .vibecoding/prompts guidelines)
node /path/to/your/vibeCoding-template/scripts/create-enhanced-project-v2.cjs
# v1 version (complete content)
node /path/to/your/vibeCoding-template/scripts/create-enhanced-project.cjs
# 🎉 Completed! Automatically created:
# ✅ 5 development phase directories + complete sub-directory structure
# ✅ Professional templates based on design_templates
# ✅ Development guide, test strategy, deployment guide
# ✅ Project briefing, architecture document, ADR template
# ✅ README.md and .gitignore files
```
#### **📝 Method 2: Manually Create Basic Structure**
```bash
# Create a new project directory (in any location)
mkdir my-awesome-project
cd my-awesome-project
# Initialize project structure (optional, VibeCoding will automatically create)
mkdir -p {src,tests,docs,config}
# Initialize git (recommended)
git init
echo "node_modules/" > .gitignore
echo "dist/" >> .gitignore
echo ".env" >> .gitignore
# Create basic package.json (optional, VibeCoding can assist in generating)
npm init -y
```
### ⚙️ Step 3: Configure IDE and MCP Connection
#### **Cursor IDE** (Recommended - No API key required)
1. Open Cursor IDE settings file:
```bash
# Windows
code "$env:APPDATA\Cursor\User\settings.json"
# macOS
code "~/Library/Application Support/Cursor/User/settings.json"
# Linux
code ~/.config/Cursor/User/settings.json
```
2. Add VibeCoding MCP settings:
```json
{
"mcpServers": {
"vibecoding-context-manager": {
"command": "node",
"args": ["/path/to/your/vibeCoding-template/dist/vibe-services/context-manager/index.js"],
"description": "VibeCoding context management service"
}
},
"vibecoding.enabled": true,
"vibecoding.defaultProvider": "cursor"
}
```
3. **Important**: Replace `/path/to/your/vibeCoding-template/` with your actual path
#### **Claude Desktop**
```json
{
"mcpServers": {
"vibecoding-context-manager": {
"command": "node",
"args": ["/path/to/your/vibeCoding-template/dist/vibe-services/context-manager/index.js"],
"env": {
"ANTHROPIC_API_KEY": "Your_ANTHROPIC_key"
}
}
}
}
```
#### **Other IDEs**
> 📖 **Complete Setup Guide**: [Complete IDE Setup Guide](IDE_SETUP_GUIDE.md) - Supports VSCode, WebStorm, etc.
> 📖 **Detailed Instructions**: [Cursor MCP Specific Instructions](CURSOR_MCP_CLARIFICATION.md)
### 🎯 Step 4: Start Your First VibeCoding Project
```bash
# In your project folder, use Cursor or Claude Desktop
# Enter the following command to start:
# 🆕 Concise command (recommended)
@vibe start "My Project"
# 📝 Complete command (backward compatible)
@vibecoding-context-manager start-clarification
```
### ✅ Step 5: Verify Successful Setup
Test the following commands in your IDE:
```bash
# Test basic connection
@vibe start "Test Project"
# If you see a response similar to the following, the setup is successful:
# 🚀 Project clarification started
# Project ID: proj_xxxxx
# Question: Please describe the main goals and problems to be solved by this project?
```
## 🌟 Core Highlights
### ⚡ **Revolutionary Command System**
- **🆕 Concise Command**: `@vibe start "Project Name"` - Average reduction of 77% input
- **🔄 Backward Compatible**: Complete command still available
- **🧠 Intelligent Conversation**: Natural language-driven development process
### 🤖 **6 Professional MCP Services**
| Service | Function | Concise Command |
|------|------|----------|
| 📋 Context Manager | Project clarification and context management | `@vibe start`, `@vibe prd` |
| ⚡ Code Generator | AI-driven code generation | `@vibe code`, `@vibe api` |
| 📦 Dependency Tracker | Intelligent dependency analysis | `@vibe deps`, `@vibe scan` |
| 🧪 Test Validator | Automated test generation | `@vibe test`, `@vibe cover` |
| 📚 Doc Generator | Intelligent document creation | `@vibe doc`, `@vibe readme` |
| 🚀 Deployment Manager | CI/CD and infrastructure automation | `@vibe deploy`, `@vibe monitor` |
### 💡 **Technical Advantages**
- **Multi-AI Provider Support**: OpenAI, Anthropic, Gemini, local models
- **Phase-Aware Workflow**: Dynamic AI guidance adapts to development phases
- **Template System**: Rich template library with AI enhancement
- **Hot Configuration**: Runtime switching provider without restart
### 🎮 Complete Development Workflow
#### 🏗️ Start in Your Project Folder
```bash
# Enter your project directory
cd my-awesome-project
# Open Cursor IDE or other configured MCP Host
code . # or cursor .
```
#### 📋 Phase 1: Project Clarification and Requirements Collection
```bash
# 🎯 1. Start new project clarification
@vibe start "Task Management System"
# System provides 7 structured questions to collect requirements
# 🗨️ 2. Answer clarification questions one by one
@vibe ask "Mainly solves team collaboration and task tracking issues"
# System guides you through all 7 clarification questions
# 📋 3. Generate Product Requirements Document (PRD)
@vibe prd
# Automatically create comprehensive PRD and save to project
```
#### 🏗️ Phase 2: Design and Architecture
```bash
# 📐 4. Generate implementation plan
@vibe plan
# Generate detailed technical implementation plan based on PRD
# 🏛️ 5. Design system architecture
@vibe arch "Microservice architecture, using Node.js + Express + MongoDB"
# Generate architecture diagram and technical selection description
```
#### 💻 Phase 3: Development Implementation
```bash
# 🚀 6. Start code development
@vibe code "User authentication system, including registration, login, JWT verification"
@vibe api "Task CRUD interface, supporting creation, reading, updating, deletion"
# 🔄 7. Code review and refactoring
@vibe review "[Just generated code]"
@vibe refactor "Improve performance and readability"
```
#### 🧪 Phase 4: Testing and Validation
```bash
# 🧪 8. Generate test code
@vibe test
@vibe mock "[API code]"
# 📊 9. Check test coverage
@vibe cover
# Verify code quality and test coverage
```
#### 🚀 Phase 5: Deployment and Monitoring
```bash
# 📚 10. Generate documentation
@vibe doc
@vibe readme
# 🚀 11. Deploy application
@vibe deploy
# Automatically set up CI/CD process and deploy to cloud platform
```
#### 🎯 Rapid Prototype Mode (30-minute MVP)
```bash
# One-click rapid development process
@vibe start "Rapid Prototype" # 2-minute clarification
@vibe prd # 1-minute PRD generation
@vibe code "Core functionality" # 10-minute development
@vibe test # 5-minute testing
@vibe deploy # 12-minute deployment
# 🎉 30 minutes to complete MVP!
```
## 🏗️ System Architecture
### Core Service Architecture
```
VibeCoding MCP Server
├── 📋 Context Manager → Persistent conversation and project state
├── ⚡ Code Generator → AI-driven code generation
├── 📦 Dependency Tracker → Intelligent dependency management
├── 🧪 Test Validator → Automated testing and quality analysis
├── 📚 Doc Generator → Intelligent document creation
└── 🚀 Deployment Manager → CI/CD and infrastructure automation
```
### AI Prompt System
Located in `.vibecoding/prompts/`, provides intelligent guidance:
- **Core Prompts** (3): System identity, conversation style, collaboration rules
- **Service Prompts** (6): Professional prompts for each MCP service
- **Workflow Prompts** (5): Phase-specific development guidance
- **Dynamic Loading**: Adapt to current project phase and context
### Development Phases
```
0_discovery/ → Requirements collection and clarification
1_design/ → Architecture and API design
2_implementation/→ Source code and testing
3_validation/ → Test reports and quality metrics
4_deployment/ → Deployment configuration
knowledge-base/ → Patterns, solutions, and retrospectives
```
## 🔧 API Reference
### Context Manager Core API
```typescript
// Start project clarification
start-clarification(projectName: string, initialDescription?: string)
// Provide clarification answers
provide-clarification(questionIndex: number, answer: string)
// Generate PRD
generate-prd()
// Generate implementation plan
generate-impl-plan()
```
### Other Service APIs
- **Code Generator**: `generate-code`, `code-review`, `refactor-code`
- **Dependency Tracker**: `analyze-dependencies`, `security-scan`, `update-dependencies`
- **Test Validator**: `run-tests`, `validate-coverage`, `performance-test`
- **Doc Generator**: `generate-docs`, `create-api-docs`, `generate-changelog`
- **Deployment Manager**: `deploy-service`, `setup-monitoring`, `rollback-deployment`
> 📖 **Complete API Documentation**: [Tool Reference Manual](VIBECODING_TOOLS_REFERENCE.md)
## ⚙️ Configuration and Customization
### System Requirements
- **Node.js**: >= 18.0.0
- **npm**: >= 8.0.0
- **Operating System**: Windows 10/11, macOS, Linux
- **Memory**: >= 4GB RAM
### AI Provider Configuration
```bash
# Environment variable settings
OPENAI_API_KEY=your_openai_key
ANTHROPIC_API_KEY=your_anthropic_key
GEMINI_API_KEY=your_gemini_key
```
### Advanced Configuration
- **Multi-environment configuration**: Separate development, testing, and production environments
- **Team collaboration settings**: Shared configuration and best practices
- **Enterprise-level deployment**: Security and scalability considerations
> 📖 **Complete Configuration Guide**: [MCP Setup Guide](MCP_SETUP_GUIDE.md)
## 🔍 Troubleshooting
### Quick Fixes for Common Issues
#### ❌ Initialization-related Issues
```bash
# Q1: VibeCoding system initialization failed
npm cache clean --force && npm install && npm run build
# Q2: npm run vibecoding status command cannot be executed
# Ensure you are in the vibeCoding-template directory
cd /path/to/your/vibeCoding-template
npm run vibecoding status
# Q3: MCP service cannot start
npm run build && npm run test:prompts
# Q4: Cannot find dist/ directory
# Rebuild the system
npm run build
ls -la dist/vibe-services/ # Confirm service files exist
```
#### ❌ Project Setup-related Issues
```bash
# Q5: Cannot use @vibe command in project folder
# Ensure IDE is correctly configured with MCP settings and restart IDE
# Q6: Path configuration issue - cannot find VibeCoding service
# Use absolute path, confirm dist/ directory exists
# Windows example: "C:\\Users\\YourName\\vibeCoding-template\\dist\\vibe-services\\context-manager\\index.js"
# macOS/Linux example: "/Users/YourName/vibeCoding-template/dist/vibe-services/context-manager/index.js"
# Q7: Project folder structure issue
# VibeCoding will automatically create necessary folders, but you can also create manually:
mkdir -p {0_discovery,1_design,2_implementation,3_validation,4_deployment}
```
#### ❌ IDE Configuration-related Issues
```bash
# Q8: Cursor IDE cannot recognize @vibe command
# 1. Check settings.json format is correct (no comments)
# 2. Restart Cursor IDE
# 3. Confirm mcpServers configuration is correct
# Q9: Claude Desktop connection failed
# 1. Check claude_desktop_config.json format
# 2. Confirm API key settings are correct
# 3. Restart Claude Desktop
# Q10: Permission issues (Windows)
```
# Run PowerShell as administrator and set execution policy:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
```
### Get Help
- 📖 **Comprehensive Troubleshooting**: [IDE Setup Guide](IDE_SETUP_GUIDE.md#troubleshooting)
- 💬 **Community Support**: [GitHub Issues](https://github.com/vibecoding/vibecoding-template/issues)
- 🐛 **Error Reporting**: [GitHub Issues](https://github.com/vibecoding/vibecoding-template/issues/new)
## 🤝 Contributing
We welcome contributions! Please check out the [Contributing Guide](CONTRIBUTING.md) for details.
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file.
## ✅ Setup Completion Checklist
Before starting to use VibeCoding, please confirm the following:
### 🔧 System Setup Check
- [ ] **Node.js >= 18.0.0** (`node --version`)
- [ ] **VibeCoding Downloaded and Built** (`npm run build` successful)
- [ ] **System Status Normal** (`npm run vibecoding status` shows ✅)
- [ ] **Prompt System Operation** (`npm run test:prompts` shows 🎉)
### 📁 Project Setup Check
- [ ] **Project Folder Created** (`mkdir my-project && cd my-project`)
- [ ] **Git Initialized** (`git init` and `.gitignore` configuration)
- [ ] **IDE Opened Project** (`code .` or `cursor .`)
### ⚙️ IDE Configuration Check
- [ ] **MCP Configuration File Modified** (settings.json or claude_desktop_config.json)
- [ ] **VibeCoding Path Correct** (using absolute path)
- [ ] **IDE Restarted** (configuration takes effect after restart)
- [ ] **Test Command Successful** (`@vibe start "test"` has response)
### 🎯 Ready to Start Development
- [ ] **Choose Development Mode**:
- 📋 **Full Process**: Start from requirement clarification (`@vibe start "project name"`)
- ⚡ **Quick Prototype**: 30-minute MVP mode
- 💻 **Direct Development**: Skip clarification and generate code directly
---
**🚀 Enjoy your AI-driven conversational development experience now!**
### 📚 Recommended Learning Path
1. **Newbie**: [Complete IDE Setup Guide](IDE_SETUP_GUIDE.md) → Complete a simple project
2. **Advanced**: [Complete Tool Reference Manual](VIBECODING_TOOLS_REFERENCE.md) → Explore all features
3. **Expert**: [Architecture Design Document](#-architecture) → Customize and extend
> **💡 Tip**: Encounter problems? Check the above [🔍 Troubleshooting](#-troubleshooting) or refer to [GitHub Issues](https://github.com/vibecoding/vibecoding-template/issues)
