---

name: documentation-generator description: Generate comprehensive documentation for codebases, suitable for both human developers and AI coding assistants. Use when documenting a repository, creating architecture docs, generating API references, writing onboarding guides, or creating CLAUDE.md/AGENTS.md files for AI assistants working with the codebase.

Documentation Generator

Systematic approach to creating useful documentation for human developers and AI coding agents.

Documentation Types

1. CLAUDE.md / AGENTS.md (AI Assistant Documentation)

For AI coding assistants working with the codebase:

Copy# Project Name

## Quick Context
[One paragraph explaining what this project is]

## Tech Stack
- Language: [e.g., TypeScript 5.x]
- Framework: [e.g., Next.js 14]
- Database: [e.g., PostgreSQL with Prisma]
- Key Dependencies: [List critical packages]

## Project Structure

src/ ├── components/ # React components ├── lib/ # Shared utilities ├── pages/ # Next.js pages (routing) ├── api/ # API routes └── types/ # TypeScript type definitions

Copy
## Common Tasks

### Adding a New Feature
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Running Tests
```bash
npm test              # Run all tests
npm test -- --watch   # Watch mode

Code Conventions

• [Convention 1: e.g., Use named exports]
• [Convention 2: e.g., Components in PascalCase]
• [Convention 3: e.g., Utilities in camelCase]

Key Patterns

[Describe architectural patterns used, e.g., Repository pattern, Service layer, etc.]

Gotchas & Warnings

• [Thing that's not obvious but important]
• [Common mistake to avoid]

Important Files

• src/config/index.ts - Configuration management
• src/lib/db.ts - Database connection
• src/middleware/auth.ts - Authentication logic

Copy
### 2. Architecture Documentation (ARCHITECTURE.md)

```markdown
# Architecture Overview

## System Diagram
[ASCII diagram or link to visual diagram]

## Core Components

### [Component Name]
- **Purpose**: [What it does]
- **Location**: `path/to/component`
- **Key Files**:
  - `file1.ts` - [Description]
  - `file2.ts` - [Description]
- **Dependencies**: [What it depends on]
- **Dependents**: [What depends on it]

## Data Flow
[Describe how data flows through the system]

## External Dependencies
| Service | Purpose | Config Location |
|---------|---------|-----------------|
| [Service] | [Purpose] | [Path to config] |

## Design Decisions
### [Decision Title]
- **Decision**: [What was decided]
- **Context**: [Why this decision was needed]
- **Alternatives Considered**: [Other options]
- **Rationale**: [Why this was chosen]

3. API Documentation

Copy# API Reference

## Authentication
[How to authenticate with the API]

## Base URL
`https://api.example.com/v1`

## Endpoints

### [Resource Name]

#### GET /resource
Retrieves a list of resources.

**Query Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| page | integer | No | Page number (default: 1) |
| limit | integer | No | Items per page (default: 20) |

**Response:**
```json
{
  "data": [...],
  "meta": { "page": 1, "total": 100 }
}

Errors:

---

POST /resource

Creates a new resource.

Request Body:

Copy{
  "name": "string (required)",
  "description": "string (optional)"
}

Response: 201 Created

Copy{
  "id": "uuid",
  "name": "string",
  "created_at": "ISO8601"
}

Copy
### 4. Onboarding Guide (ONBOARDING.md)

```markdown
# Developer Onboarding

## Prerequisites
- [ ] [Tool/software 1] installed
- [ ] [Tool/software 2] installed
- [ ] Access to [system/repo]

## Setup Steps

