# Well-– keep Claude Code's context lean as your codebase grows > Source: > Published: 2026-06-18 17:46:52+00:00 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.