---
description: Analyze repository structure and recommend optimal CLAUDE.md placement strategy
allowed-tools:
  - Bash
  - Glob
  - Grep
  - Read
  - Write
---

# Plan CLAUDE.md Strategy

Analyze the repository structure and recommend optimal CLAUDE.md file placement for context management. Determine whether a single root CLAUDE.md is sufficient or if multiple strategically-placed files would improve Claude Code's effectiveness.

## Instructions

### Phase 1: Repository Analysis

1. **Understand the repository structure at a high level**:

   a) **Get directory structure overview**:
   ```bash
   tree -L 3 -d -I 'node_modules|.git|dist|build|coverage|.next|.nuxt|vendor' | head -100
   ```

   b) **Identify repository type and scale**:
   - Is this a monorepo? (Look for `packages/`, `apps/`, `services/`, workspaces)
   - Is this a large library? (Check for multiple major modules/components)
   - Is this a standard single-app repo?
   - Count total directories: `find . -type d | grep -v node_modules | grep -v .git | wc -l`
   - Estimate codebase size: `find . -type f \( -name "*.js" -o -name "*.ts" -o -name "*.py" -o -name "*.go" -o -name "*.java" -o -name "*.rb" -o -name "*.php" \) | grep -v node_modules | wc -l`

2. **Identify major architectural boundaries**:

   a) **Scan for monorepo indicators**:
   - Look for `packages/`, `apps/`, `services/`, `modules/`, `libs/` directories
   - Check for workspace files: `package.json` (workspaces), `pnpm-workspace.yaml`, `lerna.json`, `nx.json`
   - Read these files to understand workspace structure

   b) **Identify distinct domains/modules**:
   - Use Glob to find top-level source directories: `src/**/`, `lib/**/`, `components/**/`, etc.
   - Look for clear separation of concerns (frontend/backend, api/web, services/core)
   - Identify independent subsystems that could be developed separately

   c) **Assess component independence**:
   - Can developers work on one area without needing context from others?
   - Are there clear boundaries between domains?
   - Do subdirectories have their own dependencies/configs? (e.g., separate package.json files)

3. **Analyze existing documentation patterns**:

   a) **Find existing CLAUDE.md files**:
   ```bash
   find . -name "CLAUDE.md" -o -name "claude.md" | grep -v node_modules
   ```

   b) **Find README files throughout the repo**:
   ```bash
   find . -name "README.md" | grep -v node_modules | head -20
   ```

   c) **Identify documentation concentrations**:
   - Are there subdirectories with substantial documentation already?
   - Do subdirectories have their own docs/ folders?
   - Read a few README files to understand local context needs

4. **Assess workflow patterns**:

   a) **Check for independent build/test configurations**:
   - Multiple `package.json`, `Cargo.toml`, `go.mod`, `pom.xml` files
   - Separate CI/CD configs per directory
   - Independent deployment configs

   b) **Evaluate development isolation**:
   - Would a developer working in `services/auth/` need constant context from `services/payments/`?
   - Are there teams that own specific parts of the codebase?

### Phase 2: Decision Analysis

5. **Apply decision criteria**:

   **Single CLAUDE.md is sufficient when:**
   - ✅ Small to medium codebase (<500 files, <50 directories)
   - ✅ Single unified application with tight coupling
   - ✅ No clear architectural boundaries
   - ✅ All code shares common context and patterns
   - ✅ Simple project structure (e.g., typical web app)
   - ✅ Developers need full repository context for most tasks

   **Multiple CLAUDE.md files are beneficial when:**
   - 📂 **Monorepo**: Multiple packages/apps with independent lifecycles
   - 📂 **Large library**: Distinct modules that can be understood independently
   - 📂 **Microservices**: Separate services with different tech stacks/patterns
   - 📂 **Domain boundaries**: Clear DDD-style bounded contexts
   - 📂 **Team ownership**: Different teams own different parts
   - 📂 **Scale**: >1000 files or >100 directories
   - 📂 **Context overload**: Root CLAUDE.md would be >500 lines to cover everything
   - 📂 **Independent workflows**: Subdirectories have own build/test/deploy cycles

6. **Determine recommendation**:

   Based on the analysis, decide:
   - **Option A**: Single root CLAUDE.md is optimal
   - **Option B**: Multiple CLAUDE.md files recommended with specific locations

### Phase 3: Recommendations

