Update CLAUDE.md After Installation

MANDATORY FIRST RESPONSE PROTOCOL

1. ☐ Complete Phase 0: Detect the framework
2. ☐ Complete Phase 1: Framework-specific discovery (ALL steps)
3. ☐ Create API surface inventory with counts
4. ☐ Verify >90% coverage is achievable
5. ☐ Announce: "Detected [Framework]. Starting documentation update targeting 10/10"

Overview

Context Budget Limits

If Over Budget

1. Move code examples >30 lines to "reference by path" format
2. Convert prose to tables (3x more token-efficient)
3. Consolidate overlapping sections
4. Remove redundant information between files

What Makes 10/10 Documentation

1. Step-by-Step Implementation Guides

## Adding a New API Endpoint (Laravel)

### Step 1: Create the Model
```php
class ModelName extends Model
{
    use BelongsToAccount, HasUuids;
    protected $fillable = ['account_id', 'name'];
}
```

### Step 2: Create the Form Request
### Step 3: Create the Controller (thin — delegates to Service)
### Step 4: Register Routes in routes/api.php

2. Response Formats

// NestJS — Interceptor wraps all responses:
{ success: true, data: T, timestamp: string }

// Error — Exception Filter formats:
{ success: false, error: string, code: 'ERROR_CODE', details: [...] }

3. State Machines with Visual Diagrams

## Gift Redemption State Machine

| Current | Action | New State | Who |
|---------|--------|-----------|-----|
| pending | Admin approves | fulfilled | Admin |
| pending | Admin cancels | cancelled | Admin |

4. Route/Screen Tables

| Route | File | Type | Purpose |
|-------|------|------|---------|
| `/` | app/page.tsx | Server Component | Home page |
| `/dashboard/[id]` | app/dashboard/[id]/page.tsx | Server Component | User detail |
| `/api/users` | app/api/users/route.ts | GET, POST | User CRUD |

5. API Surface Tables

| Export | Type | Purpose |
|--------|------|---------|
| parseMarkdownToBlocks | function | Parse plan text → Block[] |
| Plan | interface | Full plan with versions |

When to Use

• Initial install: User just installed agents and CLAUDE.md has generic examples
• Project start: Beginning work on a project for the first time
• Key milestones: After major architecture changes
• Periodic refresh: User asks to "update docs" or "sync CLAUDE.md with project"

Common Rationalizations (All Wrong)

• "I already know this codebase" → STILL do Phase 1 discovery
• "The exports haven't changed much" → STILL verify counts
• "This is a small project" → STILL create all 3 required files
• "80% coverage is good enough" → NO, 90% minimum
• "I can eyeball the exports" → Use search commands, not memory
• "Wrong framework won't matter" → Phase 0 detection is MANDATORY

Phase 0: Framework Detection (MANDATORY)

composer.json

artisan

app/Models/

routes/api.php

next.config.*

app/page.tsx

src/app/page.tsx

nest-cli.json

@nestjs/core

src/**/*.module.ts

app.json

"expo"

app/_layout.tsx

package.json

packages/*/package.json

packages/*/src/index.ts

Phase 1: Exhaustive Discovery (MANDATORY)

Laravel

1. Models:

   ls app/Models/*.php

   — list all, note relationships (

   belongsTo

   ,

   hasMany

   ,

   belongsToMany

   ), scopes, casts
2. Services:

   ls app/Services/**/*.php

   — list key public methods per service
