CLAUDE.md Writing Guidelines

Guidelines for writing effective CLAUDE.md files, based on Anthropic's official best practices.

Purpose of CLAUDE.md

CLAUDE.md is automatically pulled into context. Document:

• Common bash commands - Build, test, lint, deploy
• Core files and utilities - Key files Claude should know
• Code style guidelines - Formatting, patterns, conventions
• Testing instructions - How to run tests, patterns
• Repository etiquette - Branch naming, PR conventions
• Unexpected behaviors - Known gotchas, things that cause problems

Core Principles

1. Keep It Concise

"You're writing for Claude, not onboarding a junior dev."

CLAUDE.md consumes tokens on every prompt. Every line should earn its place.

DO:

• Write for Claude, not humans
• Use bullet points and tables over prose
• Link to detailed docs instead of duplicating
• Regularly audit and remove outdated content

DON'T:

• Include verbose explanations
• Duplicate information from code/comments
• Add documentation that's rarely referenced
• Include Table of Contents (Claude doesn't need navigation)

2. Use Emphasis Markers

Claude follows instructions better with explicit emphasis:

• IMPORTANT:

  - Rules that need attention

• CRITICAL:

  - Rules that must never be violated

• NEVER:

  - Absolute prohibitions

• ALWAYS:

  - Absolute requirements

3. Use Tables for Quick Reference

Tables are scannable and token-efficient:

| Client Context | Import From | Notes |
|----------------|-------------|-------|
| Server Components | `@/lib/server` | Must await |
| Client Components | `@/lib/client` | No await |

4. Use DO/DON'T Examples

// DON'T: Use raw color values
<p className="text-gray-500">Text</p>

// DO: Use semantic tokens
<p className="text-muted">Text</p>

5. Create a "Danger Zone" Section

Group actions that cause problems:

## Danger Zone

| Action | Consequence |
|--------|-------------|
| `npm run dev` automatically | Dev server already running |
| `as any` casts | Defeats TypeScript |

Structure Recommendation

# CLAUDE.md

## Project Overview
## Quick Start
## Architecture
## Danger Zone
## Critical Rules
## Common Patterns
## Environment Setup
## Troubleshooting
## Additional Documentation

What to Include vs. Link

Include Directly

• Commands Claude runs frequently
• Critical rules that must never be violated
• Quick reference tables
• Brief DO/DON'T examples
• Danger Zone items

Link to External Docs

• Detailed setup guides
• Comprehensive code examples
• Full API documentation
• Any content > 50 lines on a single topic

Anti-Patterns to Avoid

Verbose Explanations

# Too verbose
The middleware handles authentication by using the server-side
utilities. It's critically important that you understand...

# Concise
**Middleware:** Return exact response from `updateSession()`.

Table of Contents

Claude doesn't need navigation aids. ToCs waste tokens.

Obvious Instructions

# Claude already knows this
Use proper types. Write clean code.

# Project-specific
Use `Tables<'table_name'>` helpers, never verbose syntax.

Duplicated Rules

Audit for rules stated multiple times. Consolidate into one location.

Modular Rules Architecture

For larger projects, use modular rules in

.claude/rules/

:

# CLAUDE.md (lean hub)

## Rules Reference

| Rule File | Contents |
|-----------|----------|
| `architecture.md` | Route structure, data flow |
| `patterns.md` | Common code patterns |
| `danger-zone.md` | All "never do" rules |

Benefits:

• Agents can include specific rule bundles
• Easier maintenance
• Reduces main CLAUDE.md size

Tuning Your CLAUDE.md

Iterate Like a Prompt

1. Observe - Notice when Claude doesn't follow instructions
2. Strengthen - Add emphasis markers (IMPORTANT, NEVER)
3. Simplify - Remove content Claude doesn't reference
4. Test - Try different phrasings

Regular Audits

• Remove rules Claude consistently follows without prompting
• Strengthen rules Claude frequently ignores
• Update after major codebase changes
• Remove references to deleted files/patterns

Review Checklist

• Can each section be shorter?
• Is every instruction necessary?
• Are critical rules emphasized?
• Is verbose content moved to linked docs?
• Are there redundant sections?
• Is there a Table of Contents? (Remove it)

Resources

• Anthropic's Claude Code Best Practices
• CLAUDE.md Optimization - Arize