PowerUp Coaching — Living Knowledge Base

Your Folder Tree Is a Rule Inheritance Hierarchy — Stop Cramming Everything Into One CLAUDE.md

5 min read

Topic

Why one project-root CLAUDE.md is the wrong default architecture for ambient AI work — and the recursive folder pattern (parent rules cascade, child rules stay scoped, inheritance is automatic) that solves both context pollution and rule conflicts at the same time.

Target Reader

Knowledge entrepreneurs and AI-first solopreneurs who have adopted CLAUDE.md / AGENTS.md as the way they configure Claude across their work — and who are now hitting the moment where their root CLAUDE.md is bloated, every project re-copies the same boilerplate, and conflicting rules across contexts produce inconsistent output.

The Fear / Frustration / Want / Aspiration

The frustration: you keep copy-pasting the same rules into every project’s CLAUDE.md and they drift out of sync. The fear: your AI configuration is silently becoming unmaintainable. The want: an architectural pattern that handles rule scoping for you, so universal rules live once and instance-specific rules stay where they belong. The aspiration: an ambient AI setup where every refinement compounds across the right scope — and never across the wrong one.

Before State

The reader has one bloated CLAUDE.md at the project root that tries to cover every context, OR they have many CLAUDE.md files across projects that all repeat the same boilerplate and drift out of sync. Rules conflict across contexts; the AI guesses wrong or asks for disambiguation every time.

After State

The reader treats the folder hierarchy as a rule inheritance hierarchy. Universal rules live at the domain root and apply to every descendant for free. Specific rules live at the level they actually apply to. Adding a new instance (year, client, project) is a one-line copy — universal rules come along automatically. The AI sees only the rules that are relevant here.

Narrative Arc

Open with the single-bag-of-rules failure mode — the bloated root CLAUDE.md that breaks at scale. Diagnose why “more files everywhere” doesn’t solve it (drift), and why “everything at the root” doesn’t either (pollution and conflicts). Reveal the recursive pattern as the structural answer: folders nest, rules inherit, conflicts disappear. Walk through the accounting example as the worked illustration. Close with the migration path — you don’t need to redesign your setup; you walk the existing tree and ask one question at each level.

Core Argument

Folders are not flat storage; they are a rule inheritance hierarchy for ambient agents. Each level’s CLAUDE.md holds rules scoped to that level’s subtree. Parent rules cascade automatically to all descendants. Child rules stay scoped to their branch. The same scoping discipline that makes nested code namespaces tractable makes nested ambient folders tractable — and the architecture handles the compounding for you. Refine a parent rule once, every descendant invocation benefits forever.

Key Evidence / Examples

  • Lou’s accounting walkthrough from the AIM session — accounting/CLAUDE.md holds chart of accounts, ledger conventions, and category-assignment heuristics; year subfolders hold only year-specific irregularities. Adding 2028 next year is a one-line copy.
  • The contrast that drives the reframe: “At the level of the accounting folder, I created all the CLAUDE rules I need. When I do 2027, it can still look at the folder above it and inherit the rules.” — Lou
  • The write-back move that pays off only because the architecture is recursive: when the AI saves its learning to the right scope level, the inheritance does the compounding work. Save universal learning to the parent, save instance-specific learning to the child.
  • Cross-reference to Insight - Ambient Intelligence — Build a Skill in Every Folder to Make Your Entire Knowledge Base Alive — the flat case (every folder is an agent); this insight is the recursive extension.
  • The two failure modes of the flat alternative: bloated single CLAUDE.md (context pollution + rules that don’t apply here) OR many files everywhere (drift + duplication).

Proposed Structure (5–7 beats)

  1. The bloated CLAUDE.md. Open with the reader’s actual situation. The single-bag-of-rules pattern and why it breaks.
  2. Why “just split it up” isn’t the answer. Drift. Duplication. The reader who has tried this knows it does not work.
  3. Folders as rule inheritance. The structural move. Parent rules cascade. Child rules stay scoped.
  4. The accounting walkthrough. Concrete example. Show the directory structure. Show what each level’s CLAUDE.md contains.
  5. The placement test. The single question to ask of every rule: “does this apply to every folder underneath this one?” Anything that does goes up; anything that doesn’t stays here.
  6. The compounding payoff. Refine the parent once, every descendant benefits. Save learning at the right level, inheritance does the work. The architecture compounds knowledge automatically.
  7. The migration path. You don’t redesign — you walk the tree and apply the placement test at each level. The architecture emerges from the audit.

Editorial Notes

The reader-objection to surface and answer: “isn’t this just how folders already work?” — the answer is that folders’ inheritance is structural (well-known) but the rule-inheritance discipline applied to ambient agents is not yet a default pattern in how people set up CLAUDE.md / AGENTS.md. Most users have one root file and ad-hoc child files. Naming the architecture turns ad-hoc into a default.

The accounting walkthrough is load-bearing — without a concrete worked example the architecture sounds abstract. Show the directory tree as ASCII art early and reuse it as the structural anchor throughout.

The placement test (beat 5) is the most copy-pasteable piece — frame it as a single question the reader can use on any existing CLAUDE.md tonight.

Next Step

  • Approved for drafting
  • Needs revision
  • Deprioritised

Graph View