update-agent-docs

name	update-agent-docs
description	Analyze a codebase and update or create CLAUDE.md agent documentation. Extracts project patterns, conventions, and principles through codebase exploration, then presents findings for interactive refinement. Use when user says "update CLAUDE.md", "refresh agent docs", "create CLAUDE.md", "improve agent documentation", or "document codebase for Claude".

Update Agent Documentation

Analyze a codebase to extract patterns, conventions, and principles, then create or update CLAUDE.md documentation through interactive refinement.

When to Use This Skill

Use this skill when the user explicitly requests:

• "Update CLAUDE.md"
• "Refresh agent docs"
• "Create CLAUDE.md"
• "Improve agent documentation"
• "Document codebase for Claude"
• "Generate CLAUDE.md"

Important: This skill runs only on explicit request.

Core Principles

1. Discovery-first: Explore the codebase thoroughly before drafting
2. Interactive refinement: Present findings to user for discussion
3. Evidence-based: Every principle should cite specific code examples
4. Actionable: Focus on patterns that guide actual coding decisions
5. Concise: Sacrifice verbosity for clarity

---

Workflow

Phase 1: Initialization

1. Find existing CLAUDE.md files:

   find . -name "CLAUDE.md" -type f 2>/dev/null
   

2. Ask user about scope using AskUserQuestion:

   • Which CLAUDE.md to update? (root, subdirectory, or create new)
   • If creating new, where should it live?

3. Read existing CLAUDE.md (if present):

   • Understand current structure
   • Note what's already documented
   • Identify gaps or outdated sections

4. Inform user:

   • "I'll analyze your codebase using multiple exploration agents"
   • "Then present my findings for your review"
   • "We'll iterate until the documentation feels right"

Phase 2: Parallel Exploration

Launch 5 Task agents with subagent_type: "Explore" in parallel to analyze different aspects:

Agent 1: Tech Stack & Project Structure

Explore this codebase to identify the technology stack:

1. Find and read configuration files:
   - package.json, Cargo.toml, pyproject.toml, go.mod
   - tsconfig.json, babel.config.js, webpack.config.js
   - Docker files, CI configs

2. Identify:
   - Primary programming language(s)
   - Web framework (if any)
   - Database technology (if any)
   - Build tools and bundlers
   - Package manager
   - Test framework

3. Note major dependencies and their purposes

4. Map the top-level directory structure

Return a structured summary with file paths as evidence.

Agent 2: Code Style & Conventions

Explore this codebase to identify coding conventions:

1. Read 8-10 source files from different parts of the codebase

2. Look for consistent patterns in:
   - Variable naming (camelCase, snake_case, PascalCase)
   - Function naming
   - File naming (kebab-case.ts, PascalCase.tsx)
   - Import ordering (stdlib first? alphabetical?)
   - Comment style (JSDoc? inline? sparse?)

3. Identify error handling patterns:
   - try/catch usage
   - Result types
   - Error class patterns

4. Check for linting/formatting configs:
   - .eslintrc, .prettierrc, rustfmt.toml
   - Pre-commit hooks

Return examples from actual files with file paths.

Agent 3: Architecture Patterns

Explore this codebase to understand its architecture:

1. Map the src/ directory structure

2. Identify architectural patterns:
   - MVC / MVVM / Clean Architecture
   - Repository pattern
   - Service layer pattern
   - Factory patterns

3. Understand data flow:
   - Where do API calls originate?
   - How is state managed?
   - Where is business logic located?

4. Look for:
   - Dependency injection patterns
   - Interface/abstraction usage
   - Shared utilities location

Return findings with specific file paths as examples.

Agent 4: Testing Practices

Explore this codebase to understand testing practices:

1. Find test files and their organization:
   - Are tests co-located or in separate directory?
   - Test file naming convention (.test.ts, _test.go, etc.)

2. Identify test framework and patterns:
   - Jest, Vitest, pytest, go test, etc.
   - Mock/stub patterns
   - Fixture usage

3. Check for:
   - Test coverage configuration
   - CI test configuration
   - Test helper utilities

4. Look at test file structure:
   - describe/it patterns
   - Setup/teardown patterns
   - Assertion style

