e02eb28e98
Plugin:skill pairs now read as noun:verb commands instead of repeating the plugin name. Also added concise descriptions to all SKILL.md frontmatter. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
126 lines
3.2 KiB
Markdown
126 lines
3.2 KiB
Markdown
---
|
|
name: review
|
|
description: Review and optimize CLAUDE.md files for maximum Claude Code performance
|
|
---
|
|
|
|
# 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 project memory |
|
|
|
|
## Optimization Checklist
|
|
|
|
Before finalizing:
|
|
- [ ] Under 50 lines? (ideal target)
|
|
- [ ] Every line solves a real problem you've encountered?
|
|
- [ ] No redundancy with other CLAUDE.md locations?
|
|
- [ ] No instructions Claude follows by default?
|
|
- [ ] Tested by observing if Claude's behavior changes?
|
|
|
|
## Maintenance
|
|
|
|
- Run `/init` as starting point, then prune aggressively
|
|
- Every few weeks: "Review this CLAUDE.md and suggest removals"
|
|
- When Claude misbehaves: add specific rule
|
|
- When Claude ignores rules: file too long, prune other content
|
|
|
|
## Anti-Patterns
|
|
|
|
| Don't | Why |
|
|
|-------|-----|
|
|
| 200+ line CLAUDE.md | Gets ignored |
|
|
| "Write clean code" | Claude knows this |
|
|
| Duplicate rules across files | Wastes tokens, conflicts |
|
|
| Theoretical concerns | Only add for real problems |
|
|
| Long prose explanations | Use bullet points |
|
|
|
|
## Example: Minimal Effective CLAUDE.md
|
|
|
|
```markdown
|
|
# MyApp
|
|
|
|
React Native app with Expo. Backend is Supabase.
|
|
|
|
## Commands
|
|
- `pnpm test` - run tests
|
|
- `pnpm ios` - run iOS simulator
|
|
|
|
## Style
|
|
- Prefer Zustand over Context
|
|
- Use `clsx` for conditional classes
|
|
|
|
## IMPORTANT
|
|
- NEVER commit .env files
|
|
- Auth logic lives in src/lib/auth.ts only
|
|
```
|