Trim Your CLAUDE.md: Front-Loaded Token Savings

The Hidden Cost of CLAUDE.md

CLAUDE.md is injected into every single conversation as a system-level preamble. Unlike your prompts, which you control per-task, CLAUDE.md is invisible overhead — you don't see it in the chat, but you pay for every token in it, every time.

Here's the math that most developers never do: if your CLAUDE.md is 500 lines long, and each line averages 8 tokens, that is roughly 4,000 tokens injected before you type anything. Now multiply that across 20 conversations per day, and you are burning 80,000 tokens daily — just on your system prompt preamble. Over a month, that is 1.6 million tokens spent on rules you probably did not need for any given conversation.

The problem compounds because CLAUDE.md is context-agnostic. It does not know whether you are writing Python, reviewing a pull request, or debugging CSS. It sends the same 500 lines regardless. Your Python linting rules go to every TypeScript session. Your Git commit message conventions go to every CSS tweak. Every line that does not apply to the current task is pure waste.

The fix is straightforward but requires discipline: keep only the 5 to 10 rules that apply universally, and move everything else into project-specific or language-specific files that load only when relevant. The token savings are front-loaded — they compound across every single session without you having to change how you work. Think of it as reclaiming context headroom: every line removed is token budget returned for actual work. Combined with strategic compaction, the compounding effect is significant — less baseline overhead means more room before each compaction trigger.

What to Keep, What to Cut

The golden rule: if a rule does not apply to every project and every language you touch, it does not belong in your global CLAUDE.md. Move it to a project-level or language-specific rules file instead.

Keep: 5–10 Core Universal Rules

Your global CLAUDE.md should only contain rules that apply regardless of project, language, or task. These are your non-negotiables — the things you want Claude to always know.

• Communication preferences: "Reply in English. Be concise. Use active voice."
• General code style: "Prefer simple, readable code. No clever one-liners unless performance-critical."
• Tool usage patterns: "Always run tests after making changes. Never commit without explicit request."
• Git conventions: "Write commit messages in imperative mood. Keep subject under 72 characters."
• Security baseline: "Never output secrets, API keys, or credentials. Never commit .env files."
• File operation rules: "Prefer editing existing files over creating new ones. Do not create documentation files unless asked."
• Language preference: "Default to TypeScript for new projects. Use Python for scripting and data tasks."
• Documentation stance: "Write self-documenting code. Only add comments when behavior is non-obvious."

Cut: Everything Else Moves to Project Files

Here is a quick audit checklist. If you answer "yes" to any of these, the rule should leave your global CLAUDE.md:

• Language-specific rules: Python linting, TypeScript config, Rust formatting — move to .claude/rules/python.md, .claude/rules/typescript.md, etc.
• Framework-specific rules: React patterns, Django conventions, Next.js routing rules — these belong in the project repo's own CLAUDE.md or rules directory.
• Project-specific conventions: Naming conventions for a particular codebase, internal API patterns, team-specific workflow steps.
• Tool-specific configuration: Linter settings, formatter preferences, CI/CD pipeline rules — these are better enforced by actual tool config files.
• Stale or aspirational rules: "Eventually we should use X" or "Consider migrating to Y" — these are not rules, they are notes. Remove them.
• Redundant rules: Rules that duplicate what is already in your team's style guide, README, or lint config.
• Outdated rules: References to deprecated tools, old branch naming conventions, or retired workflows.

Before vs After: Real Token Math

Here is a realistic comparison. The "before" CLAUDE.md is a typical file from a developer who has been adding rules for months without ever removing any. The "after" is the same developer after a 20-minute audit.

Before: Bloated CLAUDE.md (56 lines, ~450 tokens)

After: Trimmed CLAUDE.md (8 lines, ~65 tokens)

Token Cost Comparison

That 85% reduction is just from CLAUDE.md overhead. It does not include the additional savings from project-specific rules files, which only load when you are actually working in that project. Over a year of daily use, trimming your CLAUDE.md saves roughly $8 — per developer. For a team of 10, that is $80 saved annually, just from a 20-minute file audit.

Organizing Rules by Project

