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