claude-project-docs

Original source / Raw SKILL.md

---
name: claude-project-docs
description: Generate concise CLAUDE.md files and agent documentation following best practices. Use when setting up a new project for Claude Code, auditing existing CLAUDE.md, or creating progressive disclosure documentation structure.
---

# Claude Project Docs

Create well-crafted, minimal CLAUDE.md files (~60 lines) with progressive disclosure through agent_docs/.

## When to Use

Invoke when user:
- Asks to "set up Claude for this project" or "create a CLAUDE.md"
- Wants to "audit" or "improve" their existing CLAUDE.md
- Needs to create agent documentation or progressive disclosure structure
- Says "help Claude understand this codebase"

## Core Methodology

### The 60-Line Rule

CLAUDE.md goes into EVERY session. Keep it:
- **< 60 lines** ideal (HumanLayer recommendation)
- **< 300 lines** absolute maximum
- **Universally applicable** - no task-specific content

### WHAT/WHY/HOW Structure

```markdown
# Project Name

[One sentence: what this is]

## Tech Stack
- [Framework/Language]
- [Key dependencies]

## Project Structure
[3-5 line overview of directories that matter]

## Development
[Essential commands only - build, test, run]

## Critical Rules
[2-3 non-negotiable constraints]

## Reference Documentation
When working on specific tasks, read:
- `agent_docs/[topic].md`
```

### Progressive Disclosure

Create `agent_docs/` for task-specific documentation:

| File | Content |
|------|---------|
| `building.md` | Build commands, compilation, bundling |
| `testing.md` | Test commands, coverage, fixtures |
| `architecture.md` | System design, key decisions |
| `database.md` | Schema, migrations, connections |
| `deployment.md` | Deploy process, environments |

Claude reads these ON DEMAND, not every session.

## Anti-Patterns to Prevent

**NEVER include in CLAUDE.md:**
- Code style rules (use ESLint/Prettier/linters)
- Full command documentation (use agent_docs/)
- Implementation examples (point to actual code)
- > 300 lines of content
- Generic boilerplate from /init

**Why:** LLMs follow ~150-200 instructions reliably. Every unnecessary line degrades compliance.

## Workflow

### 1. Generate New CLAUDE.md

```
User: Set up Claude for this project
→ Analyze: package.json, pyproject.toml, go.mod, Makefile
→ Generate: Minimal CLAUDE.md (~60 lines)
→ Create: agent_docs/ structure
```

### 2. Audit Existing CLAUDE.md

```
User: Audit my CLAUDE.md
→ Check: Line count, anti-patterns, task-specific content
→ Report: Issues found with severity
→ Suggest: Specific removals and agent_docs/ migrations
```

### 3. Create Agent Docs

```
User: Create agent docs for testing
→ Generate: agent_docs/testing.md with project-specific content
→ Update: CLAUDE.md reference section
```

## Output Format

When generating CLAUDE.md:
1. Show the complete file content
2. Explain what was included and why
3. List what was intentionally excluded
4. Suggest agent_docs/ files to create next

## References

For templates and examples:
- `references/claude-md-template.md` - Minimal starter template
- `references/agent-docs-catalog.md` - Complete agent_docs file list
- `references/anti-patterns.md` - Detailed anti-pattern guide
- `references/examples/` - Project-type examples

---

**Principle:** High leverage documentation. Every line in CLAUDE.md costs context across all sessions.


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### references/claude-md-template.md

```markdown
# CLAUDE.md Template

Minimal template following the 60-line rule. Copy and customize.

## The Template (~55 lines)

```markdown
# [Project Name]

[One sentence describing what this project is and does.]

## Tech Stack

- [Primary language/framework]
- [Database if applicable]
- [Key dependencies (3-5 max)]

## Project Structure

```
[root]/
├── [main-source]/    # [Brief description]
├── [secondary]/      # [Brief description]
├── [config]/         # [Brief description]
└── [tests]/          # [Brief description]
```

## Development

