VibeCoding Guide for Existing Projects

This document guides you on how to apply VibeCoding (development with >85% AI assistance) to existing projects. Integrating AI into an existing codebase requires a more systematic and cautious approach compared to new projects.

Challenges of Applying VibeCoding to Legacy Projects

• Lack of Typing: Many legacy codebases use plain JavaScript, PHP without type hints, or Python without type annotations.
• Inconsistent Structure: Different parts of the project might follow different conventions.
• Limited Documentation: Lack of documentation on business rules and system architecture.
• "Magic" Code: Many older frameworks rely on implicit conventions (convention over configuration), making it difficult for AI to understand.
• Fear of Change: Reluctance to modify working code, especially without sufficient tests.

Choosing an IDE with AI Agent Support

Any IDE that supports Agent mode can perform VibeCoding. The crucial part is setting up the context for each IDE: user rules, project rules, documents, etc.

Some recommended IDEs to start with include:

• VSCode + AugmentCode: Use the 14-day trial. Inline Assist and Completion are not yet optimal, but the Agent is very good.
• Cursor: Also a good choice to start with.
• Windsurf: Also a good choice to start with.

Codebase Analysis and Preparation Strategy

1. Understand the Codebase

• Create a Project Map:
  • List all major modules/components
  • Understand data flows and business processes
  • Identify the most complex components
• Assess Code Quality:
  • Check test coverage
  • Evaluate the extent of typing usage
  • Identify hard-to-understand/complex code sections

2. Prepare Documentation for AI

• Create a "Codebase Handbook" for the AI, including:
  • Directory structure and component responsibilities
  • Current naming conventions
  • Key processing flows and important business rules
  • Applied design patterns
• Create a Collection of Snippets from the existing codebase as references

Step-by-Step Integration Strategy

1. Start with Safe Areas

• Tasks that "don't touch old code":
  • Writing documentation, comments, JSDoc/PHPDoc
  • Creating tests for existing modules
  • Generating schema validation for existing APIs
• Isolated New Features:
  • Choose new features with minimal dependencies on old code
  • Apply VibeCoding fully to these features

2. Improve Incrementally

• Strangler Fig Pattern:
  • Wrap old code in a new shell developed using VibeCoding
  • Gradually replace parts of the old code
• Parallel Strategy:
  • Write new code in parallel with the old code
  • Perform A/B testing before fully replacing

3. Add Types Gradually

• TypeScript (JavaScript):
  • Gradually convert .js to .ts with allowJs: true
  • Start with any and incrementally improve types
  • Use JSDoc in JS files for type support
• PHP:
  • Start adding type hints to public methods
  • Use DocBlocks when function signatures cannot be changed
• Python:
  • Add type hints with # type: ignore when necessary
  • Use stub files (.pyi) to supplement types for old code

Language/Framework Specific Guidance

JavaScript/TypeScript (Node.js, Frontend)

• Legacy Express.js:
  • Create type interfaces for Request/Response
  • Separate controllers into distinct files by feature
  • Use middleware for validation instead of direct coding
• Legacy React:
  • Convert class components to function components + hooks
  • Use TypeScript + PropTypes in parallel for gradual conversion
  • Extract logic from components using custom hooks
• Vue 2:
  • Use the Composition API with the @vue/composition-api plugin
  • Add JSDoc/TypeScript for Vuex/components

PHP

• Legacy Laravel:
  • Add type hints to Models/Controllers/Services
  • Create DTOs (Data Transfer Objects) for requests/responses
  • Extract complex logic into services or actions
• Legacy PHP:
  • Create modern facades (with typing) for old functions
  • Encapsulate old logic into well-structured classes

Python

• Legacy Django:
  • Add typing module by module
  • Split large views into smaller ones
  • Move business logic from views into services
• Flask:
  • Refactor using a modular pattern with Blueprints
  • Add Pydantic models for data validation

Prompt Suggestions for AI when working with Legacy Projects

1. Analyze and Map the Codebase

Analyze the following codebase and help me create a "project map" showing:
1. Directory structure and main components
2. Core data flow
3. Design patterns used
4. Strengths and weaknesses of the current architecture

[Paste some key files/directories here]

2. Add Types to Untyped Code

Help me add TypeScript types to the following JavaScript code. Preserve the logic completely, only add:
1. Types for variables, parameters, return values
2. Interfaces/Types for objects
3. JSDoc where necessary to explain complex logic

[Paste the source code to be converted here]

3. Refactor by Feature

Help me refactor the following files from a technical layer organization to a feature module organization.
Currently, they are in separate directories (controllers/, services/, models/), but I want to group them under the "user" feature.

[List the relevant files]

Principles for Applying VibeCoding to Legacy Projects

• Preserve Behavior: Ensure functionality remains the same after refactoring
• Small Steps: Apply VibeCoding in small, manageable parts
• Test First, Refactor Later: Write tests for old code before making changes
• Learn from Legacy Code: Ensure you understand the existing business logic
• Don't Fight the Framework: Work with the conventions of the old framework instead of trying to impose a new structure
• Document Changes: Record all decisions, especially architectural ones

Case Study: Modernizing Laravel 5.x to Laravel 10+ with VibeCoding

Step 1: Analysis and Preparation

• Create a list of Models and their relationships
• Identify large Controllers needing refactoring
• Understand complex business rules
• Check for outdated packages

Step 2: Incremental Enhancement Strategy

• Add type hints to Models
• Create DTOs for Requests/Responses
• Extract Custom Validation Rules
• Move logic from Controllers to Services
• Refactor Blade views piece by piece

Step 3: Using AI for Support

• Automatically analyze model relationships
• Generate OpenAPI descriptions based on existing routes
• Improve test coverage
• Convert Controllers to the Resource/APIResource pattern

---

Remember: Modernization is a marathon, not a sprint. Take small steps, test thoroughly, and maintain consistency between old and new code.