# CLAUDE.md Best Practices - Research Notes > Comprehensive synthesis of CLAUDE.md best practices from multiple authoritative sources including official Anthropic documentation, practitioner blogs, and community resources. --- ## Executive Summary CLAUDE.md is Claude Code's memory file—the primary mechanism for giving Claude persistent context about your project. Since LLMs are stateless, this file is your sole onboarding mechanism for every conversation. ### The Golden Rule: Conciseness **Target: Under 300 lines** (ideally under 100 for most projects). Every instruction consumes tokens and competes for attention. > "Frontier LLMs reliably follow 150-200 instructions. Since Claude Code's system prompt contains ~50 instructions, your CLAUDE.md should contain far fewer than 75 instructions to remain effective." > — [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) --- ## 1. Core Principles ### 1.1 Universal Applicability Only include instructions that apply to **most sessions**. Claude Code injects a system reminder that context "may or may not be relevant"—non-universal instructions get mentally filtered out. ### 1.2 Progressive Disclosure > "Keep your CLAUDE.md concise and universally applicable. Use Progressive Disclosure - don't tell Claude all the information you could possibly want it to know. Rather, tell it how to find important information so that it can find and use it, but only when it needs to." > — [Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-best-practices) Instead of stuffing everything into CLAUDE.md, create an `agent_docs/` or `docs/` directory with focused files and reference them. ### 1.3 The WHY-WHAT-HOW Framework **WHAT**: Project structure, tech stack, directory map **WHY**: Purpose and function of components **HOW**: Practical workflows—build commands, testing, verification --- ## 2. File Locations & Hierarchy | Location | Scope | Sharing | |----------|-------|---------| | `./CLAUDE.md` or `./.claude/CLAUDE.md` | Project | Team (via git) | | `./.claude/rules/*.md` | Project (modular) | Team (via git) | | `./CLAUDE.local.md` | Project (personal) | Just you | | `~/.claude/CLAUDE.md` | All projects | Just you | | `~/.claude/rules/*.md` | All projects (modular) | Just you | | Enterprise locations* | Organization | All org users | *Enterprise: `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux) **Precedence**: Higher in hierarchy = loaded first. Project rules override user rules. **Memory Lookup Process**: Claude Code reads memories recursively: 1. Starting in the current working directory (cwd) 2. Recurses UP to (but not including) the root directory `/` 3. Reads all `CLAUDE.md` or `CLAUDE.local.md` files found 4. Discovers CLAUDE.md nested in subtrees (lazy loading when accessing those subtrees) Source: [Official Memory Docs](https://code.claude.com/docs/en/memory) --- ## 3. Recommended Structure ### 3.1 Essential Sections ```markdown # Project Overview Brief description of what this project does. # Tech Stack - Language/runtime versions - Key frameworks and libraries - Database/storage systems # Directory Structure src/ ├── components/ # UI components ├── services/ # Business logic └── utils/ # Shared utilities # Common Commands - `npm run dev` — Start development server - `npm test` — Run test suite - `npm run lint` — Check code style # Code Conventions - Use TypeScript strict mode - Prefer composition over inheritance - All API routes require authentication # Testing - Tests live alongside source files (*.test.ts) - Use fixtures from `__fixtures__/` directory - Integration tests require `TEST_DB_URL` env var # Important Warnings - Never commit `.env` files - The legacy `user` table is deprecated; use `accounts` ``` ### 3.2 Import Syntax CLAUDE.md supports importing other markdown files: ```markdown See @README.md for project overview. See @package.json for available commands. # Git workflow @docs/git-instructions.md # Individual Preferences (absolute paths) @~/.claude/my-project-instructions.md ``` **Import Rules:** - Both relative and absolute paths supported - Imports NOT evaluated inside code blocks - Max depth: 5 hops of recursive imports - CLAUDE.local.md files automatically added to .gitignore --- ## 4. Advanced Patterns ### 4.1 Modular Rules System (.claude/rules/) For larger projects, organize instructions using path-specific rules: ```markdown --- paths: src/api/**/*.ts --- # API Development Rules - All endpoints require input validation - Use standard error response format - Include OpenAPI documentation comments ``` **Glob Pattern Examples:** | Pattern | Matches | |---------|---------| | `**/*.ts` | All TypeScript files in any directory | | `src/**/*` | All files under `src/` directory | | `*.md` | Markdown files in the project root | | `src/**/*.{ts,tsx}` | TypeScript files with brace expansion | Rules without a `paths` field are loaded unconditionally. All `.md` files in `.claude/rules/` are automatically loaded. ### 4.2 Use Pointers, Not Snippets ```markdown # Bad - stale immediately The auth middleware looks like: ```typescript // 50 lines of code that will drift from reality ``` # Good - always current Auth middleware: src/middleware/auth.ts:45-92 ``` ### 4.3 Symlinks Support Symlinks are fully supported and resolved: ```bash # Symlink a shared rules directory ln -s ~/shared-claude-rules .claude/rules/shared # Symlink individual rule files ln -s ~/company-standards/security.md .claude/rules/security.md ``` Circular symlinks are detected and handled gracefully. --- ## 5. Anti-Patterns to Avoid ### 5.1 Never Use CLAUDE.md as a Linter > "Never send an LLM to do a linter's job. LLMs are comparably expensive and incredibly slow compared to traditional linters and formatters." > — [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) **Instead**: Use hooks to run formatters automatically, or create slash commands. ### 5.2 Avoid Auto-Generated CLAUDE.md `/init` is a starting point, not a finished product. CLAUDE.md has compounding leverage—poor instructions multiply through planning, research, and code generation phases. Manual curation ensures quality at the highest-leverage point. ### 5.3 Don't Over-Specify ```markdown # Bad - verbose, low signal When writing code, always make sure to follow best practices for clean code. This includes using meaningful variable names, keeping functions small and focused, and writing comments where the code isn't self-explanatory... # Good - specific, actionable - Max function length: 50 lines - Variable names: camelCase - Comments only for "why", not "what" ``` ### 5.4 Use Positive Alternatives, Not Negative Constraints ```markdown # Bad - Never use var - Don't use any type - Never commit secrets # Better - Use const/let (not var) - Use explicit types (not any) - Secrets: use environment variables, never hardcode ``` ### 5.5 Don't Include Sensitive Information Never put in CLAUDE.md: - API keys or credentials - Database connection strings - Detailed security vulnerability information - Internal URLs or IP addresses (if confidential) ### 5.6 Avoid Irrelevant Instructions **Relevance Requirement**: Claude Code injects a system reminder stating the context "may or may not be relevant" and instructs Claude to ignore irrelevant material. Non-universally-applicable instructions get filtered out, so bloat actively harms performance. **Anti-Pattern Example**: Including database schema design instructions when you're working on unrelated features wastes context and causes Claude to deprioritize all instructions uniformly. --- ## 6. Instruction Management ### 6.1 Quantity Limits Research indicates frontier LLMs reliably follow 150-200 instructions. Since Claude Code's system prompt contains ~50 instructions, your CLAUDE.md should contain far fewer than 75 instructions to remain effective. Smaller models degrade exponentially with instruction count. ### 6.2 The 13KB Rule One practitioner maintains a 13KB CLAUDE.md for a large monorepo—but emphasizes that every line earned its place through real workflow friction, not theoretical completeness. > "Document only tools used by ~30% or more of engineers." > — [Shrivu Shankar](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) If a tool needs CLAUDE.md documentation but few people use it, that's a signal to simplify your tooling. ### 6.3 Be Specific, Not Generic | Poor | Good | |------|------| | "Format code properly" | "Use 2-space indentation" | | "Follow best practices" | "Prefer composition over inheritance" | | "Test your code" | "Run `npm test` before committing" | --- ## 7. Iteration & Maintenance ### 7.1 Treat It Like a Prompt > "CLAUDE.md files become part of Claude's prompts, so they should be refined like any frequently used prompt." > — [Anthropic Engineering Blog](https://www.anthropic.com/engineering/claude-code-best-practices) A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model. ### 7.2 Adding Instructions Interactively - Press `#` during sessions to have Claude incorporate new instructions - Use `/memory` to open the file in your editor - Review session logs in `~/.claude/projects/` to identify common issues ### 7.3 Emphasis Markers When instructions must be followed strictly: ```markdown IMPORTANT: Always run tests before committing. CRITICAL: Never force-push to main. YOU MUST: Check for existing patterns in the codebase first. ``` At Anthropic, engineers occasionally run CLAUDE.md files through the [prompt improver](https://docs.anthropic.com/en/docs/build-with-claude/prompt-engineering/prompt-improver) and add emphasis markers to improve adherence. ### 7.4 In-Context Learning > "LLMs are in-context learners. If your codebase follows consistent patterns, Claude will naturally adopt them from code examples without explicit style rules." > — [HumanLayer Blog](https://www.humanlayer.dev/blog/writing-a-good-claude-md) --- ## 8. Context Management ### 8.1 Monitor Token Usage Run `/context` mid-session to understand consumption. Fresh monorepo sessions cost ~20k tokens baseline (10%), leaving 180k for actual work. ### 8.2 Session Management Strategies 1. **`/clear`** — Reset context, preserving CLAUDE.md 2. **Document & Clear** — Export progress to markdown, clear, resume fresh 3. **Avoid `/compact`** — Opaque, can lose important context ### 8.3 Context Gathering Cost Context gathering consumes time and tokens. CLAUDE.md optimization is valuable for reducing processing overhead while maintaining comprehensive guidance. --- ## 9. Team Considerations ### 9.1 Shared vs Personal - **`CLAUDE.md`**: Check into git, share team conventions - **`CLAUDE.local.md`**: Personal preferences, auto-added to .gitignore ### 9.2 Monorepo Strategy ``` monorepo/ ├── CLAUDE.md # Org-wide conventions ├── packages/ │ ├── frontend/ │ │ └── CLAUDE.md # Frontend-specific rules │ └── backend/ │ └── CLAUDE.md # Backend-specific rules ``` Claude reads parent directories recursively, so nested files augment rather than replace. ### 9.3 Enterprise-Level Memory Organizations can deploy centrally managed CLAUDE.md files: 1. Create the enterprise memory file at the Enterprise policy location 2. Deploy via configuration management system (MDM, Group Policy, Ansible, etc.) --- ## 10. Optimization Research Findings From the Arize blog post on [optimizing Claude Code with prompt learning](https://arize.com/blog/claude-md-best-practices-learned-from-optimizing-claude-code-with-prompt-learning/): ### Prompt Learning Methodology Using LLM evaluations rather than scalar rewards produces "richer feedback for optimization," enabling the meta-optimizer to target actual failure modes like misunderstood APIs and edge cases. ### Two Optimization Approaches 1. **Repository-agnostic optimization**: +5.19% accuracy boost on unseen repositories 2. **Repository-specific optimization**: +10.87% accuracy improvement when training and testing on the same codebase **Key Finding**: "Tailoring code generation to specific codebases" becomes advantageous rather than problematic overfitting. All gains came from instruction optimization, not model retraining or infrastructure modifications. --- ## 11. Quick Reference Checklist ### Starting a New Project - [ ] Run `/init` as a starting point - [ ] Edit to under 100 lines - [ ] Include only universally-applicable instructions - [ ] Add common commands with descriptions - [ ] Document critical conventions (3-5 max) - [ ] Create `docs/` for detailed references ### Before Committing CLAUDE.md - [ ] Under 300 lines? - [ ] No sensitive information? - [ ] No stale code snippets? - [ ] All file references valid? - [ ] Instructions actionable and specific? ### Periodic Review - [ ] Remove unused instructions - [ ] Update changed commands - [ ] Check instruction compliance in recent sessions - [ ] Consolidate duplicate guidance --- ## 12. Sources ### Official Documentation - [Anthropic Engineering: Claude Code Best Practices](https://www.anthropic.com/engineering/claude-code-best-practices) - [Claude Code Memory Documentation](https://code.claude.com/docs/en/memory) - [Using CLAUDE.md Files - Claude Blog](https://claude.com/blog/using-claude-md-files) ### Practitioner Insights - [Writing a Good CLAUDE.md - HumanLayer](https://www.humanlayer.dev/blog/writing-a-good-claude-md) - [How I Use Every Claude Code Feature - Shrivu Shankar](https://blog.sshh.io/p/how-i-use-every-claude-code-feature) - [CLAUDE.md Best Practices - Arize](https://arize.com/blog/claude-md-best-practices-learned-from-optimizing-claude-code-with-prompt-learning/) ### Examples & Templates - [Full CLAUDE.md Sample - GitHub Gist](https://gist.github.com/scpedicini/179626cfb022452bb39eff10becb95fa) - [CLAUDE.md Templates - Claude Flow Wiki](https://github.com/ruvnet/claude-flow/wiki/CLAUDE-MD-Templates) - [Awesome Claude Code - GitHub](https://github.com/hesreallyhim/awesome-claude-code) - [Claude Code Examples - ArthurClune](https://github.com/ArthurClune/claude-md-examples) --- ## Related Files in Systems/ - [[Claude Code Best Practices]] - Official Anthropic engineering blog post on Claude Code workflows