I Cut My Claude Code Token Usage by 65% With a Simple File Structure Change

Aslam Muhammad — Thu, 09 Apr 2026 05:19:17 +0000

If you use Claude Code regularly, you've probably noticed that your CLAUDE.md file grows over time. You add rules, context, conventions, examples — and before long it's 400 lines of markdown that loads into every single session whether you need it or not.

That's the problem. Claude Code reads your entire CLAUDE.md at the start of every conversation. A typical project file runs around 13,000 tokens. You're burning that budget before writing a single line of code.

The Fix: A Lean Index, Not a Monolith

The insight is straightforward: Claude doesn't need all your rules in every session. It needs the right rules for what you're working on right now.

leanclaude is a Claude Code project template built around this idea. Instead of one large CLAUDE.md, you get:

A lean CLAUDE.md index (~200 tokens) that names the rules but doesn't load them
Focused rule files under .claude/rules/ that Claude pulls in as needed
A memory system for persisting session discoveries across conversations

Claude Code reads the index, understands what rules exist and what they cover, and loads specific files only when relevant to the current task. The result is dramatically lower baseline token consumption.

The Token Math

Approach	Tokens/session	Sessions/day	Daily total
Monolithic CLAUDE.md	~13,000	20	~260,000
leanclaude	~4,500	20	~90,000
Savings	~8,500		~170,000/day

That's roughly 65% less context overhead — tokens that stay available for actual work.

What the Structure Looks Like

.claude/
  rules/
    git-workflow.md
    commit-format.md
    debugging-investigation.md
    escalation-protocol.md
    security-basics.md
    code-review-checklist.md
    examples/
      node/
      dotnet/
      python/
  agents/
    code-reviewer.md
    debugger.md
    refactor-specialist.md
    security-auditor.md
  commands/
    review.md
    debug.md
    pre-pr.md
    add-rule.md
  memory/
CLAUDE.md        # lean index only

The CLAUDE.md at the root is just a table of contents. Each rule file is self-contained and focused on one concern.

What's Included

10 universal rule files covering the patterns that matter on almost every project: git workflow, commit format, debugging discipline, escalation protocol, long-term architecture thinking, security basics (OWASP Top 10), code review checklist, pre-PR checks, validation after changes, and rules for managing rules.

Framework examples for Node.js, Python, and .NET. Use what fits your stack, delete the rest.

4 specialized agents you invoke by name:

code-reviewer — structured review before opening a PR
debugger — systematic root cause investigation (3-strike rule, debug report format)
refactor-specialist — architecture-safe refactoring
security-auditor — OWASP-based security review

4 slash commands — /review, /debug, /pre-pr, /add-rule — each backed by an agent with a defined workflow.

A memory system with typed templates for storing session discoveries, user preferences, and project context that persists across conversations.

How to Get Started

1. Use as a GitHub template

Go to github.com/aslammhdms/leanclaude, click "Use this template", and create your repo.

2. Update CLAUDE.md with your project's specifics

Fill in entry point, build command, and key file locations. The template has placeholder comments showing exactly what to replace.

3. Delete framework examples you don't need

If you're on Node.js, remove examples/dotnet/ and examples/python/. Fewer files means less noise.

4. Open Claude Code and start working

That's it. Claude reads the lean index and references rule files selectively based on the task.

Get It

github.com/aslammhdms/leanclaude

If you try it and find something missing or broken, open an issue. PRs are welcome too.