Skip to main content

Anthropic Claude Best Practices

Anthropic Claude Best Practices

Research Date: December 3, 2025 Purpose: Comprehensive analysis of Anthropic's official best practices for Claude Code projects Sources: 25+ official Anthropic sources, engineering blogs, and documentation

Executive Summary​

Claude.md is a special Markdown file that Claude Code automatically loads into every conversation, serving as a persistent configuration layer for project-specific context.

Critical Findings​

  1. Keep It Minimal: Under 300 lines (ideally under 100). Claude.md prepends to every prompt, consuming tokens and potentially introducing noise.

  2. Progressive Disclosure Architecture: Don't dump all information upfront. Use Claude.md to point to additional resources that Claude loads on-demand.

  3. Focus on Universal Content: Include only instructions that apply to every task. Task-specific guidance belongs in separate files or custom slash commands.

  4. Iterative Refinement: Treat Claude.md like a frequently-used prompt. Test what improves instruction-following rather than adding everything possible.

  5. Three-Tier Memory Hierarchy:

    • User-level (~/.claude/CLAUDE.md) - Personal preferences across all projects
    • Project-level (.claude/CLAUDE.md) - Team-shared conventions
    • Local project-level (.claude/CLAUDE.local.md) - Individual overrides

Performance Impact​

Research from Anthropic engineering indicates:

  • Frontier LLMs can follow ~150-200 instructions with reasonable consistency
  • Claude Code's system prompt already contains ~50 instructions
  • Bloated Claude.md files reduce performance and distract Claude
  • Each line costs tokens on every conversation turn

1. Official Anthropic Guidance​

1.1 What is Claude.md?​

From Anthropic's official documentation:

"Claude.md is a special file that Claude automatically incorporates into conversation context. Think of it as a configuration file that Claude automatically incorporates into every conversation."

Purpose​

  • Persistent project-specific context
  • Repository etiquette and conventions
  • Developer environment setup instructions
  • Frequently used commands
  • Architectural patterns and warnings

1.2 File Discovery Mechanism​

Hierarchical Loading (Cascading Order)​

Claude Code reads Claude.md files recursively: starting in the current working directory, it traverses up to (but not including) the root directory, reading all Claude.md or Claude.local.md files found.

File Locations (Priority Order)​

  1. Home directory: ~/.claude/CLAUDE.md - Universal preferences
  2. Parent directories: Support for monorepo setups
  3. Project root: .claude/CLAUDE.md - Team-shared (committed)
  4. Project root: .claude/CLAUDE.local.md - Personal (gitignored)
  5. Child directories: Loaded on-demand when Claude accesses those files

Multiple File Behavior​

"Claude.md files can be hierarchical, so you can have one project-level and one in nested directories, with Claude looking at them all and prioritizing the most specific, the most nested when relevant."

2.1 Essential Sections​

Minimum Viable Claude.md​

## Project Summary
[1-2 sentence description]

## Tech Stack
- [Language/Framework with version]
- [Key libraries]

## Key Directories
- `src/` - [purpose]
- `tests/` - [purpose]
- `docs/` - [purpose]

## Common Commands
- Build: `[command]`
- Test: `[command]`
- Lint: `[command]`
- Dev server: `[command]`

## Standards
- [Critical coding standards]
- [Type requirements]
- [Style guidelines reference]

2.2 Advanced Sections (When Needed)​

For Complex Projects​

  1. Architectural Patterns

    • Domain-driven design approach
    • Microservices boundaries
    • Non-standard architecture choices
    • Why specific patterns were chosen

  2. Team Conventions

    • Branch naming schemes
    • Commit message format
    • Code review requirements
    • PR templates

  3. Custom Tools & MCP Servers

    • Available MCP servers with usage examples
    • Custom tooling configurations
    • Non-standard development tools

  4. Workflows

    • Step-by-step process for new features
    • Bug fix workflow
    • Code review process
    • Deployment checklist

  5. Critical Warnings

    • Rate limits for external services
    • Performance-sensitive code regions
    • Security considerations
    • Known gotchas or edge cases

3. Content Guidelines​

3.1 What to Include​

✅ DO Include:

  • Build/run commands with examples
  • Testing procedures and framework details
  • Key architectural decisions
  • Team-specific conventions
  • Critical warnings about code regions
  • Rate limits for external services
  • Frequently used bash commands with descriptions
  • Core files and utility functions
  • Repository etiquette (branching, merge strategies)
  • Developer environment setup requirements
  • Project-specific quirks or warnings

3.2 What to Exclude​

❌ DON'T Include:

  1. Code Style Guidelines - Use linters instead

    "Never send an LLM to do a linter's job - LLMs are comparably expensive and incredibly slow compared to traditional linters."

  2. Sensitive Data

    • API keys, credentials, or security vulnerabilities
    • Especially important if version-controlled

  3. Task-Specific Instructions

    • Instructions that don't apply to every task
    • Use separate markdown files or custom commands instead

  4. Documentation File @-mentions

    "Don't @-mention documentation files in your Claude.md as this bloats the context window by embedding the entire file on every run."

  5. Excessive Content Without Testing

    "A common mistake is adding extensive content without iterating on its effectiveness."

  6. Long Narrative Paragraphs

    "You're writing for Claude, not onboarding a junior dev - use short, declarative bullet points and don't write long, narrative paragraphs."

  7. Theoretical Guidance

    • Information exceeding practical utility
    • Unrelated project documentation
    • "Best practices" that don't match your actual workflow

4. Token Efficiency & Context Management​

4.1 Progressive Disclosure Pattern​

Core Principle from Anthropic Engineering​

"Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable."

