Project Conversion Playbook

Project Conversion Playbook

Transform your existing projects into AI-ready codebases that maximize the effectiveness of Cursor IDE and Claude Code.

Progressive Enhancement

You don’t need to convert everything at once. Start with documentation and rules, then progressively enhance your project structure as you work with AI tools.

The AI-Ready Project Structure

An AI-optimized project isn’t just about the code—it’s about providing context, rules, and structure that AI can understand and leverage effectively.

Key Components of an AI-Ready Project

Component	Purpose	Priority
CLAUDE.md	Project context for Claude Code	Essential
.cursor/rules/	Coding standards for Cursor	Essential
docs/PRD.md	Product requirements	High
docs/ARCHITECTURE.md	System design decisions	High
docs/API.md	Interface documentation	Medium
tests/	Comprehensive test suite	High
.ai-templates/	Prompt templates	Medium
.github/ai-review.yml	AI review configuration	Low

Conversion Process by Project Type

Web Application

Converting a React/Next.js Project

1. Create CLAUDE.md in project root

# Project Overview
This is a Next.js e-commerce application using:
- Next.js 14 with App Router
- TypeScript for type safety
- Tailwind CSS for styling
- Prisma ORM with PostgreSQL
- Stripe for payments
- NextAuth for authentication

## Key Conventions
- Use server components by default
- Client components only when necessary
- All API routes in app/api/
- Shared components in components/ui/
- Business logic in lib/

## Development Workflow
- Run `npm run dev` for development
- Tests with `npm test`
- Database migrations: `npx prisma migrate dev`

## Current Focus
Working on checkout flow optimization

2. Set up .cursor/rules/

   mkdir -p .cursor/rules

   Create .cursor/rules/react.md:

   # React Development Rules
   
   - Prefer functional components with hooks
   - Use TypeScript interfaces over types
   - Extract custom hooks for reusable logic
   - Keep components under 150 lines
   - Colocate tests with components

3. Document existing architecture

   docs/ARCHITECTURE.md

   ## Frontend Architecture
   - Pages use Next.js App Router
   - Global state with Zustand
   - API calls via custom hooks
   - Optimistic UI updates
   
   ## Backend Architecture
   - RESTful API design
   - Middleware for auth/logging
   - Service layer pattern
   - Repository pattern for data

4. Create AI-friendly test structure

   __tests__/checkout.test.tsx

   describe('Checkout Flow', () => {
     it('should calculate tax correctly', () => {
       // AI can understand and extend these
     });
   });

Backend API

Converting a Node.js/Express API

1. Create comprehensive CLAUDE.md

# API Service Overview

RESTful API built with:
- Express.js framework
- PostgreSQL database
- JWT authentication
- Redis for caching

## API Structure
/api/v1/
  /auth    - Authentication endpoints
  /users   - User management
  /orders  - Order processing
  /products - Product catalog

## Key Patterns
- Middleware for auth/validation
- Error handling with custom classes
- Response formatting helpers
- Database transactions for consistency

2. Document API endpoints

   docs/API.md

   ## Authentication
   POST /api/v1/auth/login
   POST /api/v1/auth/logout
   POST /api/v1/auth/refresh
   
   ## Users
   GET    /api/v1/users
   POST   /api/v1/users
   GET    /api/v1/users/:id
   PUT    /api/v1/users/:id
   DELETE /api/v1/users/:id

3. Add coding standards

   .cursor/rules/api.md

   ## API Development Rules
   - Always validate input with Joi
   - Use try-catch with async/await
   - Return consistent error format
   - Log all errors with context
   - Use database transactions

Mobile App

Converting a React Native Project

1. Mobile-specific CLAUDE.md

# Mobile App Overview

React Native app supporting:
- iOS 14+ and Android 10+
- TypeScript throughout
- React Navigation v6
- Redux Toolkit for state
- React Query for API