### 1. Clone and Install
```bash
git clone [repo-url]
cd [project-name]
npm install

2. Environment Configuration

Copy .env.example to .env and configure:

Copycp .env.example .env

Required variables:

• DATABASE_URL: [How to get this]
• API_KEY: [How to get this]

3. Database Setup

Copynpm run db:migrate
npm run db:seed

4. Run the Application

Copynpm run dev

Visit http://localhost:3000

Verification Checklist

• Application starts without errors
• Can access homepage
• Can log in with test credentials
• Tests pass: npm test

Common Setup Issues

Issue: [Description]

Solution: [How to fix]

Next Steps

1. Read ARCHITECTURE.md
2. Review CONTRIBUTING.md
3. Pick up a "good first issue"

Copy
## Documentation Process

### Step 1: Analyze the Codebase

Before writing documentation:

1. **Identify the project type** (web app, library, CLI tool, etc.)
2. **Find entry points** (main files, index files)
3. **Map the directory structure**
4. **Identify key technologies and frameworks**
5. **Find existing documentation** (README, comments, wiki)
6. **Identify configuration files** (package.json, tsconfig, etc.)

### Step 2: Extract Key Information

**For each major component:**
- Purpose/responsibility
- Public interface
- Dependencies
- Usage examples

**For the project overall:**
- Build/run commands
- Test commands
- Environment requirements
- Deployment process

### Step 3: Choose Documentation Format

| Audience | Format | Focus |
|----------|--------|-------|
| AI Assistants | CLAUDE.md | Structure, conventions, gotchas |
| New Developers | ONBOARDING.md | Setup, first steps |
| All Developers | ARCHITECTURE.md | System design, data flow |
| API Consumers | API.md | Endpoints, auth, examples |
| Contributors | CONTRIBUTING.md | Process, standards |

### Step 4: Write Documentation

**Follow these principles:**

1. **Start with why** - Begin sections with purpose/context
2. **Be specific** - Use actual paths, commands, values
3. **Include examples** - Show, don't just tell
4. **Keep current** - Note version numbers, date updated
5. **Link, don't repeat** - Reference other docs instead of duplicating

## Generation Patterns

### Pattern: Directory Structure Documentation

```bash
# Use tree or manual inspection to map structure
tree -L 3 -I 'node_modules|.git|dist' > structure.txt

Then annotate:

Copysrc/
├── components/         # Reusable UI components
│   ├── common/         # Generic components (Button, Input, etc.)
│   └── features/       # Feature-specific components
├── hooks/              # Custom React hooks
├── lib/                # Utility functions and helpers
│   ├── api.ts          # API client
│   └── utils.ts        # General utilities
└── types/              # TypeScript type definitions

Pattern: Code Convention Extraction

Look for patterns in existing code:

• File naming conventions
• Export patterns
• Error handling patterns
• Comment style
• Test file organization

Document what you find:

Copy## Conventions

### File Naming
- Components: `PascalCase.tsx`
- Utilities: `camelCase.ts`
- Tests: `*.test.ts` colocated with source

### Exports
- Components: Named exports
- Utilities: Named exports from index.ts barrel files

Pattern: Command Documentation

Find commands in package.json, Makefile, or scripts:

Copy## Available Commands

| Command | Description |
|---------|-------------|
| `npm run dev` | Start development server with hot reload |
| `npm run build` | Create production build |
| `npm test` | Run test suite |
| `npm run lint` | Check code style |
| `npm run lint:fix` | Fix auto-fixable issues |

Pattern: Environment Variable Documentation

Copy## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `DATABASE_URL` | Yes | - | PostgreSQL connection string |
| `PORT` | No | 3000 | Server port |
| `LOG_LEVEL` | No | info | Logging verbosity |

AI-Specific Documentation Tips

When creating docs for AI coding assistants:

Do Include:

• Exact file paths
• Working code examples
• Common error messages and fixes
• Implicit conventions not obvious from code
• "Why" explanations for unusual patterns
• Commands that are frequently used

Don't Include:

• Obvious things the AI can infer from code
• Excessive background/history
• Marketing language
• Redundant information

Format for AI Consumption:

• Use consistent headers
• Prefer code blocks over prose
• Use tables for structured data
• Keep sections focused and scannable
• Include file paths with descriptions

Reference Files

• references/templates.md - Documentation templates for various project types
• references/analysis-checklist.md - Checklist for codebase analysis