Legacy To Ai Ready

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](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](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](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](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](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](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](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](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](references/examples.md) | Complete real-world examples | | [resource-discovery.md](references/resource-discovery.md) | Find existing skills & MCP servers | | [advanced-patterns.md](references/advanced-patterns.md) | Migrations, team collab, monorepos | | [claude-md-patterns.md](references/claude-md-patterns.md) | Creating CLAUDE.md | | [rules-patterns.md](references/rules-patterns.md) | Module-specific rules | | [skills-patterns.md](references/skills-patterns.md) | Domain knowledge | | [agents-patterns.md](references/agents-patterns.md) | Task specialists | | [commands-patterns.md](references/commands-patterns.md) | Quick prompts | | [hooks-patterns.md](references/hooks-patterns.md) | Auto-formatting | | [mcp-patterns.md](references/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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: nicepkg
• Source: nicepkg/ai-workflow
• License: MIT
• Homepage: https://ai-workflow.xiaominglab.com/

Install and usage instructions live in the source repository linked above.