legacy-to-ai-ready

name

legacy-to-ai-ready

description

Transform legacy codebases into AI-ready projects with Claude Code configurations. Use when (1) analyzing old projects to generate AI coding configurations, (2) creating CLAUDE.md, skills, subagents, slash commands, hooks, or rules for existing projects, (3) user wants to enable vibe coding for a codebase, (4) onboarding new team members with AI-assisted development, (5) user mentions "make project AI-ready", "generate Claude config", or "create coding standards for AI".

Legacy to AI-Ready

Transform legacy codebases into AI-ready projects by generating Claude Code configurations.

Quick Start (5-Minute Setup)

For most projects, start with just CLAUDE.md:

1. Analyze: python scripts/analyze_codebase.py [path]
2. Create CLAUDE.md with build commands, code style, architecture overview
3. Done - Claude can now write code following your project's conventions

Expand to full configuration only when needed.

Interactive Discovery

Before generating configs, ask these questions:

Project Scope:

• What is this project? (web app, API, CLI, library)
• Primary language and frameworks?
• Team size? (solo, small team, enterprise)

Pain Points:

• What mistakes do new developers commonly make?
• What patterns should always be followed?
• What operations are repeated frequently?

Integration Needs:

• External services used? (databases, APIs, cloud)
• CI/CD pipeline? (GitHub Actions, Jenkins)
• Code quality tools? (linters, formatters)

Configuration Decision Tree

Start
│
├─ Small project / Solo dev
│  └─ CLAUDE.md only
│
├─ Team project
│  ├─ Multi-language? → Add .claude/rules/
│  ├─ Complex domain? → Add .claude/skills/
│  ├─ Code reviews? → Add .claude/agents/
│  └─ Repeated tasks? → Add .claude/commands/
│
└─ Enterprise / Large team
   └─ All configurations + MCP servers + Hooks

Generated Configurations

Config	Purpose	When to Create
CLAUDE.md	Project memory (shared)	Always (required)
CLAUDE.local.md	Personal preferences (git-ignored)	Individual customization
.claudeignore	Files Claude should not access	Sensitive files exist
.claude/rules/	Path-specific rules	Multi-module projects
.claude/skills/	Domain knowledge	Complex business logic
.claude/agents/	Task specialists	Repeated review/debug tasks
.claude/commands/	Quick prompts	Common workflows
.claude/settings.json	Hooks + permissions	Auto-formatting, security
MCP servers	External tools	Database/API integrations

Workflow

Phase 1: Automated Analysis

python scripts/analyze_codebase.py [project-path]

The script detects:

• Languages and frameworks
• Directory structure patterns
• Development tools (linters, formatters)
• Git commit patterns
• Environment variables
• Code style indicators
• CI/CD configurations (GitHub Actions, etc.)
• Sensitive files (warns about .env, credentials)

Output includes:

• Recommendations for which configs to create
• Security warnings for sensitive files
• Suggested .claudeignore patterns

Phase 2: Context Gathering

Claude should read:

1. 3-5 representative source files - understand naming, patterns
2. Test files - understand testing approach
3. Config files - package.json, tsconfig, etc.
4. README/docs - project overview
5. Recent commits - understand commit style

Phase 2.5: Discover Existing Resources

Before creating custom configs, search for existing skills and MCP servers:

1. Search skill marketplaces - SkillsMP, SkillHub.club, Claude Skills Hub
2. Check GitHub repositories - awesome-claude-skills, themed skill collections
3. Find relevant MCP servers - Glama, MCP Market, official registry

See references/resource-discovery.md for complete directory of sources.

Tip: Many common needs (git commit, code review, database patterns) already have well-maintained skills available.

Phase 3: Generate Configurations

1. CLAUDE.md (Required)

Create at project root with:

• Quick reference commands (build, test, lint)
• Naming conventions
• Architecture overview
• Testing guidelines
• Git workflow

See references/claude-md-patterns.md.

2. Rules (If Multi-Module)

Create .claude/rules/ when:

• Multiple languages need different conventions
• Modules have distinct patterns (frontend/backend)
• Path-specific requirements exist

See references/rules-patterns.md.

3. Skills (If Complex Domain)

Create .claude/skills/ when:

• Domain-specific workflows exist (database, API patterns)
• Team knowledge needs preservation
• Complex procedures are repeated

See references/skills-patterns.md.

4. Subagents (If Specialized Tasks)

Create .claude/agents/ for:

• Code review automation
• Debugging assistance
• Security auditing
• Documentation generation

See references/agents-patterns.md.

5. Commands (If Common Operations)

Create .claude/commands/ for:

• Git commit workflow
• PR review process
• Deployment steps
• Test running

See references/commands-patterns.md.

6. Hooks (If Auto-Formatting Needed)

Configure .claude/settings.json for:

• Auto-format on file edit
• Protected files
• Command logging

See references/hooks-patterns.md.

7. MCP Servers (If External Integrations)

Configure MCP for:

• Database access
• GitHub integration
• Slack notifications
• Custom internal tools

See references/mcp-patterns.md.

Phase 4: Validate

1. Ask Claude to perform a typical task
2. Verify it follows project conventions
3. Iterate based on gaps discovered

Output Structure

Minimal (small projects):

project/
├── CLAUDE.md
└── [existing files]

Standard (team projects):

project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   └── code-style.md
│   └── commands/
│       └── commit.md
└── [existing files]

Complete (enterprise):

project/
├── CLAUDE.md              # Shared project memory
├── CLAUDE.local.md        # Personal (git-ignored)
├── .claudeignore          # Files to protect
├── .claude/
│   ├── settings.json      # Hooks + permissions
│   ├── rules/
│   ├── skills/
│   ├── agents/
│   └── commands/
└── [existing files]

Reference Materials

Reference	When to Read
examples.md	Complete real-world examples
resource-discovery.md	Find existing skills & MCP servers
advanced-patterns.md	Migrations, team collab, monorepos
claude-md-patterns.md	Creating CLAUDE.md
rules-patterns.md	Module-specific rules
skills-patterns.md	Domain knowledge
agents-patterns.md	Task specialists
commands-patterns.md	Quick prompts
hooks-patterns.md	Auto-formatting
mcp-patterns.md	External tools

Templates & Bundled Skills

Templates:

• assets/CLAUDE.md.template - Project memory template
• assets/settings.json.template - Hooks configuration
• assets/claudeignore.template - File ignore patterns

Bundled skills to install in target project:

• assets/skill-creator/ - For creating new project-specific skills
• assets/skill-downloader/ - For downloading additional skills
• assets/resource-scout/ - For discovering existing skills & MCP servers

Installing Bundled Skills

Copy these skills to the target project's .claude/skills/ directory:

cp -r assets/skill-creator [target-project]/.claude/skills/
cp -r assets/skill-downloader [target-project]/.claude/skills/
cp -r assets/resource-scout [target-project]/.claude/skills/

This enables the target project to:

1. resource-scout - Discover existing skills & MCP servers before building custom
2. skill-downloader - Download and install skills from GitHub or archives
3. skill-creator - Create custom skills tailored to their domain

Language Quick Reference

TypeScript/JavaScript

• Extract: eslint, prettier, tsconfig
• Hooks: prettier auto-format
• Skills: API patterns, component patterns

Python

• Extract: black, ruff, mypy, pyproject.toml
• Hooks: black/ruff auto-format
• Skills: API patterns, ORM patterns

Go

• Extract: gofmt, golangci-lint
• Hooks: gofmt auto-format
• Skills: error handling patterns

Rust

• Extract: rustfmt, clippy
• Hooks: rustfmt auto-format
• Skills: error handling, async patterns