## Project Structure
/src
  /screens   - Screen components
  /components - Shared components
  /navigation - Navigation config
  /store     - Redux store
  /api       - API client
  /utils     - Helpers

2. Platform-specific rules

   .cursor/rules/mobile.md

   - Always test on both platforms
   - Use Platform.select for OS differences
   - Prefer styled-components
   - Optimize images and assets
   - Handle offline scenarios

Essential Documentation Templates

1. CLAUDE.md Template

Comprehensive CLAUDE.md Structure

# [Project Name]

## Overview
Brief description of what the project does and its main purpose.

## Technology Stack
- Language: [e.g., TypeScript 5.0]
- Framework: [e.g., Next.js 14]
- Database: [e.g., PostgreSQL 15]
- Key Libraries: [List main dependencies]

## Project Structure

/src /components - React components /pages - Next.js pages /api - API routes /lib - Utility functions /styles - CSS/Sass files

## Development Setup
1. Install dependencies: `npm install`
2. Set up environment: `cp .env.example .env.local`
3. Run database: `docker-compose up -d`
4. Run dev server: `npm run dev`

## Coding Conventions
- TypeScript strict mode enabled
- ESLint + Prettier for formatting
- Conventional commits
- 100% test coverage goal

## Current Tasks
- [ ] Implementing user dashboard
- [ ] Optimizing database queries
- [ ] Adding real-time notifications

## Known Issues
- Performance bottleneck in search
- Memory leak in WebSocket handler

## Architecture Decisions
- Using Server Components for SEO
- Chose PostgreSQL for JSONB support
- Implemented event-driven architecture

2. Cursor Rules Template

.cursor/rules/ Structure

.cursor/rules/
├── general.md      # Overall coding standards
├── typescript.md   # TypeScript-specific rules
├── react.md        # React patterns
├── testing.md      # Test requirements
├── security.md     # Security guidelines
└── performance.md  # Performance rules

Example general.md:

# General Coding Standards

## Code Quality
- Keep functions under 50 lines
- Maximum 3 parameters per function
- Descriptive variable names
- Comments for complex logic only

## Error Handling
- Never ignore errors silently
- Log errors with context
- User-friendly error messages
- Graceful degradation

## Git Workflow
- Feature branches from develop
- Squash commits before merge
- Conventional commit messages
- PR requires 2 approvals

3. PRD Template

Product Requirements Document

# Feature: [Feature Name]

## Overview
Brief description of the feature and its value proposition.

## User Stories
- As a [user type], I want to [action] so that [benefit]
- As a [user type], I want to [action] so that [benefit]

## Acceptance Criteria
- [ ] User can perform X
- [ ] System validates Y
- [ ] Error handling for Z

## Technical Requirements
- Must work on mobile devices
- Response time < 200ms
- Support 1000 concurrent users
- Accessible (WCAG 2.1 AA)

## Non-Functional Requirements
- Security: OAuth 2.0 authentication
- Performance: CDN for static assets
- Monitoring: Track usage metrics

## Dependencies
- Payment gateway integration
- Email service for notifications
- Analytics tracking setup

## Success Metrics
- 80% feature adoption rate
- < 2% error rate
- 50% reduction in support tickets

Legacy Code Conversion

Analyzing Existing Codebase

1. Generate initial documentation

   # Use AI to analyze and document
   "Analyze this codebase and create:
   - Overview of architecture
   - List of main components
   - Technology stack details
   - Key patterns used
   - Areas needing refactoring"

2. Identify anti-patterns

   "Review code for:
   - Code smells
   - Security vulnerabilities
   - Performance bottlenecks
   - Outdated dependencies
   - Missing tests"

3. Create migration plan

   # Migration Plan
   
   ## Phase 1: Documentation (Week 1)
   - Create CLAUDE.md
   - Document API endpoints
   - Map dependencies
   
   ## Phase 2: Testing (Week 2)
   - Add missing unit tests
   - Create integration tests
   - Set up CI/CD
   
   ## Phase 3: Refactoring (Week 3-4)
   - Update dependencies
   - Fix critical issues
   - Improve code structure