7. **For Option A (Single CLAUDE.md):**

   Inform the user:
   ```
   📋 CLAUDE.md Strategy Recommendation: Single File

   Analysis Results:
   - Repository type: [standard app / small library / etc.]
   - Total files: [count]
   - Architectural complexity: [low / moderate]

   ✅ Recommendation: A single CLAUDE.md at the repository root is sufficient.

   Reasoning:
   - [List 2-3 key reasons based on analysis]
   - [e.g., "Codebase is tightly coupled with shared context"]
   - [e.g., "No clear architectural boundaries found"]

   Next Steps:
   1. Ensure root CLAUDE.md exists and is comprehensive
   2. Run `/link-docs-to-claude` to ensure all docs are referenced
   3. Keep CLAUDE.md updated as the project evolves
   ```

8. **For Option B (Multiple CLAUDE.md files):**

   a) **Identify specific locations for CLAUDE.md files**:

   For each recommended location, provide:
   - **Path**: Exact directory path (e.g., `packages/web-app/`)
   - **Scope**: What this CLAUDE.md would cover
   - **Rationale**: Why this location benefits from dedicated context
   - **Key topics**: What should be documented here

   Example structure:
   ```
   Recommended CLAUDE.md locations:

   1. 📍 packages/web-app/CLAUDE.md
      Scope: Frontend web application
      Rationale: Independent React app with own build pipeline
      Key topics: Component architecture, routing, state management

   2. 📍 packages/api/CLAUDE.md
      Scope: Backend API service
      Rationale: Separate Express.js service with own deployment
      Key topics: API endpoints, authentication, database models

   3. 📍 packages/shared/CLAUDE.md
      Scope: Shared utilities and types
      Rationale: Common code used across packages
      Key topics: Utility functions, TypeScript types, constants
   ```

   b) **Create a detailed recommendation report**:

   ```markdown
   📋 CLAUDE.md Strategy Recommendation: Multi-File Approach

   ## Analysis Results

   - Repository type: [monorepo / large library / microservices]
   - Total files: [count]
   - Total directories: [count]
   - Architectural complexity: [high / very high]
   - Major subsystems identified: [count]

   ## Assessment

   ✅ Recommendation: Multiple CLAUDE.md files recommended

   ### Why Multiple Files?
   - [List 3-5 key findings from analysis]
   - [e.g., "Monorepo with 5 independent packages"]
   - [e.g., "Clear domain boundaries between services"]
   - [e.g., "Each package has own dependencies and workflows"]
   - [e.g., "Root CLAUDE.md would exceed 800 lines to cover all context"]

   ### Proposed Structure

   Root: ./CLAUDE.md
   ├── Purpose: Repository overview, monorepo patterns, cross-cutting concerns
   ├── Content: Workspace structure, shared tooling, contribution guidelines
   └── Scope: High-level architecture and repository navigation

   [For each recommended location]:
   Location: [path]
   ├── Purpose: [Brief description]
   ├── Rationale: [Why this location needs dedicated context]
   ├── Scope: [What code/domains it covers]
   └── Key Topics to Document:
       • [Topic 1]
       • [Topic 2]
       • [Topic 3]

   ## Implementation Guide

   ### Standard CLAUDE.md Template Structure

   Each CLAUDE.md file should include these standard sections:

   ```markdown
   # [Module/Package Name]

   [Brief description]

   ## Purpose
   [What this code does and why it exists]

   ## Architecture
   [Key patterns, frameworks, and structure]

   ## Key Concepts
   [Domain-specific concepts and terminology]

   ## Development Workflow
   [How to build, test, run this code]

   ## Related Documentation
   [Links to relevant docs - populated by /link-docs-to-claude]

   ## Integration Points
   [How this integrates with other parts]
   ```

   ### Implementation Steps

   For each recommended CLAUDE.md location, use Claude Code's "!" bash mode to navigate and initialize:

   **Process:**
   1. Navigate to the directory: `!cd path/to/directory`
   2. Run the init command: `/init`
   3. Repeat for each recommended location

   **Recommended initialization order:**
   1. Start with root directory: `!cd ./` then `/init`
   2. Initialize each subdirectory in order listed above
   3. After all files created, run `/link-docs-to-claude` from root

   ## Maintenance Guidelines

   - Keep each CLAUDE.md focused on its specific domain
   - Avoid duplicating information across files
   - Root CLAUDE.md provides navigation and overview
   - Subdirectory CLAUDE.md files provide deep context
   - Update CLAUDE.md files when architecture changes
   - Run `/link-docs-to-claude` periodically to maintain doc references

   ## Expected Benefits

   ✅ **Reduced context overload**: Claude Code loads only relevant context
   ✅ **Faster comprehension**: Focused documentation for specific areas
   ✅ **Better scalability**: Documentation grows with codebase structure
   ✅ **Team alignment**: Clear ownership and documentation boundaries
   ✅ **Improved accuracy**: Context matches developer mental models
   ```