3. Jobs:

   ls app/Jobs/*.php

   — note what dispatches each (Observer, Command, other Job)
4. Observers:

   ls app/Observers/*.php

   — which model, which events (

   created

   ,

   updated

   )
5. Middleware:

   ls app/Http/Middleware/*.php

   — note alias from

   bootstrap/app.php

6. API Resources:

   ls app/Http/Resources/*.php

   — which model each transforms
7. Form Requests:

   ls app/Http/Requests/*.php

   — key validation rules per request
8. Routes:

   grep "Route::" routes/api.php

   — extract ALL methods, paths, controllers, middleware groups
9. Commands:

   ls app/Console/Commands/*.php

   + schedules from

   routes/console.php

10. Also scan:

    app/Enums/

    ,

    app/Traits/

    ,

    app/Contracts/

    ,

    app/Mail/

Next.js (App Router)

1. Page routes:

   find app -name 'page.tsx' -o -name 'page.ts'

   (or

   src/app/

   ) — derive URL from path
2. API routes:

   find app/api -name 'route.ts'

   — grep for exported

   GET

   ,

   POST

   ,

   PUT

   ,

   DELETE

   ,

   PATCH

3. Layouts:

   find app -name 'layout.tsx'

   — note which routes each wraps
4. Server Actions:

   grep -r "'use server'" src --include="*.ts" --include="*.tsx"

   — list all action functions
5. Client Components:

   grep -rl "'use client'" src

   — identify interactive components
6. Middleware:

   find . -maxdepth 2 -name 'middleware.ts'

   — note matcher config
7. Hooks:

   find src/hooks -name '*.ts' -o -name '*.tsx'

   — list custom hooks
8. Types:

   grep -rh "^export interface\|^export type" src/types --include="*.ts"

NestJS

1. Modules:

   find src -name '*.module.ts'

   — note imports, exports, controllers, providers per module
2. Controllers:

   find src -name '*.controller.ts'

   — grep

   @Controller

   ,

   @Get

   ,

   @Post

   ,

   @Put

   ,

   @Delete

   ,

   @Patch

3. Services:

   find src -name '*.service.ts'

   — list key methods
4. Entities:

   find src -path '*/entities/*.ts' -o -path '*/entity/*.ts'

   — note properties, relationships
5. DTOs:

   find src -path '*/dtos/*.ts' -o -path '*/dto/*.ts'

   — note class-validator decorators
6. Guards:

   find src -name '*.guard.ts'

   — what they protect (JWT, roles, etc.)
7. Pipes:

   find src -name '*.pipe.ts'

   — validation/transformation purpose
8. Interceptors:

   find src -name '*.interceptor.ts'

   — logging, response transform, caching
9. Filters:

   find src -name '*.filter.ts'

   — exception handling
10. Decorators:

    find src/common/decorators -name '*.ts'

    — custom metadata annotations

Expo/React Native (expo-router)

1. Screen routes:

   find app -name '*.tsx' ! -name '_layout.tsx' ! -name '+not-found.tsx'

   — derive URL from path
2. Layouts:

   find app -name '_layout.tsx'

   — navigation type (Stack, Tabs, Drawer)
3. Components:

   find src/components -name '*.tsx'

   — categorize: ui, shared, features
4. Hooks:

   find src -name 'use*.ts' -o -name 'use*.tsx'

   — global + module-specific
5. Stores:

   find src -name '*Store.ts' -o -name '*store.ts'

   — Zustand/Redux state + actions
6. API hooks:

   grep -rl "useQuery\|useMutation" src --include="*.ts"

   — React Query hooks
7. Services:

   find src/services -name '*.ts'

   — API client, storage, notifications
8. Types:

   grep -rh "^export interface\|^export type" src --include="*.ts" | sort | uniq

9. Platform-specific:

   find . -name '*.ios.tsx' -o -name '*.android.tsx' -o -name '*.web.tsx'

Node.js Monorepo

1. Packages:

   ls packages/*/package.json

   — find entry points via

   jq '.main, .exports'

2. Exports:

   grep "^export" packages/*/src/index.ts

   — count types, functions, constants
3. Subpath exports:

   find packages/*/src -name "index.ts"

   + check

   "exports"

   in package.json
