codebase-analyzer

# Codebase Analyzer

Analyze project structure and generate CLAUDE.md files interactively.

## Guidelines

**MANDATORY**: All rules below must be followed exactly. Violations produce incorrect CLAUDE.md content.

@../shared/references/guidelines.md

## Algorithm

### 1. Check Existing CLAUDE.md

If CLAUDE.md already exists, ask the user how to handle it:
- **Migrate**: Convert to auto-managed format (add markers)
- **Backup**: Create CLAUDE.md.backup and generate fresh
- **Merge**: Keep manual sections, add auto-managed sections
- **Cancel**: Abort initialization

### 2. Scan Directory Structure

Detect frameworks and build systems:
- `package.json` - Node.js/JavaScript
- `pyproject.toml`, `setup.py` - Python
- `Cargo.toml` - Rust
- `go.mod` - Go
- `Makefile` - Make-based builds
- `Dockerfile` - Container builds

Extract build/test/lint commands from config files.

### 3. Identify Subtree Candidates

Look for framework boundaries that warrant separate CLAUDE.md files:
- `src/` with 10+ source files
- `lib/` directory
- `packages/*` (monorepo packages)
- `apps/*` (monorepo applications)

### 4. Detect Code Patterns

Analyze source files for conventions:
- **Naming**: PascalCase, camelCase, snake_case usage
- **Imports**: ES6 modules, CommonJS, ordering patterns
- **Architecture**: Feature-based, layered, MVC patterns
- **Style**: Indentation, quotes, semicolons

### 5. Fetch Memory Guidelines (Optional)

If network available, fetch from `https://code.claude.com/docs/en/memory`:
- Use WebFetch tool
- Extract relevant sections for context
- Reference official guidelines above as primary source

### 6. Present Findings

Use AskUserQuestion to confirm:
- Detected framework and commands
- Suggested subtree locations
- Detected patterns

### 7. Generate Memory Files

Read `.claude/auto-memory/config.json` to determine which files to generate based on `memoryFiles`:

| `memoryFiles` value | Files to generate |
|---|---|
| absent or `["CLAUDE.md"]` | `CLAUDE.md` only (full content) |
| `["AGENTS.md"]` | `AGENTS.md` only (full content) |
| `["CLAUDE.md", "AGENTS.md"]` | `AGENTS.md` (full content) + `CLAUDE.md` (redirect) |

Generate full-content files using the EXACT template structure. Follow these steps precisely:

1. **Copy template skeleton** - Use the appropriate template (CLAUDE or AGENTS) as the base structure
2. **Use exact marker format** - See Marker Syntax section below
3. **Replace placeholders** - Substitute `{{PLACEHOLDER}}` with detected content
4. **Include all required sections** - Even if content is minimal, include the section
5. **Add MANUAL section** at the end for user notes
6. **Size limits**: Root 150-200 lines, Subtrees 50-75 lines

When both `CLAUDE.md` and `AGENTS.md` are configured, also generate redirect files:
- At the root: write `CLAUDE.md` using `CLAUDE.redirect.md.template` (static pointer, no markers)
- For each subtree that gets an `AGENTS.md`: write a matching `CLAUDE.md` redirect alongside it

## Marker Syntax

**CRITICAL**: Use the EXACT marker format below. Do NOT use variations.

```markdown
<!-- AUTO-MANAGED: section-name -->
## Section Heading

Content goes here

<!-- END AUTO-MANAGED -->
```

For user-editable content:

```markdown
<!-- MANUAL -->
## Custom Notes

Add project-specific notes here. This section is never auto-modified.

<!-- END MANUAL -->
```

**Common mistakes to avoid**:
- `<!-- BEGIN AUTO-MANAGED: name -->` - WRONG (no BEGIN prefix)
- `<!-- END AUTO-MANAGED: name -->` - WRONG (no name in closing tag)
- `<!-- AUTO-MANAGED section-name -->` - WRONG (missing colon)

## Section Definitions

### Root CLAUDE.md Sections

Generate these sections in order:

| Section Name | Heading | Required | Placeholder | Content |
|--------------|---------|----------|-------------|---------|
| `project-description` | ## Overview | Yes | `{{DESCRIPTION}}` | Project name, tagline, key features |
| `build-commands` | ## Build & Development Commands | Yes | `{{BUILD_COMMANDS}}` | Build, test, lint, run commands |
| `architecture` | ## Architecture | Yes | `{{ARCHITECTURE}}` | Directory tree, key files, data flow |
| `conventions` | ## Code Conventions | Yes | `{{CONVENTIONS}}` | Naming, imports, formatting rules |
| `patterns` | ## Detected Patterns | Yes | `{{PATTERNS}}` | AI-detected recurring code patterns |
| `git-insights` | ## Git Insights | No | `{{GIT_INSIGHTS}}` | Key commits, design decisions |
| `best-practices` | ## Best Practices | No | `{{BEST_PRACTICES}}` | From official Claude Code docs |

### Subtree CLAUDE.md Sections

Generate these sections in order:

| Section Name | Heading | Required | Placeholder | Content |
|--------------|---------|----------|-------------|---------|
| `module-description` | ## Purpose | Yes | `{{DESCRIPTION}}` | Module purpose and responsibility |
| `architecture` | ## Module Architecture | Yes | `{{ARCHITECTURE}}` | Module structure, key files |
| `conventions` | ## Module-Specific Conventions | Yes | `{{CONVENTIONS}}` | Module-specific rules |
| `dependencies` | ## Key Dependencies | Yes | `{{DEPENDENCIES}}` | Module dependencies |

## Templates

Reference the template files for exact structure:

### CLAUDE.md Root Template
@templates/CLAUDE.root.md.template

### CLAUDE.md Subtree Template
@templates/CLAUDE.subtree.md.template

### AGENTS.md Root Template
@templates/AGENTS.root.md.template

### AGENTS.md Subtree Template
@templates/AGENTS.subtree.md.template

### CLAUDE.md Redirect Template (when both files configured)
@templates/CLAUDE.redirect.md.template

## User Interactions

Use AskUserQuestion for:
1. Existing CLAUDE.md handling (migrate/backup/merge/cancel)
2. Subtree location confirmation
3. Final approval before writing files

## Output

After generating files, report:
- Files created/modified
- Sections populated
- Any warnings or suggestions