/gen-claude-md

Deeply explore the codebase with parallel agents, then generate or update CLAUDE.md with discovered patterns.

Usage

/gen-claude-md          # Generate new CLAUDE.md (or update if exists)
/gen-claude-md --update # Only update specific sections

---

PHASE 1: PARALLEL EXPLORATION

Deploy 5 exploration agents simultaneously using the Task tool:

Agent Prompts

Launch ALL of these in a SINGLE message with multiple Task tool calls:

1. Architecture Agent (subagent_type: Explore)

   Explore the codebase architecture:
   - Entry points (main files, index files)
   - Directory structure and organization
   - Core abstractions and patterns
   - Module boundaries and dependencies
   Return: bullet points of key architectural findings
   

2. Tech Stack Agent (subagent_type: Explore)

   Identify the technology stack:
   - Package manager and dependencies (package.json, requirements.txt, etc.)
   - Frameworks and libraries in use
   - Build tools and scripts
   - Database/storage technologies
   Return: categorized list of technologies with versions
   

3. Testing Agent (subagent_type: Explore)

   Analyze the testing setup:
   - Test framework(s) used
   - Test file locations and naming conventions
   - Types of tests (unit, integration, e2e)
   - Test commands and configuration
   Return: testing patterns and commands
   

4. Patterns Agent (subagent_type: Explore)

   Discover coding patterns and conventions:
   - Naming conventions (files, functions, variables)
   - Code organization patterns
   - Error handling patterns
   - State management approach
   Return: documented patterns with examples
   

5. Config Agent (subagent_type: Explore)

   Find configuration and environment setup:
   - Environment variables needed (.env.example, config files)
   - Required setup steps
   - CI/CD configuration
   - Deployment setup
   Return: setup requirements and config patterns
   

---

PHASE 2: SYNTHESIS

After all agents return, synthesize findings into CLAUDE.md:

If CLAUDE.md doesn't exist:

Create new file with discovered information filling in the template:

# CLAUDE.md

> Auto-generated by /gen-claude-md. Update this file when Claude makes mistakes.

## Project Overview

**Project:** {from directory name or package.json}
**Tech Stack:** {from Tech Stack Agent}
**Purpose:** {infer from README or code}

## Quick Start

{from Config Agent - actual commands found}

## Architecture

{from Architecture Agent - actual structure found}

## Key Patterns

{from Patterns Agent - actual patterns found}

### Code Style
{discovered conventions}

### Testing
{from Testing Agent}

## Anti-Patterns (DO NOT DO)

| Date | Mistake | Correct Approach |
|------|---------|------------------|
| | | |

<!-- Add mistakes here as you find them -->

## Gotchas

{any non-obvious things discovered during exploration}

## Environment Variables

{from Config Agent}

---
*Generated: {timestamp}*
*Re-run /gen-claude-md to update with new discoveries*

If CLAUDE.md exists:

Read existing file and MERGE new discoveries:

• Don't overwrite Anti-Patterns table (user-added content)
• Don't overwrite Gotchas (user-added content)
• Update tech stack if changed
• Add newly discovered patterns
• Preserve custom sections

---

PHASE 3: OUTPUT

After generating/updating:

CLAUDE.md generated from codebase exploration

Discovered:
- Tech: {list key technologies}
- Patterns: {count} coding patterns documented
- Tests: {test framework} with {convention}
- Config: {count} environment variables needed

Sections to customize:
- [ ] Add project purpose/description
- [ ] Add known gotchas
- [ ] Add team conventions (if shared repo)

Remember: Update CLAUDE.md when Claude makes mistakes!
Use /add-mistake for quick additions.

---

Example Exploration Output

When you run the agents, you might discover:

Architecture Agent:
- Entry: src/index.ts
- Pattern: Feature-based folders (src/features/*)
- API: REST endpoints in src/api/
- Shared: src/lib/ for utilities

Tech Stack Agent:
- Runtime: Node.js 20
- Framework: Express 4.18
- Database: PostgreSQL via Prisma
- Testing: Jest + Supertest

Testing Agent:
- Location: __tests__/ directories
- Naming: *.test.ts
- Command: npm test
- Coverage: npm run test:coverage

Patterns Agent:
- Files: kebab-case.ts
- Functions: camelCase
- Components: PascalCase
- Error handling: try/catch with custom AppError class

Config Agent:
- Required: DATABASE_URL, JWT_SECRET, PORT
- Optional: LOG_LEVEL, REDIS_URL
- Setup: npm install && npm run db:migrate

This gets synthesized into a complete, project-specific CLAUDE.md.