4. TypeScript interfaces:

   grep -rh "^export interface\|^export type" packages/*/src --include="*.ts"

5. Route handlers:

   grep -r "router\.\|app\.\(get\|post\|put\|delete\)" --include="*.ts"

6. State machines: Look for entities with

   status

   or

   state

   fields

Inventory Checklist (all frameworks)

• Complete list of all discoverable items with counts
• All routes/screens mapped
• All state machines identified (entities with status/state fields)
• Import/use patterns noted

Phase 2: Required Output Files

File 1:

exports-reference.md

(REQUIRED)

.claude/claude-md-refs/exports-reference.md

Laravel

use App\Models\Toast;

use App\Services\ToastService;

Next.js

NestJS

Expo/React Native

Node.js Monorepo

import { Type } from '@scope/package';

File 2:

development-guide.md

(REQUIRED)

.claude/claude-md-refs/development-guide.md

ApiResponse

app/

_layout.tsx

File 3:

architecture.md

(REQUIRED)

.claude/claude-md-refs/architecture.md

1. Dependency/Import Graph — ASCII diagram showing how components depend on each other
2. Request/Data Lifecycle — Flow from entry to response
3. Routes/Screens Table — ALL routes with methods, handlers/files, auth requirements
4. State Machines — ASCII diagram + transition table for each stateful entity
5. Key Subsystems — 1 paragraph + key files per major subsystem

File 4: Update

CLAUDE.md

## Project Documentation

@.claude/claude-md-refs/architecture.md
@.claude/claude-md-refs/development-guide.md
@.claude/claude-md-refs/exports-reference.md

## Quick Documentation Reference

| Need Help With | See File |
|----------------|----------|
| Adding features, endpoints, screens | development-guide.md |
| Understanding system structure, flows | architecture.md |
| Finding models, services, hooks, exports | exports-reference.md |

Phase 3: Verification (MANDATORY)

Check 1: API Surface Coverage (>90%)

find app -name "*.php" -type f | wc -l

grep -c "^|" .claude/claude-md-refs/exports-reference.md

find app -name 'page.tsx' -o -name 'route.ts' | wc -l

find src -name '*.module.ts' -o -name '*.controller.ts' -o -name '*.service.ts' | wc -l

find app -name '*.tsx' ! -name '_layout.tsx' | wc -l

find src -name 'use*.ts' | wc -l

grep -rh "^export" packages/*/src/index.ts | wc -l

Check 2: Context Budget

wc -l CLAUDE.md .claude/claude-md-refs/*.md

Check 3: Required Sections

Check 4: No Duplicates

Check 5: AI Effectiveness Test

• Find any model/service/hook/export by searching exports-reference.md?
• Add a new feature by following development-guide.md step-by-step?
• Understand the system architecture from architecture.md?
• Know which file to read for any task from CLAUDE.md Quick Reference?

Quality Checklist (Must Score 10/10)

Common Mistakes

Failure Modes

Failure Mode 1: Skipping Discovery

Failure Mode 2: Wrong Framework Detection

grep "^export"

app/Models/

Failure Mode 3: Generic Templates

Failure Mode 4: Over Budget

Failure Mode 5: Self-Assessing "Good Enough"

Failure Mode 6: No State Machines

Quick Workflow Summary

PHASE 0: DETECT FRAMEWORK
├── Check composer.json+artisan → Laravel
├── Check next.config.* → Next.js
├── Check nest-cli.json/@nestjs/core → NestJS
├── Check app.json(expo)+_layout.tsx → Expo/React Native
├── Check packages/*/package.json → Node.js monorepo
└── Announce detected framework

PHASE 1: DISCOVERY (framework-specific, do not skip)
├── Scan all classes/files/exports per framework steps
├── Map all routes/screens
├── Identify state machines
└── Create inventory with counts

PHASE 2: DOCUMENTATION (3 required files)
├── CREATE exports-reference.md (>90% coverage, framework tables)
├── CREATE development-guide.md (step-by-step, actual code)
├── CREATE architecture.md (diagrams, routes, flows)
└── UPDATE CLAUDE.md (add @imports, keep <1000 lines)

PHASE 3: VERIFICATION (all must pass)
├── API surface coverage >90%
├── Context budget met (<2500 lines total)
├── All required sections present
├── No duplicates between files
└── AI effectiveness test passes

COMPLETE: Announce final quality score (must be 10/10)

Completion Announcement

Documentation update complete.

**Framework:** [Laravel/Next.js/NestJS/Expo/Node.js monorepo]

**Quality Score: X/10**
- API Surface Coverage: X/2 (Y% of Z items documented)
- Implementation Guidance: X/2
- State/Workflow Diagrams: X/2
- Routes/Screens: X/2
- Context Efficiency: X/2

**Files created/updated:**
- exports-reference.md: X lines
- development-guide.md: X lines
- architecture.md: X lines
- CLAUDE.md: X lines
- Total: X lines (within 2,500 budget)

**Verification passed:** All 5 checks complete.