Init Deep

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

```bash
{test command}

---

**src/components/CLAUDE.md Template (30-50 lines):**

```markdown
# 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

```typescript
// 1. External packages
// 2. Internal aliases (@/)
// 3. Relative imports
// 4. Types (import type)

---

**scripts/CLAUDE.md Template (30-50 lines):**

```markdown
# 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

```bash
./scripts/{script-name}.sh
# or
npm run {script-name}

---

### Phase 5: Execution

**For Fresh Projects:**

1. Create root CLAUDE.md
2. Create nested CLAUDE.md files in detected/selected directories (parallel writes)
3. Report created files

**For Migration:**

1. Create backup: `cp CLAUDE.md CLAUDE.md.backup`
2. Create nested CLAUDE.md files with migrated content
3. Rewrite root CLAUDE.md to minimal version
4. If `.claude/docs/` exists, offer to migrate or remove
5. Present before/after comparison

**For --fresh Flag:**

1. Find all existing CLAUDE.md files: `find . -name "CLAUDE.md" -type f`
2. Delete all found CLAUDE.md files
3. Run fresh project workflow

**Deduplication Check (Required):**

Before finalizing, review all generated files:
1. List all rules in root CLAUDE.md
2. Check each nested file for duplicates
3. Remove any duplicated guidance from children
4. Only domain-specific additions remain in nested files

**Before/After Report:**

```markdown
## 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)