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.

OpenClaw Optimised

AI Skill Market Insights

Be Part of the 0+ Developer Community

CLAUDE.md Optimization Guide

Core Principle: Less Is More

What to Include

Essential (High Value)

Include Only If Non-Standard

Do NOT Include

Structure

Commands

Code Style

Architecture

IMPORTANT

Formatting Rules

File Placement

Optimization Checklist

Maintenance

Anti-Patterns

Example: Minimal Effective CLAUDE.md

Commands

Style

IMPORTANT

Quick Start

Manual Installation

TEAR & SHARE

Tags

document-release

中文去AI味

Copy Editing

Essence Distiller

文件总结 File Summary & Analysis

Channels

Learn

Compare

Company