Quick Start Tutorial

Get up and running with VDK CLI in under 5 minutes. This tutorial will walk you through initializing VDK in a project and setting up your first AI assistant integration.

Step 1: Navigate to Your Project

cd your-project-directory

VDK works with any project structure - whether it's a React app, Node.js API, Python Django project, or any other codebase.

Step 2: Initialize VDK

vdk init

This command will:

• Scan your project structure
• Detect technologies and frameworks
• Identify architectural patterns
• Generate project-aware AI rules
• Create a vdk.config.json file

Example Output

🔍 Scanning project at: /Users/dev/my-react-app
📁 Detected project structure...
🔧 Technology Analysis:
   - Framework: React (18.2.0)
   - Language: TypeScript
   - Build Tool: Vite
   - Styling: Tailwind CSS
   - Testing: Vitest
   - State: Zustand

🎯 Pattern Detection:
   - Architecture: Component-based
   - Patterns: Hooks, Custom Hooks, Context API
   - Structure: Feature-based organization

📝 Generated 12 AI rules in .ai/rules/
✅ VDK configuration created at vdk.config.json

Step 3: Check What Was Generated

# View the generated configuration
cat vdk.config.json

# List generated rules
ls -la .ai/rules/

Your project now contains:

• vdk.config.json - VDK configuration
• .ai/rules/ - Generated AI assistant rules
• Rule files tailored to your project's technology stack

Step 4: Set Up IDE Integration

Option A: Automatic Detection

# Scan for available IDEs
vdk integrations --scan

VDK will detect which AI-powered IDEs you have installed:

🔍 Scanning for IDE integrations...

✅ Detected IDE Integrations:
   • Claude Code (high confidence)
   • Cursor AI (medium confidence)

💤 Available IDEs (not detected):
   • Windsurf
   • GitHub Copilot

Option B: Manual Setup

Choose your preferred IDE and set it up:

Claude Code

vdk integrations --setup claude-code

Cursor

vdk integrations --setup cursor

Windsurf

vdk integrations --setup windsurf

GitHub Copilot

vdk integrations --setup github-copilot

Integration Success

After successful setup, you'll see:

🔧 Setting up Claude Code integration...

✅ Claude Code integration configured successfully!

Configuration files created:
   • projectMemory: CLAUDE.md
   • projectSettings: .claude/settings.json
   • projectCommands: .claude/commands/

💡 Claude Code next steps:
   - Run `claude` in this directory to start
   - Use `/vdk-analyze` to analyze your project
   - Use `/vdk-refresh` to update rules

Step 5: Start Using Your AI Assistant

With Claude Code

# Start Claude Code in your project
claude

Claude will now understand your project context. Try asking:

• "Help me create a new React component following this project's patterns"
• "Refactor this code to match our TypeScript conventions"
• "Add a new API endpoint following our existing structure"

With Cursor

Open your project in Cursor. The generated rules in .cursor/rules/ will automatically enhance Cursor's understanding of your project.

With Windsurf

Open your project in Windsurf. The rules in .windsurf/rules/ provide project context to the AI assistant.

Step 6: Verify Everything Works

# Check VDK status
vdk status

You should see:

Checking VDK status...

✅ VDK Configuration: Found and valid.
   - Project: my-react-app
   - IDE: Claude Code

✅ Local Rules: Found 12 rule(s) in .ai/rules
📊 Blueprint Repository Status: 109 blueprints available
   - Local cache: Up to date

What Happens Next?

Automatic Project Understanding

Your AI assistant now understands:

1. Technology Stack: React, TypeScript, Tailwind CSS, etc.
2. Project Structure: Component organization, utility functions, etc.
3. Coding Patterns: Naming conventions, file organization, etc.
4. Dependencies: Available packages and their usage patterns
5. Best Practices: Project-specific conventions and standards

Example: Enhanced AI Responses

Before VDK:

User: "Create a button component"
AI: "Here's a basic button component..."

After VDK:

User: "Create a button component"
AI: "I'll create a button component following your project's patterns:
- Using TypeScript with proper interfaces
- Styled with Tailwind CSS classes
- Following your component structure in src/components/
- Including proper prop validation
- Matching your existing button variants..."

Common Workflows

Adding New Features

When working on new features, your AI assistant will:

• Follow your existing code patterns
• Use the same dependencies and utilities
• Match your naming conventions
• Suggest appropriate file locations
• Implement proper TypeScript types

Code Reviews

Your AI can now:

• Check code against project standards
• Suggest improvements based on existing patterns
• Identify inconsistencies with project conventions
• Recommend better approaches using your tech stack

Refactoring

AI-assisted refactoring becomes more accurate:

• Maintains project-specific patterns
• Uses appropriate abstractions from your codebase
• Preserves existing architectural decisions
• Suggests migrations that fit your project structure

Keeping Rules Updated

As your project evolves, update your VDK rules:

# Re-scan and update rules
vdk init --overwrite

# Check for remote rule updates
vdk update

# Refresh IDE integration memory
vdk claude-code --update-memory

Next Steps

1. Explore Commands: Learn all VDK CLI commands
2. Customize Integration: Configure specific IDE settings
3. Advanced Features: Set up watch mode for continuous updates
4. Team Collaboration: Deploy rules to VDK Hub

Tips for Success

🎯 Be Specific in Prompts

Instead of "create a component", try "create a reusable Card component for our design system"

🔄 Update Regularly

Run vdk init --overwrite when you add new dependencies or change project structure

👥 Share with Team

Use vdk deploy to share your project rules with team members

🔧 Customize Rules

Create custom templates for project-specific patterns

Troubleshooting

If something doesn't work as expected:

# Enable debug mode
VDK_DEBUG=true vdk init

# Check integration status
vdk integrations --scan

# Verify configuration
vdk status

See the troubleshooting guide for common issues and solutions.

Congratulations! 🎉 You've successfully set up VDK CLI and enhanced your AI assistant with project-aware intelligence. Your coding sessions should now be more productive and contextually relevant.