**Build:** `[build command]`
**Test:** `[test command]`
**Run:** `[run/dev command]`
**Lint:** `[lint command]` (configured in [config file])

## Critical Rules

- [Rule 1: Non-negotiable constraint]
- [Rule 2: Security or architectural boundary]
- [Rule 3: Process requirement]

## Reference Documentation

When working on specific tasks, read relevant files:
- `agent_docs/building.md` - Build process and compilation
- `agent_docs/testing.md` - Test patterns and fixtures
- `agent_docs/architecture.md` - System design decisions
```

## Filling the Template

### Project Name Section

One sentence only. Answer: "What is this?"

**Good:**
```markdown
# Acme API

REST API for Acme's customer management system.
```

**Bad:**
```markdown
# Acme API

This is the main API server for Acme Corporation's customer
management platform. It was started in 2019 and has grown to
support over 50 endpoints across 12 domains...
```

### Tech Stack Section

3-5 items maximum. Only what Claude needs to know for code style.

**Good:**
```markdown
## Tech Stack
- Python 3.11 + FastAPI
- PostgreSQL + SQLAlchemy
- Redis for caching
- pytest for testing
```

**Bad:**
```markdown
## Tech Stack
- Python 3.11.4
- FastAPI 0.104.1
- PostgreSQL 15.2
- SQLAlchemy 2.0.23
- Redis 7.2.3
- pytest 7.4.3
- black 23.11.0
- mypy 1.7.1
- ruff 0.1.6
- pre-commit 3.6.0
- Docker 24.0.7
- docker-compose 2.23.0
...
```

### Project Structure Section

Only directories that matter for navigation. 3-5 lines.

### Development Section

Only the commands Claude will actually run. No explanations.

### Critical Rules Section

2-3 rules maximum. These must be:
- **Universal** - Apply to every task
- **Non-obvious** - Claude wouldn't guess them
- **Consequential** - Breaking them causes real problems

**Good rules:**
- Never modify files in `legacy/` - deprecated, will be removed
- All API changes require OpenAPI spec update first
- Database migrations must be reversible

**Bad rules:**
- Use 4-space indentation (that's a linter's job)
- Write tests for new code (Claude does this anyway)
- Follow REST conventions (too vague)

### Reference Documentation Section

List your `agent_docs/` files. Claude will read them when relevant.

## Line Count Check

Count your lines:
```bash
wc -l CLAUDE.md
```

| Lines | Status |
|-------|--------|
| < 40 | Minimal, may need more context |
| 40-60 | Ideal range |
| 60-100 | Acceptable, consider trimming |
| > 100 | Too long, audit needed |
| > 300 | Critical, refactor immediately |

## What NOT to Include

See `anti-patterns.md` for detailed guidance on what to exclude.

Quick list:
- Code style rules (use linters)
- Full command documentation (use agent_docs/)
- API documentation (use OpenAPI/docs/)
- Onboarding instructions for humans
- Project history or roadmap
- Team information

```

### references/agent-docs-catalog.md

```markdown
# Agent Docs Catalog

Complete catalog of `agent_docs/` files for progressive disclosure.

## Core Principle

CLAUDE.md is read every session. `agent_docs/` files are read on-demand.

Put task-specific content in agent_docs/ to:
- Reduce CLAUDE.md bloat
- Keep session context focused
- Allow detailed documentation per topic

## Directory Structure

```
project-root/
├── CLAUDE.md              # ~60 lines, universal
└── agent_docs/
    ├── building.md        # Build and compilation
    ├── testing.md         # Test patterns and execution
    ├── architecture.md    # System design
    ├── database.md        # Data layer
    ├── deployment.md      # Deploy process
    ├── api.md             # API design patterns
    ├── security.md        # Security practices
    └── debugging.md       # Debug workflows
```

## File Specifications

### building.md

**Purpose:** Build process, compilation, bundling

**Include:**
- Build commands with common flags
- Environment-specific builds (dev, staging, prod)
- Build artifacts and their locations
- Common build errors and fixes
- Asset pipeline details

**Template:**
```markdown
# Building

