GitHub - BanyanOutcomes/well-actually: A starter layout for keeping Claude Code's context lean as your codebase grows: path-scoped rules that auto-load by file, on-demand system docs, and skills to maintain both. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
BanyanOutcomes
well-actually
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>3 Commits<br>3 Commits
.claude
.claude
documentation
documentation
example
example
src
src
.gitignore
.gitignore
CLAUDE.md
CLAUDE.md
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
well-actually
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
The structure
├── CLAUDE.md # lean map: orientation + pointers to documentation/, nothing more<br>├── .claude/<br>│ ├── rules/ # how we do things — each file auto-loads ONLY when its paths: match<br>│ │ ├── database.md # paths: migrations, *.sql, src/db/**<br>│ │ ├── api-design.md # paths: src/api/**, routes, handlers<br>│ │ ├── testing.md # paths: *.test.*, *.spec.*, tests/**<br>│ │ └── security.md # paths: auth, api, webhooks, middleware, env<br>│ └── skills/<br>│ ├── well-actually-get-started/ # seeds rules/ + documentation/ in one pass<br>│ ├── well-actually-create-rules/ # splits a fat CLAUDE.md into .claude/rules/<br>│ ├── well-actually-documentation-full/ # documents the whole repo from scratch<br>│ └── well-actually-documentation-recent/# syncs docs with commits since the last sync<br>├── documentation/ # how the system works — read on demand, pointed at by CLAUDE.md<br>│ ├── auth-flow.md<br>│ ├── ingestion-pipeline.md<br>│ ├── billing-webhooks.md<br>│ └── .last-synced # commit SHA the docs were last synced to (created on first full pass)<br>└── example/<br>└── walkthrough.md # one small feature, start to finish — see the mechanism in action
How loading actually works
This is the part most "split your CLAUDE.md" advice gets wrong, so it's worth being precise (confirmed against the official memory docs):
CLAUDE.md loads 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.
.claude/rules/*.md is the load-bearing trick. Each rule file carries a 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.
documentation/ is 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 for a concrete before/after: a path-scoped rule loading itself mid-task, and documentation/ re-syncing from a diff afterward.
The skills
The skills are what keep the layout from being a chore:
well-actually-get-started seeds both trees at once — splits your CLAUDE.md into .claude/rules/ and reads your code into...