Return examples of well-written tests from the codebase.

Agent 5: Development Workflow

Explore this codebase to understand development workflow:

1. Check package.json/Makefile for common scripts:
   - dev, start, build, test, lint
   - Database/migration commands

2. Look for:
   - Environment configuration (.env.example)
   - Docker setup (docker-compose.yml)
   - CI/CD configuration (.github/workflows, .gitlab-ci.yml)

3. Check git patterns:
   - Branch naming in recent history
   - Commit message patterns
   - PR template if present

4. Identify:
   - Local development prerequisites
   - Common CLI commands
   - Deployment patterns

Return actionable commands and workflows.

Phase 3: Synthesize Findings

After exploration agents complete:

1. Aggregate discoveries into categories:

   • Project Overview
   • Tech Stack
   • Project Structure
   • Code Style & Patterns
   • Architecture
   • Development Workflow
   • Testing
   • Constraints

2. Identify actionable principles - things Claude should do or avoid:

   • Explicit dos/don'ts
   • Before/after examples from the codebase
   • File paths and specific patterns

3. Rate confidence for each finding:

   • High: Consistent pattern across 5+ files
   • Medium: Pattern in 2-4 files
   • Low: Single occurrence or inference

Phase 4: Interactive Review

Present findings to user using AskUserQuestion:

Step 1: Overview Review

Question: "Here's what I found about your project. Is this accurate?"

[Present: Tech stack, main purpose, structure summary]

Options:
- "Looks correct" - Continue to details
- "Some corrections needed" - Let user provide corrections

Step 2: Code Style Review

Question: "I identified these coding conventions. Should I document them?"

[Present each pattern with code example]

For each pattern, options:
- "Yes, document this"
- "No, not a real pattern"
- "Modify this"

Step 3: Architecture Review

Question: "These architecture patterns seem important:"

[Present each pattern]

Options per pattern:
- "Include"
- "Skip"
- "Expand"

Step 4: Constraints & Anti-patterns

Question: "Did I miss any important constraints or anti-patterns? Things Claude should NEVER do in this codebase?"

Options:
- "Add these constraints" - User provides list
- "None to add" - Continue

Step 5: Priority Areas

Question: "What aspects of the codebase does Claude struggle with most? What should be emphasized?"

Options:
- User provides specific pain points
- "Not sure" - Use defaults

Phase 5: Draft Generation

Based on confirmed findings, generate CLAUDE.md following the template in TEMPLATE.md.

Key structure:

1. One-liner description
2. Tech Stack
3. Quick Start commands
4. Project Structure
5. Code Style with ❌/✅ examples
6. Architecture patterns
7. Testing approach
8. Constraints (Never/Always)

Phase 6: Review & Iterate

Present the draft using AskUserQuestion:

Question: "Here's the draft CLAUDE.md. How should we proceed?"

[Show full draft or section-by-section]

Options:
- "Looks good, write it"
- "Modify section: [X]"
- "Add section about [Y]"
- "Too verbose, condense"
- "Too brief, expand [Z]"

Iterate until user approves.

Phase 7: Write File

After user confirms:

1. Confirm file path using AskUserQuestion:

   Question: "Write to [path]/CLAUDE.md?"
   Options:
   - "Yes, write it"
   - "Different location"
   

2. Write the file using Write tool

3. Suggest next steps:

   • "Run a few tasks to test if the documentation helps"
   • "Consider adding subdirectory CLAUDE.md files for specific areas"

---

Notes

• Launch exploration agents in parallel (single message, multiple Task tool calls)
• Always cite specific file paths as evidence for patterns
• Prioritize actionable guidance over descriptions
• Keep examples from actual codebase, not hypothetical
• CLAUDE.md should be readable in under 2 minutes
• Use ❌/✅ markers for anti-patterns and preferred patterns
• Focus on current state, not historical changes

Error Handling

• No source files found: Ask user to confirm project path
• Mixed conventions: Note inconsistency, ask user which to prefer
• Existing CLAUDE.md conflict: Ask to merge, replace, or create alongside
• User cancels: Inform them findings are not saved

Template Reference

See TEMPLATE.md for the CLAUDE.md template structure.