✅ When Your CLAUDE.md Outgrows a Single File
A CLAUDE.md that started as a dozen useful lines tends to grow into hundreds as a project matures — build commands, conventions, gotchas, architecture notes, all accumulating in one file. Past a certain size, that file stops being something Claude reads efficiently and starts being something it has to search through, which costs both context budget and precision. A few structural moves keep it useful as it scales:
- Split by directory, not by topic. A CLAUDE.md in a subdirectory only loads when work touches that subtree — better than one giant root file with sections most sessions never need.
- Put the frequently-needed 20% at the top. Build/test/lint commands and the most commonly hit gotchas belong near the start; deep architecture rationale can live further down or in a linked doc.
- Prefer short, specific rules over long prose. "Never use
--force on this repo's deploy script — it skips the health check" is more useful than a paragraph explaining the deploy pipeline's history.
- Delete stale entries aggressively. A CLAUDE.md instruction that no longer matches the codebase is worse than no instruction — it actively misleads.
A useful test: would a new teammate need this on day one?
If a rule only matters for a rare edge case, it probably belongs in a comment near the relevant code, not in the file that gets read at the start of every single session. Reserve CLAUDE.md for what's genuinely load-bearing across most tasks in that directory.
CLAUDE.md
project memory
directory-scoped config
context budget
onboarding
✅ A Checklist for Reviewing Auto-Mode Permissions Before You Grant Them
Auto mode is most valuable exactly where the stakes are highest — long, unattended runs — which is precisely when a permissive setting you granted weeks ago and forgot about can cause the most damage. A short review checklist worth running whenever you're about to widen auto-mode permissions, and periodically on existing ones:
- Scope to the narrowest command set that actually unblocks the workflow — a broad allowlist granted "to be safe" is usually solving a problem that a narrower one would have solved too.
- Separate CI/scripted permissions from interactive-session permissions — what's reasonable for an unattended nightly job is often too broad for an interactive session where a human could otherwise catch a mistake.
- Re-check after any Claude Code upgrade — as this week's changes to git-command guardrails and shell classification show, default safety behaviour does shift between versions; a permission set tuned around an old default can behave differently after an update.
- Log what auto mode actually did, not just what it was allowed to do — the gap between the two is where surprises live.
Treat permission grants like any other access control
The same discipline that applies to reviewing who has prod database access applies here: least privilege, periodic review, and a clear owner for the decision. Auto-mode permissions are a real access-control surface, not just a convenience setting.
auto mode
permissions
least privilege
access control
Claude Code
