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.mdindex (~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.