claude-optimised

# CLAUDE.md Optimization Guide

Write CLAUDE.md files that maximize Claude's adherence and performance.

## Core Principle: Less Is More

Long CLAUDE.md = Claude ignores half of it. Critical rules get lost in noise.

**For each line ask:** "Would removing this cause Claude to make mistakes?"
- If no → delete it
- If Claude already does it correctly → delete it or convert to hook

## What to Include

### Essential (High Value)

| Section | Example |
|---------|---------|
| Project context | "Next.js e-commerce app with Stripe" (1 line) |
| Build/test commands | `npm run test`, `pnpm build` |
| Critical gotchas | "Never modify auth.ts directly" |
| Non-obvious conventions | "Use `vi` for state, not `useState`" |
| Domain terminology | "PO = Purchase Order, not Product Owner" |

### Include Only If Non-Standard

- Branch naming (if not `feature/`, `fix/`)
- Commit format (if not conventional commits)
- File boundaries (sensitive files to avoid)

### Do NOT Include

- Things Claude already knows (general coding practices)
- Obvious patterns (detectable from existing code)
- Lengthy explanations (be terse)
- Aspirational rules (only real problems you've hit)

## Structure

```markdown
# Project Name

One-line description.

## Commands
- Test: `npm test`
- Build: `npm run build`
- Lint: `npm run lint`

## Code Style
- [Only non-obvious conventions]

## Architecture
- [Brief, only if complex]

## IMPORTANT
- [Critical warnings - use sparingly]
```

## Formatting Rules

- **Bullet points** over paragraphs
- **Markdown headings** to separate modules (prevents instruction bleed)
- **Specific** over vague: "2-space indent" not "format properly"
- **IMPORTANT/YOU MUST** for critical rules (use sparingly or loses effect)

## File Placement

| Location | Scope |
|----------|-------|
| `~/.claude/CLAUDE.md` | All sessions (user prefs) |
| `./CLAUDE.md` | Project root (share via git) |
| `./subdir/CLAUDE.md` | Loaded when working in subdir |
| `.claude/rules/*.md` | Auto-loaded as...