Implementation Strategy​

Instead of dumping all information into Claude.md, use it to reference additional resources:

## Additional Documentation

For specific tasks, refer to:
- `docs/frontend-development.md` - Component patterns
- `docs/api-integration.md` - Backend integration guide
- `docs/testing-strategy.md` - Test writing guidelines

Claude will read these files when working on related tasks.

4.2 Three-Tier Architecture​

From Agent Skills Research​

  1. Metadata Layer (Always Loaded) - Claude.md basics
  2. Full Content Layer (Conditionally Loaded) - Referenced docs
  3. Referenced Files (As-Needed) - Deep documentation

Benefits​

  • Minimal token consumption baseline
  • Unbounded context potential
  • Focused information retrieval

4.3 Context Window Management​

Official Best Practices​

  1. Use /clear Command Frequently

    "During long sessions, Claude's context window can fill with irrelevant conversation, file contents, and commands, which can reduce performance and distract Claude. Use the /clear command frequently between tasks to reset the context window."

  2. Avoid Final 20% for Complex Tasks

    "Avoid using the final 20% of your context window for complex tasks, as performance degrades significantly when approaching limits."

  3. Leverage Subagents

    "For complex problems, consider strong use of subagents, especially early on in a conversation or task."

  4. Structured State Files

    • Use claude-progress.txt for session notes
    • Use feature_list.json for structured data
    • Use tests.json for test status tracking
    • Git history provides recoverable checkpoints

5. Multi-Session Continuity Patterns​

5.1 Long-Running Agent Architecture​

From "Effective Harnesses for Long-Running Agents"​

Anthropic's two-agent solution for multi-session continuity:

Components​

  1. Initializer Agent - First-run setup
  2. Coding Agent - Subsequent sessions with identical system prompt/tools

State Files​

  • claude-progress.txt - Chronological work log
  • feature_list.json - Feature status (use JSON, not Markdown)
  • init.sh - Environment setup script
  • Git history - Recoverable checkpoints

Why JSON for Feature Lists​

"The model is less likely to inappropriately change or overwrite JSON files compared to Markdown files."

5.2 Session Continuity Strategies​

Opening Ritual (Every Session)​

  1. Verify working directory
  2. Read progress notes
  3. Examine feature list
  4. Check git logs
  5. Launch development server
  6. Run baseline tests

Incremental Work Discipline​

  • Focus on single features per session
  • Prevents context exhaustion mid-feature
  • Clear handoff points between sessions

Clean State Requirements​

  • Conclude with git commits
  • Update progress files
  • Enable rollback if needed
  • Mimic professional developer practices

6. Do's and Don'ts​

6.1 Do's​

✅ DO: Keep Files Minimal

  • Under 300 lines total
  • Under 100 lines ideally
  • Every line should solve a real problem

✅ DO: Use Progressive Disclosure

  • Reference additional docs in Claude.md
  • Let Claude load detailed content on-demand
  • Organize related docs in subdirectories

✅ DO: Iterate and Test

  • Treat Claude.md like a frequently-used prompt
  • Test what actually improves instruction-following
  • Remove content that doesn't help

✅ DO: Use # Key for Dynamic Updates

"Press the # key during sessions to have Claude automatically incorporate instructions into the relevant Claude.md file."

✅ DO: Check into Version Control

  • Share .claude/CLAUDE.md with team
  • Maintain consistency across team members
  • Document architectural patterns everyone should follow

✅ DO: Use Claude.local.md for Personal Preferences

  • Add to .gitignore
  • Keep personal/experimental instructions separate
  • Avoid cluttering shared documentation

6.2 Don'ts​

❌ DON'T: Stuff Everything Possible

"Don't stuff every possible command into the file—you will get sub-optimal results."

❌ DON'T: Use /init Without Review

"Don't auto-generate with /init—it's the highest leverage point of the harness."

❌ DON'T: Include Code Style in Claude.md

  • Use linters (Ruff, ESLint, etc.)
  • Use formatters (Black, Prettier, etc.)
  • Use hooks for automatic formatting

❌ DON'T: @-Mention Documentation Files

  • Bloats context window
  • Embeds entire files on every run
  • Use references instead

❌ DON'T: Add Theoretical Content

  • Focus on actual workflow
  • Solve real problems encountered
  • Skip "best practices" that don't apply

7. Source Bibliography​

Official Anthropic Sources​

  1. Claude Code Overview
  2. Claude Code Settings
  3. Common Workflows
  4. Claude Code Best Practices
  5. Effective Harnesses for Long-Running Agents
  6. Effective Context Engineering for AI Agents
  7. Equipping Agents with Agent Skills
  8. anthropics/anthropic-quickstarts
  9. anthropics/Claude-code

Community Sources​

  1. Writing a Good Claude.md
  2. Apidog: Claude.md Best Practices
  3. Managing Claude Code's Context

Conclusion​

Anthropic's official guidance emphasizes minimalism, progressive disclosure, and iterative refinement for Claude.md files.

Key Takeaways​

  1. Shorter is better - Under 300 lines total, under 100 lines ideal
  2. Progressive disclosure works - Reference external docs instead of embedding everything
  3. Iteration is critical - Test what improves instruction-following
  4. Frontier LLMs have limits - ~150-200 instructions max with reasonable consistency
  5. Token efficiency matters - Claude.md prepends to every prompt

"Your Claude.md file should contain as few instructions as possible - ideally only ones which are universally applicable to your task, as instruction-following quality decreases uniformly as instruction count increases."

Research Compiled By: AI Research Agent Date: December 3, 2025 Confidence Level: High (based on multiple corroborating official sources)