9. **Provide initialization checklist (if multiple files recommended)**:

   Create a simple checklist for the user to follow:

   ```markdown
   ## CLAUDE.md Initialization Checklist

   For each location below, use "!" bash mode to navigate and initialize:

   ### Root Directory
   - [ ] `!cd ./`
   - [ ] `/init`

   ### Subdirectories
   - [ ] `!cd packages/web-app/`
   - [ ] `/init`

   - [ ] `!cd packages/api/`
   - [ ] `/init`

   - [ ] `!cd packages/shared/`
   - [ ] `/init`

   [Continue for each recommended location...]

   ### Final Step
   - [ ] Return to root: `!cd ./`
   - [ ] Link documentation: `/link-docs-to-claude`
   ```

   Customize the checklist with the actual recommended paths from your analysis.

### Phase 4: Validation and Summary

10. **Validate recommendations**:

   - Do the recommended locations align with actual architectural boundaries?
   - Are there any edge cases or special considerations?
   - Would this strategy scale with likely repository growth?

11. **Provide final summary**:

   Recap the recommendation with:
   - Clear decision (single vs. multiple)
   - Number of files recommended (if multiple)
   - Estimated effort to implement
   - Expected benefits
   - Any caveats or considerations

## Decision Logic Reference

### Indicators for Single CLAUDE.md

| Indicator | Description |
|-----------|-------------|
| Small scale | <500 files, <50 directories |
| Tight coupling | No clear separation between modules |
| Single app | Standard web app, CLI tool, or small library |
| Shared context | All code needs similar background knowledge |
| Simple structure | Flat or shallow directory hierarchy |

### Indicators for Multiple CLAUDE.md Files

| Indicator | Description |
|-----------|-------------|
| Monorepo | Multiple packages/apps/services |
| Large scale | >1000 files or >100 directories |
| Domain boundaries | Clear DDD-style bounded contexts |
| Team ownership | Different teams own different areas |
| Independent workflows | Separate build/test/deploy per area |
| Tech diversity | Different tech stacks in different areas |
| Context overload | Single file would be >500 lines |
| Documentation concentration | Subdirectories have substantial local docs |

### Recommended CLAUDE.md Placement Patterns

**Monorepo Pattern:**
```
./CLAUDE.md (overview, workspace structure)
./packages/*/CLAUDE.md (per-package context)
```

**Microservices Pattern:**
```
./CLAUDE.md (architecture overview)
./services/*/CLAUDE.md (per-service context)
```

**Large Library Pattern:**
```
./CLAUDE.md (library overview, getting started)
./src/*/CLAUDE.md (per-major-module context)
```

**Full-Stack Pattern:**
```
./CLAUDE.md (project overview)
./frontend/CLAUDE.md (frontend-specific)
./backend/CLAUDE.md (backend-specific)
```

## Important Guidelines

### Analysis Best Practices

- **Be thorough**: Don't rush the analysis phase
- **Look for patterns**: Identify recurring structures
- **Consider growth**: Think about how the repo will evolve
- **Validate boundaries**: Ensure recommended locations make sense
- **Think like a developer**: Where would context be most useful?

### Recommendation Best Practices

- **Be specific**: Provide exact paths, not vague suggestions
- **Explain rationale**: Help users understand the "why"
- **Provide templates**: Make implementation easy
- **Consider maintenance**: Recommend sustainable patterns
- **Balance granularity**: Not too few, not too many files

### Communication Best Practices

- **Be clear and decisive**: Don't hedge unnecessarily
- **Provide actionable steps**: Make it easy to implement
- **Show your work**: Explain how you reached conclusions
- **Use visual formatting**: Make recommendations scannable
- **Offer alternatives**: Note when single vs. multiple is borderline

## Error Handling

| Issue | Solution |
|-------|----------|
| Cannot determine structure | Use `tree` and `find` commands to explore |
| Ambiguous boundaries | Err on side of fewer files, note uncertainty |
| No clear monorepo structure | Check for workspace configs, separate package.json files |
| Very flat structure | Likely single CLAUDE.md is best |
| Extremely large repo | May need >10 CLAUDE.md files, group by major domains |

## Example Outputs

### Example 1: Small Project (Single File)