Modernization Strategy

Incremental Approach

• Start with documentation
• Add tests for existing code
• Refactor module by module
• Maintain backward compatibility

Big Bang Approach

• Complete rewrite planning
• Parallel development
• Feature parity checklist
• Staged rollout strategy

AI Integration Points

1. Automated Documentation

Documentation Generation Workflow

.github/workflows/docs.yml

name: Update Documentation

on:
  push:
    branches: [main]

jobs:
  update-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Generate API Docs
        run: |
          # AI generates from code
          npx ai-doc-gen --source ./src --output ./docs/api

      - name: Update CLAUDE.md
        run: |
          # AI updates project context
          npx update-claude-md

      - name: Commit changes
        run: |
          git add docs/
          git commit -m "docs: auto-update documentation"
          git push

2. Code Quality Enforcement

AI-Powered Code Review

.github/ai-review.yml

review:
  models:
    - claude-3-sonnet
    - gpt-4

  checks:
    - security_vulnerabilities
    - performance_issues
    - code_duplication
    - test_coverage
    - documentation_gaps

  rules:
    - enforce_typescript
    - require_tests
    - max_complexity: 10
    - min_coverage: 80

3. Test Generation

AI Test Generation Strategy

ai-test-template.ts

describe('[Component/Function]', () => {
  // AI generates comprehensive tests

  describe('Happy Path', () => {
    it('should handle normal input', () => {
      // Test implementation
    });
  });

  describe('Edge Cases', () => {
    it('should handle empty input', () => {
      // Test implementation
    });

    it('should handle null values', () => {
      // Test implementation
    });
  });

  describe('Error Scenarios', () => {
    it('should throw on invalid input', () => {
      // Test implementation
    });
  });
});

Measuring Conversion Success

Success Metrics

Metric	Before	After	Target
AI Understanding	0%	80%	90%
Documentation Coverage	20%	90%	95%
Test Coverage	40%	85%	90%
Refactoring Speed	1 file/hour	10 files/hour	15 files/hour
Bug Detection	Manual	AI-assisted	Automated
Code Review Time	2 hours	30 minutes	15 minutes

Common Pitfalls to Avoid

Over-Documentation

Don’t document obvious things. Focus on:

• Architecture decisions
• Business logic reasoning
• Complex algorithms
• External integrations

Rigid Rules

Rules should guide, not constrain:

• Allow exceptions with justification
• Update rules based on learnings
• Keep rules concise and clear

Ignoring Context

Always provide business context:

• Why features exist
• User journey understanding
• Performance requirements
• Security considerations

Conversion Checklist

Complete Conversion Checklist

• Documentation

  • CLAUDE.md created and comprehensive
  • Architecture documented
  • API documentation complete
  • PRD for main features

• AI Configuration

  • .cursor/rules/ directory set up
  • Coding standards documented
  • Test patterns defined
  • Security rules specified

• Code Quality

  • Linting configured
  • Tests achieving >80% coverage
  • CI/CD pipeline active
  • Code review process defined

• Project Structure

  • Clear folder organization
  • Consistent naming conventions
  • Modular architecture
  • Dependencies documented

• Team Readiness

  • Team trained on AI tools
  • Workflows documented
  • Success metrics defined
  • Feedback loop established

Continuous Improvement

Project conversion is not a one-time activity. Continuously update documentation, refine rules, and optimize structure as you learn what works best with AI tools.

Next Steps

1. Start with documentation - Create CLAUDE.md today
2. Add one rule file - Begin with general coding standards
3. Convert one module - Pick a well-understood component
4. Measure improvement - Track time saved and quality gains
5. Iterate and expand - Apply learnings to rest of project

The goal isn’t perfection—it’s creating a foundation that makes AI assistance more effective and your development more efficient.