๐Ÿ“

CLAUDE.md Writing Guide โ€” Order Optimization & Best Practices

Claude Code

Stable content on top, frequently changing content at bottom โ€” Prompt caching optimization

CLAUDE.md is the most important file for Claude Code to understand your project. It's automatically loaded at the start of every session, and Claude follows the rules written here.

Most Important Principle: Placement Order

Put stable content on top, frequently changing content at the bottom. The reason is prompt caching.

Claude Code caches system prompts, and caching is only valid for the matching portion from the beginning. If the front of the file changes, the entire cache is invalidated. So putting content that never changes (project description, coding rules) at the very top increases cache hit rates, while content that changes every time (current work context) should go at the very bottom so it doesn't affect the cache.

Recommended Order

  1. Project Description โ€” name, tech stack, purpose (rarely changes โ†’ cache hit)
  2. Coding Rules โ€” conventions, prohibitions, style (additions happen but existing content stays โ†’ cache hit)
  3. Architecture Decisions โ€” DB, auth, routing patterns (occasional changes โ†’ occasional cache miss)
  4. Current Work Context โ€” ongoing tasks, temp notes (frequent changes โ†’ cache miss, but at bottom so no impact on above cache)

Rule File Separation

Split topic-specific .md files into .claude/rules/ directory to keep the main CLAUDE.md clean. Rule files are auto-loaded alongside CLAUDE.md.

3 Levels of CLAUDE.md

  • ~/.claude/CLAUDE.md โ€” personal global rules (all projects)

  • project-root/CLAUDE.md โ€” project rules (Git committed, team shared)

  • .claude/rules/*.md โ€” topic-specific split rules (Git committed)

Prompt Caching and Placement Order

Claude Code includes CLAUDE.md in the system prompt and caches from the beginning. If the front matches the previous session โ†’ cache hit โ†’ faster and cheaper.

Cache Hit ✓ Project description (rarely changes)
Cache Hit ✓ Coding rules (only additions)
Occasional Miss Architecture decisions (on design changes)
Cache Miss ✗ Current work context (changes every time, but at bottom so no impact above)

Key: Caching is valid only for the matching portion from the beginning. Putting changing content at the top invalidates the entire cache.

3 Levels of CLAUDE.md

Level Location Scope Git
Personal Global ~/.claude/CLAUDE.md All my projects Untracked
Project project-root/CLAUDE.md Entire project (team shared) Committed
Topic-specific .claude/rules/*.md Project (topic separated) Committed

Writing Tips

✓

Be specific โ€” "Use Rails 8 enum syntax (attribute + enum :status)" beats "write clean code"

✓

Include reasons with prohibitions โ€” "No jsonb (SQLite unsupported)" is followed better than just "No jsonb"

✓

Include code examples โ€” adding code blocks alongside instructions dramatically improves accuracy

✗

Don't document what code shows โ€” file structure, git history, variable names โ€” Claude can read these directly

How to Use

1

Create CLAUDE.md at project root โ†’ write in stability order (project desc โ†’ coding rules โ†’ architecture โ†’ current work)

2

When rules grow, split into topic-specific .md files in .claude/rules/

3

Set personal global rules in ~/.claude/CLAUDE.md (applies to all projects)

4

Always place frequently changing content (current tasks, temp notes) at the very bottom

Tags

#CLAUDE.md #rules #context #convention #project #caching #optimization

Source

Anthropic Docs

← โš™๏ธ settings.json Management โš– Commands vs Skills Complete Comparison →