Well-– keep Claude Code's context lean as your codebase grows

A developer has released a starter layout for Claude Code that splits context into path-scoped rule files to keep the AI assistant's context window lean as codebases grow. The template uses .claude/rules/*.md files with YAML frontmatter paths: globs so rules load automatically only when relevant files are touched, avoiding the cost of loading everything into every session. The approach includes skills to seed and maintain the structure, aiming to make Claude Code more efficient for large projects.

A starter layout for keeping Claude Code sharp as your codebase grows. The premise, in one line: the context window is a budget, not a backpack. Everything you load costs you twice — once in space, once in attention. So instead of cramming everything into CLAUDE.md , this template splits context into pieces that load only when they're relevant — and for the rules half, it uses Claude Code's own path-scoped loading so "only when relevant" is a mechanism , not a hope. Full write-up: Context Is a Budget, Not a Backpack https://banyanbusinessoutcomes.com/attention/context-is-a-budget-not-a-backpack/ . ├── CLAUDE.md lean map: orientation + pointers to documentation/, nothing more ├── .claude/ │ ├── rules/ how we do things — each file auto-loads ONLY when its paths: match │ │ ├── database.md paths: migrations, .sql, src/db/ │ │ ├── api-design.md paths: src/api/ , routes, handlers │ │ ├── testing.md paths: .test. , .spec. , tests/ │ │ └── security.md paths: auth, api, webhooks, middleware, env │ └── skills/ │ ├── well-actually-get-started/ seeds rules/ + documentation/ in one pass │ ├── well-actually-create-rules/ splits a fat CLAUDE.md into .claude/rules/ │ ├── well-actually-documentation-full/ documents the whole repo from scratch │ └── well-actually-documentation-recent/ syncs docs with commits since the last sync ├── documentation/ how the system works — read on demand, pointed at by CLAUDE.md │ ├── auth-flow.md │ ├── ingestion-pipeline.md │ ├── billing-webhooks.md │ └── .last-synced commit SHA the docs were last synced to created on first full pass └── example/ └── walkthrough.md one small feature, start to finish — see the mechanism in action This is the part most "split your CLAUDE.md" advice gets wrong, so it's worth being precise confirmed against the official memory docs https://code.claude.com/docs/en/memory : loads CLAUDE.md in full, every session . So it stays a table of contents, not an encyclopedia — orientation plus pointers to documentation/ , and any standard so universal it should always be in context.is the load-bearing trick. Each rule file carries a .claude/rules/ .md paths: glob in its YAML frontmatter, and Claude Code loads it automatically and only when Claude touches a file matching that glob . Open a migration → database.md arrives. Fix a typo → nothing arrives. You don't reference these from CLAUDE.md ; the glob does the work.⚠️ A rule file without a paths: block loads on every session — that's the backpack again. Every file here has one on purpose.- This beats the common alternatives: a markdown mention of a file loads nothing automatically the model has to choose to read it , and an @import loads eagerly at startup costs context every session . paths: is the only mechanism that's both automatic and relevance-gated. is documentation/ read on demand — there's no auto-load, which is correct for reference material you reach for occasionally. CLAUDE.md lists these so the right one is easy to find. Good docs are cached understanding; the .last-synced marker is how the maintenance skill keeps that cache honest. See example/walkthrough.md /BanyanOutcomes/well-actually/blob/main/example/walkthrough.md for a concrete before/after: a path-scoped rule loading itself mid-task, and documentation/ re-syncing from a diff afterward.The skills are what keep the layout from being a chore: seeds both trees at once — splits your well-actually-get-started CLAUDE.md into .claude/rules/ and reads your code into documentation/ , fanning out subagents so it's fast.does just the rules half: reads an existing well-actually-create-rules CLAUDE.md and decomposes it into concern-scoped .claude/rules/ files, each with the right paths: glob.reads the whole repo and writes well-actually-documentation-full documentation/ from scratch — one doc per subsystem, in parallel. Use it to seed, or to reset docs that have rotted too far. It also writes the first .last-synced marker.is the maintenance loop: it reads every commit well-actually-documentation-recent since the last sync tracked by .last-synced , not a calendar window and updates only the affected docs, then advances the marker. - Clone this repo, or copy the layout into an existing project. - Open the folder in Claude Code. - Run . It reads your existing well-actually-get-started CLAUDE.md and code and seeds .claude/rules/ and documentation/ for you — replacing the placeholders with the real thing. Starting from scratch with no CLAUDE.md ? Skip this and fill the placeholder files in by hand; each ships with a short prompt explaining what belongs there, and the rule files show the paths: format to copy. - Review the proposed lean CLAUDE.md and approve it. - From then on, after each feature lands, run and watch the affected docs update themselves. If the docs ever drift too far, well-actually-documentation-recent rebuilds them from the whole repo. well-actually-documentation-full The Quickstart assumes you're starting fresh. To add this to an app you already have , you only need the skills — the placeholder CLAUDE.md , .claude/rules/ , documentation/ , src/ , and example/ are scaffolding for a new project, and the skills regenerate the real versions from your code. Copy just the skills: from your app's root mkdir -p .claude/skills cp -r /path/to/well-actually/.claude/skills/well-actually- .claude/skills/ PowerShell New-Item -ItemType Directory -Force .claude\skills | Out-Null Copy-Item -Recurse C:\path\to\well-actually\.claude\skills\well-actually- .claude\skills\ The well-actually- names won't collide with typical project skills, so this merges cleanly. Then, from your app: - Run to decompose your existing well-actually-create-rules CLAUDE.md into .claude/rules/ . It proposes a slimmed CLAUDE.md written to CLAUDE.md.proposed for you to diff and never overwrites the original without approval. - Run to generate well-actually-documentation-full documentation/ from your code and write the first .last-synced marker. - Maintain with as you ship. well-actually-documentation-recent The skills create .claude/rules/ and documentation/ if those folders don't exist, so there's nothing to set up by hand. well-actually-get-started runs steps 1–2 together; on an existing app you can also just run them directly. These files are deliberately generic — they're prompts, not prescriptions. Delete the rules you don't need, add the concerns you do, and tune each rule's paths: glob to your actual layout — that's the one thing worth getting right, since it decides when the rule fires. Keep every file short. The moment a rule file turns into a second encyclopedia, you're back to carrying the backpack.