diegosouzapw 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 attentionCRITICAL:- Rules that must never be violatedNEVER:- Absolute prohibitionsALWAYS:- 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
- Observe - Notice when Claude doesn't follow instructions
- Strengthen - Add emphasis markers (IMPORTANT, NEVER)
- Simplify - Remove content Claude doesn't reference
- 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)