{"slug": "well-keep-claude-code-s-context-lean-as-your-codebase-grows", "title": "Well-– keep Claude Code's context lean as your codebase grows", "summary": "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.", "body_md": "A starter layout for keeping Claude Code sharp as your codebase grows.\n\nThe 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`\n\n, 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.\n\nFull write-up: [Context Is a Budget, Not a Backpack](https://banyanbusinessoutcomes.com/attention/context-is-a-budget-not-a-backpack/)\n\n```\n.\n├── CLAUDE.md                 # lean map: orientation + pointers to documentation/, nothing more\n├── .claude/\n│   ├── rules/                # how we do things — each file auto-loads ONLY when its paths: match\n│   │   ├── database.md        #   paths: migrations, *.sql, src/db/**\n│   │   ├── api-design.md      #   paths: src/api/**, routes, handlers\n│   │   ├── testing.md         #   paths: *.test.*, *.spec.*, tests/**\n│   │   └── security.md        #   paths: auth, api, webhooks, middleware, env\n│   └── skills/\n│       ├── well-actually-get-started/         # seeds rules/ + documentation/ in one pass\n│       ├── well-actually-create-rules/        # splits a fat CLAUDE.md into .claude/rules/\n│       ├── well-actually-documentation-full/  # documents the whole repo from scratch\n│       └── well-actually-documentation-recent/# syncs docs with commits since the last sync\n├── documentation/            # how the system works — read on demand, pointed at by CLAUDE.md\n│   ├── auth-flow.md\n│   ├── ingestion-pipeline.md\n│   ├── billing-webhooks.md\n│   └── .last-synced          # commit SHA the docs were last synced to (created on first full pass)\n└── example/\n    └── walkthrough.md        # one small feature, start to finish — see the mechanism in action\n```\n\nThis 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)):\n\nloads`CLAUDE.md`\n\n*in full, every session*. So it stays a table of contents, not an encyclopedia — orientation plus pointers to`documentation/`\n\n, and any standard so universal it should always be in context.is the load-bearing trick. Each rule file carries a`.claude/rules/*.md`\n\n`paths:`\n\nglob 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`\n\narrives. Fix a typo → nothing arrives. You don't reference these from`CLAUDE.md`\n\n; the glob does the work.⚠️ A rule file*without*a`paths:`\n\nblock loads on every session — that's the backpack again. Every file here has one on purpose.- This beats the common alternatives: a markdown\n*mention*of a file loads nothing automatically (the model has to choose to read it), and an`@import`\n\nloads eagerly at startup (costs context every session).`paths:`\n\nis the only mechanism that's both automatic*and*relevance-gated.\n\nis`documentation/`\n\n*read on demand*— there's no auto-load, which is correct for reference material you reach for occasionally.`CLAUDE.md`\n\nlists these so the right one is easy to find. Good docs are cached understanding; the`.last-synced`\n\nmarker is how the maintenance skill keeps that cache honest.\n\nSee [ 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\n\n`documentation/`\n\nre-syncing from a diff afterward.The skills are what keep the layout from being a chore:\n\nseeds both trees at once — splits your`well-actually-get-started`\n\n`CLAUDE.md`\n\ninto`.claude/rules/`\n\nand reads your code into`documentation/`\n\n, fanning out subagents so it's fast.does just the rules half: reads an existing`well-actually-create-rules`\n\n`CLAUDE.md`\n\nand decomposes it into concern-scoped`.claude/rules/`\n\nfiles, each with the right`paths:`\n\nglob.reads the whole repo and writes`well-actually-documentation-full`\n\n`documentation/`\n\nfrom 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`\n\nmarker.is the maintenance loop: it reads every commit`well-actually-documentation-recent`\n\n*since the last sync*(tracked by`.last-synced`\n\n, not a calendar window) and updates only the affected docs, then advances the marker.\n\n- Clone this repo, or copy the layout into an existing project.\n- Open the folder in Claude Code.\n- Run\n. It reads your existing`well-actually-get-started`\n\n`CLAUDE.md`\n\nand code and seeds`.claude/rules/`\n\nand`documentation/`\n\nfor you — replacing the placeholders with the real thing. (Starting from scratch with no`CLAUDE.md`\n\n? 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:`\n\nformat to copy.) - Review the proposed lean\n`CLAUDE.md`\n\nand approve it. - From then on, after each feature lands, run\nand watch the affected docs update themselves. If the docs ever drift too far,`well-actually-documentation-recent`\n\nrebuilds them from the whole repo.`well-actually-documentation-full`\n\nThe Quickstart assumes you're starting fresh. To add this to an app you **already have**, you only need the skills — the placeholder `CLAUDE.md`\n\n, `.claude/rules/`\n\n, `documentation/`\n\n, `src/`\n\n, and `example/`\n\nare scaffolding for a new project, and the skills regenerate the real versions from your code. Copy just the skills:\n\n```\n# from your app's root\nmkdir -p .claude/skills\ncp -r /path/to/well-actually/.claude/skills/well-actually-* .claude/skills/\n# PowerShell\nNew-Item -ItemType Directory -Force .claude\\skills | Out-Null\nCopy-Item -Recurse C:\\path\\to\\well-actually\\.claude\\skills\\well-actually-* .claude\\skills\\\n```\n\nThe `well-actually-*`\n\nnames won't collide with typical project skills, so this merges cleanly. Then, from your app:\n\n- Run\nto decompose your existing`well-actually-create-rules`\n\n`CLAUDE.md`\n\ninto`.claude/rules/`\n\n. It proposes a slimmed`CLAUDE.md`\n\n(written to`CLAUDE.md.proposed`\n\nfor you to diff) and never overwrites the original without approval. - Run\nto generate`well-actually-documentation-full`\n\n`documentation/`\n\nfrom your code and write the first`.last-synced`\n\nmarker. - Maintain with\nas you ship.`well-actually-documentation-recent`\n\nThe skills create `.claude/rules/`\n\nand `documentation/`\n\nif those folders don't exist, so there's nothing to set up by hand. (`well-actually-get-started`\n\nruns steps 1–2 together; on an existing app you can also just run them directly.)\n\nThese 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.", "url": "https://wpnews.pro/news/well-keep-claude-code-s-context-lean-as-your-codebase-grows", "canonical_source": "https://github.com/BanyanOutcomes/well-actually", "published_at": "2026-06-18 17:46:52+00:00", "updated_at": "2026-06-18 18:01:25.617483+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "large-language-models"], "entities": ["Claude Code", "Anthropic", "CLAUDE.md", "Banyan Business Outcomes"], "alternates": {"html": "https://wpnews.pro/news/well-keep-claude-code-s-context-lean-as-your-codebase-grows", "markdown": "https://wpnews.pro/news/well-keep-claude-code-s-context-lean-as-your-codebase-grows.md", "text": "https://wpnews.pro/news/well-keep-claude-code-s-context-lean-as-your-codebase-grows.txt", "jsonld": "https://wpnews.pro/news/well-keep-claude-code-s-context-lean-as-your-codebase-grows.jsonld"}}