Most people reorganize their files for themselves. I reorganized mine for my AI agent — and the results surprised me.
I spend most of my working day inside Claude Code. It reads my files, writes to them, searches them, and navigates between contexts. At some point I realized I was spending more time in each session telling the agent where things were than actually doing the work. That felt like a design problem.
The fix turned out to be simple: stop organizing your filesystem for humans and start organizing it for agents.
The core insight
When Claude Code starts a session, it reads CLAUDE.md files up the directory tree. Each one loads automatically based on where you are. A file in ~/work/customers/acme/ loads the global rules, the workspace rules, the work home rules, and the customers folder rules — in that order, from root to current directory.
This means your directory structure isn’t just organization. It’s the instruction set your agent loads every time.
Bad structure = the agent asks “where should I save this?” every session. Good structure = the agent knows from the path alone what context it’s in and what rules apply.
The directory is the router. The CLAUDE.md at each level is the route handler.
Token costs compound
There’s a second reason to care about this that I didn’t expect: path length directly affects cost.
Every file path appears constantly in an agent workflow — in CLAUDE.md references, tool calls, grep results, error messages, memory entries. A path referenced 50 times per session at 20 characters costs fewer tokens than the same path at 50 characters. The difference is small per reference. Across thousands of agent interactions, it compounds.
I started auditing my folder names:
| Before | After | Why |
|---|---|---|
domain-service/ | gtm/ | Everything in my workspace is domain-specific — the prefix was redundant |
br-spend-analysis/ | revenue/spend/ | Semantic, short, no abbreviation |
field-guidance/ | gtm/guides/ | Describes what it is, not what it’s for |
2026 work Notes/ | work/ | Year prefix breaks paths annually |
The principle: every / costs tokens. Every character in a folder name costs tokens. Design for the machine, not for the Finder sidebar.
I searched for prior art on this. The closest I found was a Dust.tt post that explicitly notes long paths consume tokens in agent prompts, and Anthropic’s own engineering blog on context engineering noting that directory organization determines what loads into working memory. Nobody has formally quantified the differential. It’s treated as pragmatic wisdom. I think it deserves a name: path-token cost.
Scoped context, not one giant file
The wrong way to do this: one massive CLAUDE.md in your home directory with every rule, every path, every workflow.
The right way: a CLAUDE.md at each directory level that only describes that directory.
My hierarchy looks like this:
~/.claude/CLAUDE.md ← identity, hard rules, product naming
~/EmployerCloud/CLAUDE.md ← workspace routing: which subdirs are which
~/EmployerCloud/work/CLAUDE.md ← work context: tools, doc conventions
~/EmployerCloud/work/gtm/CLAUDE.md ← GTM folder: guides, publishing pipeline
~/EmployerCloud/work/customers/CLAUDE.md ← account file format, update workflow
~/Documents/Code/my-kb/CLAUDE.md ← KB repo conventions, CIWhen the agent is working in the my-kb repo, it has loaded: global identity + workspace routing + KB conventions. It has not loaded my customer account workflow or my spend analysis pipeline — those aren’t relevant and shouldn’t be in context.
Path = context. The agent knows what it’s doing because of where it is.
The two-home model
This thinking extended beyond folder names into which cloud provider should hold different content.
My work files live in my employer’s managed cloud infrastructure. When I leave someday, those files stay with that employer.
My personal files shouldn’t live there. They should live in something I control regardless of employer. I moved them to a separate cloud provider, into a folder clearly named for its storage backend.
The backend suffix in the folder name is intentional — it encodes the storage provider. If I ever add a second personal store, it becomes personal-dropbox/ or personal-box/. The agent (and I) always know which cloud a file is in from the path alone.
~/EmployerCloud/work/ ← employer's infrastructure, employer's retention
~/PersonalCloud/personal/ ← mine, regardless of employer
~/Documents/Code/ ← git only, no cloud syncThe third tier is important: code repos shouldn’t be in cloud sync at all. node_modules/, .git/ internals, and build artifacts create sync interference and burn bandwidth. Code gets git — that’s its sync and backup. It lives outside all cloud providers intentionally.
What didn’t exist before
I went looking for prior art on “AI-native filesystem design” as a concept. There are posts about organizing files for AI search, and posts about context engineering for agents. But the specific idea — design your directory structure as an agent routing layer, with CLAUDE.md as route handlers, optimized for token cost — I couldn’t find it written down anywhere.
That doesn’t mean nobody’s doing it. It means nobody’s named it yet.
I’d call the principles:
- Path = context. The agent loads context based on where it is. Directory structure is the routing table.
- CLAUDE.md files are route handlers. Each one fires when the agent enters that directory. Keep them scoped to their directory only.
- Path-token cost is real. Short, flat, semantic names reduce token spend at every reference. It compounds.
- Cloud provider = data ownership boundary. Work and personal content belong in different cloud providers, not different folders in the same one.
- Code lives outside sync. Git is the sync and backup for code. Cloud sync and version control conflict by design.
The before and after
Before: One folder called 2026 work Notes/ (breaks every January). One 700-line CLAUDE.md with every rule mixed together. Every session started with some version of “where do you want me to save this?”
After: A flat semantic structure, scoped CLAUDE.md files at each level, short folder names, and a clear two-home model across cloud providers.
The agent now navigates without being told. When it’s in gtm/guides/, it knows it’s staging content for the KB. When it’s in revenue/spend/, it knows it’s doing analysis work. When it’s in customers/acme/, it knows the account file format and update workflow without me repeating it.
That’s not a productivity hack. That’s a different model for how humans and agents work together — one where the workspace itself is part of the system design.
If you’re building something similar or thinking about agent-native workspace design, I’d be interested to hear about it.