OpenClaw 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

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

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

~15 lines. Covers what Claude can't infer. Nothing more.