Once you have trimmed your global CLAUDE.md down to universal rules, the next step is organizing project-specific and language-specific rules so they load only when relevant. Claude Code supports a structured rules directory.

The .claude/rules/ Directory Structure

Language-specific rule files (like python.md or typescript.md) are loaded automatically when Claude detects you are working in that language. This means your Python linting rules only cost tokens when you are actually writing Python — not when you are debugging CSS or reviewing a markdown file.

For project-level conventions, place a CLAUDE.md or .claude/rules/ directory in the project repository itself. These files only load when your working directory is inside that project. If you contribute to 5 different repos, each with its own conventions, none of those project-specific rules burn tokens in the other 4.

The key principle is locality: rules should live as close as possible to where they apply. Universal rules at the user level, language rules in named files, project rules in the repo. Every rule further down the hierarchy is less likely to apply to any given conversation, so keeping it local prevents it from leaking into unrelated sessions.

Maintenance Tips

Trimming your CLAUDE.md is not a one-time task. Rules accumulate over time, and without periodic maintenance, your lean 8-line file will grow back to 50+ lines within months.

Schedule a Quarterly Audit

Set a calendar reminder to review your CLAUDE.md and rules directory every 3 months. Ask yourself three questions for each rule: (1) Do I still follow this rule in practice? (2) Does this rule apply to all projects, or can it move to a language-specific file? (3) Has this rule been superseded by a tool config or team convention?

Remove Stale Rules Immediately

When you change jobs, switch primary languages, or adopt a new framework, remove the old rules right away. References to Python 3.8 conventions when you are on 3.12, or React class component rules when you use hooks exclusively, are dead weight. Every stale rule costs tokens to deliver zero value.

Use Version Control for Rules

Keep your user-level CLAUDE.md and rules directory in a dotfiles repo. This gives you a history of changes, makes it easy to sync across machines, and provides a natural review step before committing rule changes. If a rule was important enough to add, it should be important enough to justify in a commit message.

Watch for Rule Creep

The most common failure mode is "just one more line." You encounter a situation, think "Claude should know this," and add a rule. Over weeks, these one-liners accumulate. To combat this, adopt a hard cap: your global CLAUDE.md must never exceed 15 lines. If you want to add a new rule, you must remove or relocate an existing one first. This forces prioritization.

Common Mistakes

Trimming your CLAUDE.md is simple in principle, but there are a few ways to get it wrong. Here are the most common pitfalls and how to avoid them.

1. Cutting Too Aggressively

The goal is not zero lines — it is the right lines. Removing your security rules ("never output secrets") to save 10 tokens is false economy. Some rules earn their token cost many times over by preventing expensive mistakes. Keep rules that prevent catastrophic failures (security, data loss, destructive git operations) even if they feel obvious. The model benefits from explicit guardrails.

2. Forgetting to Move Rules (Instead of Just Deleting)

The most common mistake: you delete rules from your global CLAUDE.md but never create the corresponding language-specific or project-specific files. The rules are gone, and Claude no longer follows them anywhere. Always verify that a rule has a new home before removing it from the global file. A good practice: create the new rules file first, then delete from global.

3. Keeping Rules as Documentation

CLAUDE.md is not a README. If a line describes something rather than instructing something, it is documentation, not a rule. "This project uses React 18 with TypeScript" is documentation — useful, but better placed in the project README. "Use functional components, prefer hooks over classes" is a rule. Audit your CLAUDE.md for descriptive statements masquerading as rules.

4. Ignoring Context Window Tradeoffs

A very lean CLAUDE.md saves tokens, but it also gives the model less initial guidance. There is a sweet spot — typically 5 to 15 universal rules — where you get most of the behavioral benefits with minimal token cost. Going below 3 lines risks losing important context that shapes the model's default behavior. Experiment: trim aggressively, then add back rules when you notice the model making mistakes it did not make before.

5. Not Testing After Trimming

After trimming your CLAUDE.md, run a few representative tasks to verify the model still behaves as expected. Check that your security rules are still respected, your commit message format is still followed, and your language conventions are still applied. A 10-minute test session is cheap insurance against discovering a missing rule days later when it matters.

FAQ