```
📋 CLAUDE.md Strategy Recommendation: Single File

Analysis Results:
- Repository type: Standard web application
- Total files: 234
- Total directories: 28
- Architectural complexity: Low

✅ Recommendation: A single CLAUDE.md at the repository root is sufficient.

Reasoning:
- Small, tightly-coupled codebase with shared patterns
- No clear architectural boundaries between components
- All developers need full context for most tasks
- Current structure is simple and well-organized

Next Steps:
1. Ensure root CLAUDE.md exists and covers key patterns
2. Run `/link-docs-to-claude` to reference all docs
3. Keep CLAUDE.md updated as project grows
```

### Example 2: Monorepo (Multiple Files)

```
📋 CLAUDE.md Strategy Recommendation: Multi-File Approach

Analysis Results:
- Repository type: Monorepo (Turborepo workspace)
- Total files: 2,847
- Total directories: 312
- Architectural complexity: High
- Major subsystems identified: 5 packages

✅ Recommendation: Multiple CLAUDE.md files (6 total)

Why Multiple Files?
- Monorepo with 5 independent packages (web, api, mobile, admin, shared)
- Each package has own dependencies, build config, and team ownership
- Different tech stacks (React, Node.js, React Native)
- Root CLAUDE.md would need 1000+ lines to cover everything
- Developers typically work within single package boundaries

Proposed Structure:

Root: ./CLAUDE.md
├── Purpose: Monorepo overview, tooling, workspace management
├── Content: Turborepo config, shared scripts, CI/CD, contribution guide
└── Scope: Cross-package patterns and repository navigation

Location: apps/web/CLAUDE.md
├── Purpose: Customer-facing web application
├── Rationale: Independent Next.js app with own deployment pipeline
├── Scope: Frontend components, pages, routing, state management
└── Key Topics:
    • Next.js app router patterns
    • Component architecture and design system
    • API integration with backend
    • Authentication and user flows

Location: apps/api/CLAUDE.md
├── Purpose: Backend API service
├── Rationale: Separate Express.js service with own database
├── Scope: REST endpoints, business logic, database models
└── Key Topics:
    • API endpoint structure and patterns
    • Database schema and migrations
    • Authentication/authorization
    • Background jobs and queues

Location: apps/mobile/CLAUDE.md
├── Purpose: Mobile application
├── Rationale: React Native app with platform-specific patterns
├── Scope: Mobile screens, navigation, native modules
└── Key Topics:
    • React Native patterns
    • Native module integration
    • Push notifications
    • App store deployment

Location: apps/admin/CLAUDE.md
├── Purpose: Admin dashboard
├── Rationale: Separate React app for internal users
├── Scope: Admin UI, data management, analytics
└── Key Topics:
    • Admin component patterns
    • Data tables and forms
    • User management
    • Reporting features

Location: packages/shared/CLAUDE.md
├── Purpose: Shared code library
├── Rationale: Common utilities and types used across apps
├── Scope: Utility functions, TypeScript types, constants, UI components
└── Key Topics:
    • Shared TypeScript types
    • Utility function library
    • Shared UI components
    • Configuration constants

## CLAUDE.md Initialization Checklist

For each location below, use "!" bash mode to navigate and initialize:

### Root Directory
- [ ] `!cd ./`
- [ ] `/init`

### Subdirectories
- [ ] `!cd apps/web/`
- [ ] `/init`

- [ ] `!cd apps/api/`
- [ ] `/init`

- [ ] `!cd apps/mobile/`
- [ ] `/init`

- [ ] `!cd apps/admin/`
- [ ] `/init`

- [ ] `!cd packages/shared/`
- [ ] `/init`

### Final Step
- [ ] Return to root: `!cd ./`
- [ ] Link documentation: `/link-docs-to-claude`
```

## Definition of Done

- [ ] Repository structure analyzed comprehensively
- [ ] Repository type identified (monorepo, library, standard app, etc.)
- [ ] Scale metrics gathered (file count, directory count)
- [ ] Architectural boundaries identified
- [ ] Existing documentation patterns assessed
- [ ] Workflow patterns evaluated
- [ ] Decision criteria applied systematically
- [ ] Clear recommendation made (single vs. multiple)
- [ ] Specific locations identified (if multiple recommended)
- [ ] Rationale provided for each recommended location
- [ ] Implementation guide created (templates, steps, or script)
- [ ] Expected benefits communicated
- [ ] User provided with actionable next steps
- [ ] Validation performed on recommendations
- [ ] Final summary delivered clearly