The filesystem is your agent's routing layer

A developer found that organizing a filesystem for AI agents rather than humans significantly improves efficiency, as Claude Code automatically loads `CLAUDE.md` files from the directory tree based on the agent's current location. The developer discovered that shorter, semantic folder names reduce token costs across thousands of agent interactions, with every character in a file path consuming tokens each time it appears in tool calls, grep results, and memory entries.

CLAUDE.md files up the directory tree automatically — your directory structure is the instruction set your agent runs every time, not just organization for humans. CLAUDE.md files at each directory level beat one 700-line monolith — the agent loads only the context relevant to where it is, not every rule you've ever written. 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. 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. 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 https://dust.tt/blog/how-we-taught-ai-agents-to-navigate-company-data-like-a-filesystem that explicitly notes long paths consume tokens in agent prompts, and Anthropic's own engineering blog https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents 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 . 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 ~/WorkCloud/CLAUDE.md ← workspace routing: which subdirs are which ~/WorkCloud/work/CLAUDE.md ← work context: tools, doc conventions ~/WorkCloud/work/guides/CLAUDE.md ← guides folder: publishing pipeline ~/WorkCloud/work/customers/CLAUDE.md ← account file format, update workflow ~/Documents/Code/my-kb/CLAUDE.md ← KB repo conventions, CI When 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. 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. ~/WorkCloud/work/ ← employer's infrastructure, employer's retention ~/PersonalCloud/personal/ ← mine, regardless of employer ~/Documents/Code/ ← git only, no cloud sync The 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. 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: 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.