claudemd

CLAUDE.md Best Practices

Deep, opinionated writing on how to structure high-performance rules, keep context windows small, and configure robust CLI commands for Claude Code.

The Golden Rule: Treat Claude Like an Experienced Peer

Do not waste context space writing paragraphs of introductory explanations. State guidelines as direct instructions. Ensure commands are exact and whitelists are precise. Claude Code is a terminal tool — it expects logic, not prose.

1. File Size and Length Recommendations

Keep your CLAUDE.md under 150 lines of markdown (maximum 300 lines for massive repositories). Every line of rules you add is appended to the system prompt of every single message turn inside the terminal CLI.

If your rule file is excessively long, it:

  • Increases API Latency: The model has to parse more rules before replying.
  • Depletes Tokens: Costs accumulate much faster during long sessions.
  • Dilutes Rule Priority: The LLM might overlook critical rules if buried under paragraphs of minor styling advice.

2. What to Include — The Vital Pieces

Your configuration file should prioritize developer workflows. Focus heavily on these three components:

Commands Map

Exact CLI lines for building, testing single files, running checks, and running linters.

Architecture Rules

State design patterns, directory hierarchies, and file naming rules clearly.

Critical Excludes

Specify folders that should not be touched, read, or modified (e.g. database migrations).

3. What to Skip

Keep these details out of your CLAUDE.md files to preserve context space:

  • General Language Rules: Claude is already highly proficient in TypeScript, Python, and C#. You do not need to tell it "Use arrays in TypeScript" or "Write comments in code."
  • Git Guidelines: Claude Code handles committing and merging using standard Git conventions. Keep git messaging formatting rules in your global config, not inside the project file.
  • Third-party installation instructions: Skip links to external documentation or lengthy explanations of library APIs.

4. Command Pattern Optimization

Provide commands that can execute without human interaction. Avoid commands that launch interactive dashboards or require user input:

Avoid (Interactive)
- Test: `npm run test:watch`
Prefer (Non-Interactive / Single Run)
- Test: `npm test`
- Test single file: `npm test -- [filename]`

5. Common Mistakes to Avoid

  1. Providing outdated commands: If the test command is deprecated, Claude Code will run it, fail, and waste context trying to fix the test suite instead of working on the requested feature.
  2. Conflicting guidelines: Ensure there are no contradictions between your local CLAUDE.md and the global rules stored at ~/.claude/CLAUDE.md.
  3. Writing rules for multiple frameworks in a single file: If your repository is a monorepo containing both a C# backend and a React frontend, split the configurations using subdirectory-level CLAUDE.md files.