---
name: generating-claude-md
description: "Use when adding AI agent documentation to a project directory, creating CLAUDE.md files for new areas, or helping teams document their codebase conventions for Claude Code. Triggers on requests like 'add a CLAUDE.md', 'document this project for AI', or 'create agent instructions'."
---

# Generating CLAUDE.md Files

## Overview

Generate contextual CLAUDE.md files for project directories in a monorepo. CLAUDE.md files provide AI agents with domain-specific conventions, patterns, and commands — loading automatically when working in that directory.

**Core principle:** Scan the directory, extract real patterns from actual code, and produce a concise reference that reduces context window usage by loading only when relevant.

**Announce at start:** "I'm using the generating-claude-md skill to create documentation for this directory."

## Prerequisites

This skill works best with the [superpowers](https://github.com/obra/superpowers) plugin installed:
- `superpowers:brainstorming` — for scoping what belongs in each CLAUDE.md
- `superpowers:writing-plans` — for planning multi-file documentation efforts

Install superpowers: Claude Code Settings > Plugins > Add `obra/superpowers`

Without superpowers, follow the process below manually.

## When to Use

- Adding CLAUDE.md to a new project directory
- Helping another team document their area of a monorepo
- Fragmenting a large root CLAUDE.md into nested domain files
- Onboarding a new codebase area for AI agent usage

## How CLAUDE.md Loading Works

```
Root CLAUDE.md          → ALWAYS loaded (keep minimal)
apps/CLAUDE.md          → Loaded when working in apps/
apps/my-app/CLAUDE.md   → Loaded when working in apps/my-app/
libs/my-lib/CLAUDE.md   → Loaded when working in libs/my-lib/
```

**Key insight:** Nested files load IN ADDITION to parent files, not instead of them. Put universal info at root, domain-specific info in nested files.

## The Process

### Step 1: Scan the Directory

Analyze these files to understand the project:

| File | What It Tells You |
|------|-------------------|
| `package.json` | Dependencies, scripts, project name |
| `tsconfig.json` | TypeScript configuration, path aliases |
| `jest.config.js` / `vitest.config.mts` | Test runner and configuration |
| `.eslintrc` | Linting rules and custom configs |
| `src/index.ts` | Public API surface |
| `README.md` | Existing documentation |
| `CLAUDE.md` (parent dirs) | What's already documented upstream |
| Recent commits (`git log -20 --oneline -- <dir>`) | Active patterns and conventions |
| `*.stories.tsx` files | Component patterns and mock data |

**Critical:** Read the parent CLAUDE.md files first. Do NOT duplicate content that already exists upstream.

### Step 2: Identify What to Document

Extract from actual code — never invent patterns:

1. **Dev commands** — What scripts does `package.json` define? What's the test command?
2. **Architecture patterns** — How is code organized? What's the component structure?
3. **Data patterns** — GraphQL/REST? State management? How is data fetched?
4. **Testing patterns** — What test runner? What utilities? How are mocks structured?
5. **Build/deploy** — How is it built? Any special build steps?
6. **Domain concepts** — Business logic rules, naming conventions, gotchas
7. **Cross-references** — Related projects that agents should know about

### Step 3: Write the CLAUDE.md

**Structure:**

```markdown
# [Project Name] - AI Agent Guide

Brief 1-2 sentence description of what this project does.

## Development Commands

```bash
yarn test              # What it runs
yarn lint              # Linting
yarn check-types       # Type checking
# Any project-specific commands
```

## Architecture

- Key architectural decisions
- Component/module organization patterns
- Important conventions specific to THIS directory

## [Domain-Specific Section]

Patterns unique to this project area.

## Testing

- Which test runner (Jest/Vitest/both)
- Testing utilities and patterns used here
- How to mock data for this project

## Related Projects

- `path/to/related` - Brief description
```

**Guidelines:**
- **Target: 40-150 lines.** Shorter is better. Agents read this every session.
- **No duplicating parent CLAUDE.md content.** If root covers TypeScript conventions, don't repeat them.
- **Use actual code examples** from the project, not generic templates.
- **Commands must be verified** — run them or check package.json scripts.
- **Link to sibling projects** that agents working here would need to know about.

### Step 4: Update Parent Index

If a parent directory has a CLAUDE.md, add a cross-reference:

```markdown
## Nested Documentation

- `subdir/CLAUDE.md` - Brief description of what it covers
```

This helps agents discover related documentation even when not working directly in the subdirectory.

### Step 5: Verify

1. Read the generated CLAUDE.md — is anything duplicated from parent?
2. Are all commands accurate? (Check `package.json` scripts)
3. Is it under 150 lines? If not, trim to essentials.
4. Does it reference real patterns from actual code?

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| Copy sections from root CLAUDE.md | Reference: "See root CLAUDE.md for X" |
| Document every file in the directory | Document patterns and conventions |
| Include generic TypeScript/React advice | Only project-specific conventions |
| Write a README (purpose, installation) | Write agent instructions (how to work here) |
| Exceed 200 lines | Keep under 150, ideally 40-100 |
| Invent patterns you didn't see in code | Extract from actual files and commits |

## Fragmentation Strategy

When breaking a large root CLAUDE.md into nested files:

1. **Identify domains** — Group content by which directory it's most relevant to
2. **Move, don't copy** — Remove content from root when moving to nested file
3. **Root keeps universal info** — Repo structure, tooling (yarn/nx), commit conventions, CI/CD
4. **Add index to root** — List all nested CLAUDE.md files with descriptions
5. **Category-level indexes** — Directories with multiple documented children get their own CLAUDE.md listing nested docs (e.g., `libs/CLAUDE.md` listing `libs/picnic/CLAUDE.md`, `libs/data/CLAUDE.md`)

**Before fragmentation:**
```
Root CLAUDE.md: 1000 lines (always loaded)
```

**After fragmentation:**
```
Root CLAUDE.md: 200 lines (always loaded)
libs/CLAUDE.md: 30 lines (loaded in libs/)
libs/picnic/CLAUDE.md: 150 lines (loaded in libs/picnic/)
libs/data/CLAUDE.md: 90 lines (loaded in libs/data/)
mfes/CLAUDE.md: 60 lines (loaded in mfes/)
```

Context savings: Agent working in `libs/picnic/` loads ~380 lines instead of 1000.

## Multi-Directory Workflow

When documenting multiple directories at once:

1. **Plan first** — Use `superpowers:writing-plans` to create a task per CLAUDE.md
2. **Work bottom-up** — Start with leaf directories, then category indexes, then root updates
3. **One commit per file** — Makes review easier and allows partial reverts
4. **PR with clear scope** — Title: "docs: Add CLAUDE.md files for [domain]"

## Quick Reference

| Question | Answer |
|----------|--------|
| Where does it go? | Same directory as the code it documents |
| How long? | 40-150 lines ideal, 200 max |
| What format? | Markdown with code blocks for commands |
| Duplicate parent? | Never — reference it instead |
| Include examples? | Yes, from actual code in the directory |
| Update parent? | Yes, add cross-reference to nested doc |