/init-deep              # Update: modify existing + create new where needed
/init-deep --fresh      # Delete all CLAUDE.md files, regenerate from scratch
/init-deep --max-depth=2 # Limit nesting depth (default: unlimited)

Score = (file_count * 3) + (reference_centrality * 3) + (symbol_density * 1) + (export_count * 1)

src/           # Source code root
tests/         # Test files
test/          # Alternative test directory
lib/           # Library code
api/           # API layer (may be under src/)
components/    # UI components
hooks/         # React/custom hooks
utils/         # Utility functions
services/      # Service layer
scripts/       # Build/dev scripts
packages/      # Monorepo packages
apps/          # Monorepo apps

src/api/
src/components/
src/hooks/
src/utils/
src/services/
src/lib/
src/routes/
src/pages/
src/stores/
src/models/

# Find directories that should have CLAUDE.md
for dir in tests test src lib api components hooks utils services scripts packages apps; do
  if [ -d "$dir" ]; then
    echo "FOUND: $dir/"
  fi
done
 
# Check src/ subdirectories
if [ -d "src" ]; then
  for subdir in api components hooks utils services lib routes pages stores models; do
    if [ -d "src/$subdir" ]; then
      echo "FOUND: src/$subdir/"
    fi
  done
fi

What does this project do? (One sentence)
 
Example: "A CLI tool for managing Kubernetes deployments"

Which package manager does this project use?
 
Options:
- npm (default, will not be documented)
- pnpm
- yarn
- bun
- none (not a JS/TS project)

Any build, test, or lint commands that differ from standard?
 
Leave blank if using standard commands (npm test, npm run build).
Only specify if different, e.g., "pytest -v" or "make release"

I detected these directories. Which should have their own CLAUDE.md?
 
Detected:
- [x] tests/
- [x] src/components/
- [x] src/api/
- [ ] src/utils/
- [ ] scripts/
 
Select all that would benefit from contextual guidance.
(Default: tests/ and any domain-specific src/ directories)

Found existing CLAUDE.md ({N} lines). Options:
 
1. Analyze and migrate - Extract content to nested CLAUDE.md files
2. Replace - Create fresh minimal structure (backup original)
3. Cancel - Keep existing structure

## CLAUDE.md Analysis
 
### Metrics
| Metric | Value | Status |
|--------|-------|--------|
| Total Lines | 245 | MIGRATE |
| Instructions | 52 | HIGH |
| Hardcoded Paths | 18 | WARNING |
 
### Content Migration Plan
| Lines | Content | Destination |
|-------|---------|-------------|
| 1-15 | Project description | Root CLAUDE.md |
| 20-45 | Testing patterns | tests/CLAUDE.md |
| 50-95 | Component conventions | src/components/CLAUDE.md |
| 100-140 | API design patterns | src/api/CLAUDE.md |
| 145-180 | General coding style | src/CLAUDE.md |
| 185-245 | Outdated/stale content | REMOVE (with approval) |

# {Project Name}
 
{One-sentence description}
 
## Development
 
{Package manager line - ONLY if not npm}
 
{Non-standard commands - ONLY if provided}
 
## Where to Look
 
| Task | Location |
|------|----------|
| Add new API endpoint | src/api/ |
| Add UI component | src/components/ |
| Add utility function | src/utils/ |
| Write tests | tests/ |
| Add service integration | src/services/ |
| Modify build/deploy | scripts/ |
 
## Agent Workflow
 
Explore finds -> Librarian reads -> You plan -> Worker implements -> Validator checks
 
When delegating to agents:
-Use positive constraints ("ensure X") not negative ("don't do Y")
-Include context, expected output, acceptance criteria
-Launch independent tasks in parallel
 
## Guidance
 
Context-specific guidance lives in nested CLAUDE.md files throughout the repo.
These load automatically when you work in those directories.
Closest CLAUDE.md to the file being edited takes precedence.

# Testing
 
## Framework
 
{e.g., Jest, Vitest, pytest, Go testing}
 
## Patterns
 
-Test files: `*.test.ts` or `*.spec.ts`
-Describe blocks mirror module structure
-One assertion per test when practical
 
## Running Tests
 

 
## Mocking
 
- Prefer real implementations over mocks
- Mock only: network, time, randomness, file system
 
## Coverage
 
Focus on behavior, not percentage. Critical paths need thorough coverage.
 
## Anti-Patterns
 
- Don't mock what you can test directly
- Don't test implementation details
- Don't share mutable state between tests
- Don't write tests that pass when code is broken

# Components
 
## Structure
 

 
## Naming
 
- Components: PascalCase
- Props interface: `{ComponentName}Props`
- Files match component name
 
## Patterns
 
- Prefer composition over inheritance
- Extract hooks for reusable logic
- Props over context for explicit dependencies
 
## Exports
 
{Named exports / default exports preference}
 
## Anti-Patterns
 
- Don't use inline styles when CSS modules exist
- Don't prop-drill beyond 2 levels - use context
- Don't mix data fetching with presentation
- Don't create god components (>200 lines)