## Quick Commands
- Dev build: `npm run build:dev`
- Prod build: `npm run build:prod`
- Watch mode: `npm run build:watch`

## Build Artifacts
Output goes to `dist/`:
- `dist/server/` - Node.js server bundle
- `dist/client/` - Browser assets

## Environment Variables
Build respects these env vars:
- `NODE_ENV` - development|production
- `API_URL` - Backend API endpoint

## Common Issues
[List 2-3 frequent build problems and solutions]
```

---

### testing.md

**Purpose:** Test execution, patterns, fixtures

**Include:**
- Test commands (unit, integration, e2e)
- Test file locations and naming
- Fixture/mock patterns used
- Coverage requirements
- CI test configuration

**Template:**
```markdown
# Testing

## Quick Commands
- All tests: `npm test`
- Unit only: `npm run test:unit`
- E2E: `npm run test:e2e`
- Coverage: `npm run test:coverage`

## Test Structure
tests/
├── unit/          # Fast, isolated tests
├── integration/   # Service integration tests
└── e2e/           # Full workflow tests

## Fixtures
Fixtures in `tests/fixtures/`. Load with:
```typescript
import { loadFixture } from '@/tests/helpers'
const user = loadFixture('user-active')
```

## Coverage Requirements
- Minimum: 80% line coverage
- New code: Must include tests
- CI fails below threshold
```

---

### architecture.md

**Purpose:** System design, key decisions, patterns

**Include:**
- High-level architecture diagram (ASCII or reference)
- Key design decisions and rationale
- Pattern catalog used in codebase
- Module boundaries and dependencies
- Data flow overview

**Template:**
```markdown
# Architecture

## Overview
[2-3 sentences describing the system]

## Key Decisions
1. **[Decision]**: [Rationale]
2. **[Decision]**: [Rationale]

## Patterns Used
- **Repository Pattern**: Data access in `src/repositories/`
- **Service Layer**: Business logic in `src/services/`
- **DTOs**: API contracts in `src/dtos/`

## Module Dependencies
```
Controllers → Services → Repositories → Database
     ↓
   DTOs
```

## Boundaries
- `src/core/` - No external dependencies
- `src/infra/` - All external integrations
```

---

### database.md

**Purpose:** Data layer, schema, migrations

**Include:**
- Database technology and connection
- Schema overview (key tables/collections)
- Migration commands and workflow
- Seeding and fixtures
- Query patterns and ORM usage

**Template:**
```markdown
# Database

## Technology
PostgreSQL 15 via Prisma ORM

## Connection
- Dev: `DATABASE_URL` in `.env`
- Prod: Managed via infrastructure

## Schema Overview
Key tables:
- `users` - User accounts
- `orders` - Order records
- `products` - Product catalog

Full schema: `prisma/schema.prisma`

## Migrations
- Generate: `npx prisma migrate dev --name [name]`
- Apply: `npx prisma migrate deploy`
- Reset: `npx prisma migrate reset`

## Seeding
`npm run db:seed` - Loads fixtures from `prisma/seed.ts`
```

---

### deployment.md

**Purpose:** Deploy process, environments, infrastructure

**Include:**
- Deployment commands/process
- Environment list and URLs
- Infrastructure overview
- Rollback procedures
- Secrets management

**Template:**
```markdown
# Deployment

