legacy-to-ai-ready

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.

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)

```

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

```

| 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 |

Phase 1: Automated Analysis

```bash

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

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 | 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:

• 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:

```bash

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

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