# API Layer
 
## Design
 
-RESTful endpoints / GraphQL / tRPC
-Consistent error response format
-Request validation at boundary
 
## Patterns
 
-Controllers handle HTTP concerns only
-Business logic lives in services
-Validate input, sanitize output
 
## Error Handling
 

 
## Authentication
 
{auth pattern if applicable}
 
## Anti-Patterns
 
- Don't expose internal errors to clients
- Don't skip input validation
- Don't leak sensitive data in responses
- Don't mix auth logic with business logic

# Hooks
 
## Naming
 
-Prefix with `use`: `useAuth`, `useForm`, `useFetch`
-Name describes the capability, not implementation
 
## Patterns
 
-Single responsibility per hook
-Return stable references (useMemo, useCallback)
-Handle cleanup in useEffect
 
## Testing
 
-Test hooks via @testing-library/react-hooks
-Test state transitions, not implementation
 
## Common Hooks
 
{list project-specific hooks if established}
 
## Anti-Patterns
 
-Don't call hooks conditionally
-Don't create hooks with side effects on mount without cleanup
-Don't return unstable references
-Don't nest hooks more than 2 levels deep

# Utilities
 
## When to Create
 
Create a utility when:
-Logic is used in 3+ places
-Function is pure (no side effects)
-Behavior is well-defined and testable
 
## Patterns
 
-Pure functions preferred
-No dependencies on external state
-Comprehensive input validation
-Clear, descriptive names
 
## Naming
 
-Functions: camelCase, verb-first (`formatDate`, `parseInput`)
-Files: kebab-case or camelCase (match project convention)
 
## Testing
 
Every utility function needs tests. They're isolated and easy to test.
 
## Anti-Patterns
 
-Don't create utils for single-use logic
-Don't add side effects to pure functions
-Don't create "misc" or "helpers" grab-bags
-Don't depend on global state

# Services
 
## Purpose
 
Services encapsulate external integrations and complex business logic.
 
## Patterns
 
-One service per external dependency
-Services are injectable/mockable
-Handle retries, timeouts, circuit breaking
 
## Structure
 

 
## Error Handling
 
- Wrap external errors in domain-specific errors
- Log at service boundary
- Never expose internal details to callers
 
## Anti-Patterns
 
- Don't call services from other services directly - use orchestrator
- Don't mix HTTP/DB concerns in same service
- Don't retry without backoff
- Don't swallow errors silently

# Source Code
 
## Style
 
-{indent style}
-{semicolons yes/no}
-{quote style}
 
## Imports
 

 
## Naming
 
- Files: {convention}
- Functions: camelCase
- Classes: PascalCase
- Constants: SCREAMING_SNAKE
 
## Patterns
 
- Prefer early returns
- Explicit over implicit
- Composition over inheritance
 
## Anti-Patterns
 
- Don't use `any` - use `unknown` and narrow
- Don't nest callbacks >2 levels
- Don't mutate function arguments
- Don't use magic numbers without constants

# Scripts
 
## Purpose
 
Build, deployment, and development automation scripts.
 
## Conventions
 
-Scripts are executable: `chmod +x script.sh`
-Include usage comment at top
-Exit codes: 0 success, 1 error
-Use `set -euo pipefail` for bash scripts
 
## Running
 

 
## Adding New Scripts
 
1. Create in scripts/ directory
2. Add npm script alias if frequently used
3. Document purpose in script header
 
## Anti-Patterns
 
- Don't hardcode paths - use variables
- Don't skip error handling
- Don't assume dependencies exist - check first
- Don't write scripts without idempotency

## Migration Complete
 
### Before
-Root CLAUDE.md: 245 lines
-Nested CLAUDE.md: 0 files
-.claude/docs/: 3 files
 
### After
-Root CLAUDE.md: 85 lines (65% reduction)
-Nested CLAUDE.md: 4 files
  -tests/CLAUDE.md (35 lines)
  -src/components/CLAUDE.md (42 lines)
  -src/api/CLAUDE.md (38 lines)
  -src/CLAUDE.md (30 lines)
 
### Backup
Original preserved at CLAUDE.md.backup
 
### Benefit
Root context cost reduced from 245 to 85 lines.
Domain guidance loads only when working in those directories.

Created nested CLAUDE.md structure:
 
Root:
  - CLAUDE.md ({N} lines)
 
Nested:
  - tests/CLAUDE.md ({N} lines) - Testing patterns
  - src/components/CLAUDE.md ({N} lines) - Component patterns
  - src/api/CLAUDE.md ({N} lines) - API patterns
 
How it works:
Claude automatically loads CLAUDE.md from any directory it reads.
When you work in src/api/, the API patterns load automatically.
Closest file to your edit takes precedence ("closest wins").
 
Next steps:
1. Review each CLAUDE.md and customize for your project
2. Add patterns as they emerge during development
3. Keep files focused and minimal (30-80 lines nested, 50-150 root)