## Environments
| Env | URL | Branch |
|-----|-----|--------|
| Dev | dev.example.com | develop |
| Staging | staging.example.com | main |
| Prod | example.com | release/* |

## Deploy Commands
- Staging: `npm run deploy:staging`
- Prod: `npm run deploy:prod` (requires approval)

## Process
1. PR merged to main
2. CI runs tests
3. Auto-deploy to staging
4. Manual promotion to prod

## Rollback
`npm run rollback:prod -- --version=[tag]`

## Secrets
Managed in AWS Secrets Manager. Never commit `.env.prod`.
```

---

### api.md

**Purpose:** API design patterns, conventions

**Include:**
- API style (REST, GraphQL, etc.)
- Endpoint naming conventions
- Request/response patterns
- Authentication approach
- Error handling format

---

### security.md

**Purpose:** Security practices, auth, sensitive data

**Include:**
- Authentication mechanism
- Authorization patterns
- Sensitive data handling
- Security review process
- Known security boundaries

---

### debugging.md

**Purpose:** Debug workflows, logging, troubleshooting

**Include:**
- Logging configuration
- Debug commands and tools
- Common issues and solutions
- Performance profiling
- Error tracking integration

## When to Create Agent Docs

Create a new `agent_docs/` file when:

1. **Content is task-specific** - Only relevant for certain work
2. **Content exceeds 20 lines** - Too much for CLAUDE.md
3. **Content changes frequently** - Isolate changes
4. **Multiple related topics** - Group for discoverability

## Referencing from CLAUDE.md

Add a Reference Documentation section:

```markdown
## Reference Documentation
When working on specific tasks, read relevant files:
- `agent_docs/building.md` - Build process and compilation
- `agent_docs/testing.md` - Test patterns and fixtures
- `agent_docs/architecture.md` - System design decisions
- `agent_docs/database.md` - Prisma schema and migrations
- `agent_docs/deployment.md` - Deploy to staging/production
```

Claude will read these files when the task context matches.

```

### references/anti-patterns.md

```markdown
# Anti-Patterns Guide

What NOT to include in CLAUDE.md and why.

## The Core Problem

CLAUDE.md content goes into every session. LLMs have limited instruction-following capacity:

- **~150-200 instructions** for frontier thinking models
- **Fewer** for smaller or non-thinking models
- **Peripheral bias** - Beginning/end of prompt get priority

Every unnecessary line in CLAUDE.md:
1. Consumes instruction budget
2. Dilutes important instructions
3. Increases chance of being ignored

## Anti-Pattern Catalog

### 1. Code Style Rules

**Bad:**
```markdown
## Code Style
- Use 2-space indentation
- Use single quotes for strings
- Add trailing commas in arrays
- Use arrow functions over function declarations
- Prefer const over let
- No semicolons
```

**Why it's bad:**
- Linters do this faster and cheaper
- Adds 6+ instructions Claude may ignore
- Gets stale when config changes

**What to do instead:**
```markdown
## Development
Lint: `npm run lint` (auto-fixes on save)
```

Configure ESLint, Prettier, Black, etc. properly. Claude will follow existing code patterns through in-context learning.

---

### 2. Comprehensive Command Documentation

**Bad:**
```markdown
## Commands

### Development
- `npm run dev` - Start development server with hot reload on port 3000
- `npm run dev:debug` - Start with Node inspector on port 9229
- `npm run dev:mock` - Start with mock API responses

### Building
- `npm run build` - Production build to dist/
- `npm run build:dev` - Development build with source maps
- `npm run build:analyze` - Build with bundle analyzer
- `npm run build:docker` - Build Docker image

### Testing
- `npm test` - Run all tests
- `npm run test:unit` - Unit tests only
- `npm run test:e2e` - End-to-end tests
- `npm run test:watch` - Watch mode
- `npm run test:coverage` - With coverage report

[...20 more commands...]
```

**Why it's bad:**
- Bloats CLAUDE.md by 30+ lines
- Most commands won't be used in a session
- Package.json already documents this

**What to do instead:**

In CLAUDE.md (~4 lines):
```markdown
## Development
Build: `npm run build`
Test: `npm test`
Dev: `npm run dev`
```

In `agent_docs/building.md` (full documentation):
```markdown
[Complete command reference here]
```

---

### 3. Implementation Examples

**Bad:**
```markdown
## API Pattern
When creating new endpoints, follow this pattern:

```typescript
// src/routes/example.ts
import { Router } from 'express'
import { validateRequest } from '@/middleware/validation'
import { exampleSchema } from '@/schemas/example'
import { ExampleService } from '@/services/example'

const router = Router()

router.post('/',
  validateRequest(exampleSchema),
  async (req, res) => {
    const service = new ExampleService()
    const result = await service.create(req.body)
    res.status(201).json(result)
  }
)

export default router
```
```

**Why it's bad:**
- 20+ lines of code in system prompt
- Gets stale when patterns change
- Existing code shows the pattern better

**What to do instead:**
```markdown
## Critical Rules
- Follow existing patterns in src/routes/
```

Claude learns from your actual code through in-context learning.

---

### 4. Generated /init Content

**Bad:**
Using the raw output from `claude /init`:
```markdown
# Project

This is a TypeScript project using Node.js.

## Files
- package.json: Contains dependencies
- tsconfig.json: TypeScript configuration
- src/: Source files
- tests/: Test files

## Scripts
See package.json for available scripts.
```

**Why it's bad:**
- Generic, not project-specific
- States obvious facts
- Provides no real guidance

**What to do instead:**
Hand-craft your CLAUDE.md. Every line should be:
- **Non-obvious** - Claude wouldn't know without it
- **Actionable** - Affects how Claude works
- **Universal** - Relevant to every session

---

### 5. Excessive Critical Rules

**Bad:**
```markdown
## Rules
1. Use TypeScript for all new files
2. Follow ESLint configuration
3. Write tests for new functionality
4. Use meaningful variable names
5. Add JSDoc comments to public functions
6. Keep functions under 50 lines
7. Use async/await over promises
8. Handle all errors appropriately
9. Log important operations
10. Validate all user input
11. Never commit secrets
12. Follow REST conventions
13. Use proper HTTP status codes
14. Document API changes in OpenAPI
15. Update changelog for features
```

**Why it's bad:**
- 15 rules compete for attention
- Many are obvious or covered by linters
- Violates the ~150 instruction limit principle

**What to do instead:**
```markdown
## Critical Rules
- Never modify files in `legacy/` - deprecated code
- All API changes require OpenAPI spec update first
- Run `npm test` before pushing
```

2-3 rules that are:
- Non-obvious
- Specific to this project
- Have real consequences if violated

---

### 6. Team/Process Information

**Bad:**
```markdown
## Team
- Frontend: @alice, @bob
- Backend: @charlie, @diana
- DevOps: @eve

## Process
1. Create feature branch from develop
2. Open draft PR when starting
3. Request review from 2 team members
4. Squash merge when approved
5. Delete branch after merge

## Meetings
- Standup: Daily 9am
- Sprint planning: Monday 10am
- Retro: Friday 3pm
```

**Why it's bad:**
- Irrelevant to Claude's work
- Takes up instruction budget
- Human process, not AI context

**What to do instead:**
Don't include this in CLAUDE.md. It's for humans, not agents.

---

### 7. Project History/Roadmap

**Bad:**
```markdown
## History
This project started in 2019 as a hackathon prototype...

## Roadmap
- Q1: Mobile app launch
- Q2: International expansion
- Q3: Enterprise features
```

**Why it's bad:**
- Narrative text wastes tokens
- Future plans don't help current coding
- Gets stale

**What to do instead:**
Focus on present-state, actionable information only.

---

## Quick Audit Checklist

Run this audit on your CLAUDE.md:

| Check | Action |
|-------|--------|
| Line count > 100? | Trim or move to agent_docs/ |
| Code style rules? | Delete, use linters |
| Command list > 5? | Move to agent_docs/building.md |
| Code examples? | Delete, point to actual code |
| Generated by /init? | Rewrite from scratch |
| > 5 rules? | Reduce to 2-3 critical ones |
| Team/process info? | Delete |
| History/roadmap? | Delete |
| Tutorial-style prose? | Convert to bullets |

## The Litmus Test

For every line in CLAUDE.md, ask:

1. **Is this universal?** - Applies to every session, not just some tasks
2. **Is this non-obvious?** - Claude wouldn't know without it
3. **Is this actionable?** - Changes how Claude works
4. **Is this current?** - Won't become stale

If any answer is "no," remove it or move it to `agent_docs/`.

```