Jonathon's AI Wiki

Folder-as-Workspace Architecture — 3-Layer Routing for Claude Code Without Building Custom Agents

9 min read

Source: raw/Stop_Building_AI_Agents._Use_This_Folder_System_Instead..md — anonymous creator (channel name not surfaced in transcript), youtube.com/watch?v=MkN-ss2Nl10, fetched 2026-05-20.

A 25-minute walkthrough of a 3-layer folder + CLAUDE.md routing pattern the author argues is “what the industry is actually moving towards” and that replaces building custom agent frameworks. Decision: instead of building one agent per task, build one folder structure with three layers of context routing and let Claude Code become the agent each layer needs. Sister pattern to Ben’s Five-Skill AIOS Setup (which prescribes a specific folder template) and Simon Scrapes’ Nine-Component AIOS (which lists primitives), but with a different emphasis: the pure routing primitive itself as the load-bearing pattern.

Key Takeaways

  • The core thesis: “Stop building agents. Build a folder system.” Most operators are building custom agents for each task (writing-room agent, production agent, distribution agent). The author’s claim: one folder structure + one Claude Code session + good routing in English = N agents. The folder is the app; English file/folder names are the routing logic.
  • Three layers, each with a specific load-time.
    • Layer 1 — CLAUDE.md (the map / floor plan). Loaded automatically every time Claude enters this folder. Contains: folder structure, naming conventions, where files go, what each workspace is for. Author’s framing: “You walk into any room, the floor plan is on the wall, and the agent knows where to go.”
    • Layer 2 — workspace-specific context files (the rooms). Loaded only when Claude routes into that workspace. Each workspace has its own context markdown describing what tasks happen there, which skills/MCPs/files to load. Example workspaces in the template: Writing Room / Production / Community.
    • Layer 3 — the actual files and outputs (the workspace itself). Where the work lives. Drafts, scripts, outputs, with naming conventions enforced by Layer 1.
  • The router table — the most important pattern in the whole system. Inside each workspace’s Layer-2 context file, the author embeds a simple markdown table that tells the AI: for THIS task, read THESE files, skip THOSE files, you might need THESE skills. The author calls this “traditional function-call routing that has existed for decades and decades — but now it gets to be natural language English.” Without the router table, the agent either reads everything (wastes tokens), guesses wrong (misses what matters), or can’t be edited.
  • One Claude session, many contexts — not one agent per task. From Writing Room with minimal prompting, the agent loads only writing-room context. Open a second Claude in Production, load only production context. The same Claude session can move files between workspaces: “Take the script from writing room and let’s make an animation out of it in production.” No multi-agent framework needed.
  • Skills are wired into the system, not standalone. The author’s distinction from “just running skills”: skills called from inside Layer-2 context files, conditionally based on which workspace + which stage the agent is in. “You can wire up to 15 skills, 20 skills, 100 skills into a workspace, or you can perfectly add the skills where you’d need them inside the workspace rather than having them loaded at all times.” The plug-and-play of skills + the routing logic of folders.
  • Naming conventions in CLAUDE.md replace database queries. Sneaky trick: at the start of CLAUDE.md the author lists folder navigation rules + file naming conventions (e.g., example-api-off-guide-draft.md, 2026-03-launch-week.md). The agent uses these to navigate the file system instead of querying a database when you say “pull my v2 demo script.” “Zero code technically speaking. No Python, no framework, no Postgres, no vector database.”
  • Production pipeline = brief → spec → build → output. The author’s worked example for Production workspace: 4 ordered stages (Brief → Spec → Build → Output), each with its own context that loads only the docs needed for that stage. Brief stage might load text standards. Spec stage might load design system + component library. Build stage might load the deck. Same MD file orchestrates all four sub-workflows. No sub-agents needed.
  • Markdown is the universal substrate. The author spends 90 seconds explaining markdown to non-engineers (John Gruber, 2004, “plain text that renders to formatted document”) because the pattern relies on operators being comfortable opening any of these files in Notepad and editing in plain English. “Look, my CLAUDE.md, this is what it looks like in Notepad. Same thing. And nothing breaks when you edit it. You can type whatever you want in here. It’s just English.”
  • The folder is the UI. “What’s simpler UI than a folder?” The author argues the next phase is voice-to-folder — talking to your folder setup via voice, the AI doing the file-system text work for you. No clicking required.
  • Customization is the whole point — this is a template not a prescription. The transcript walks through Writing Room / Production / Community as a fake-content-business example, but explicitly says: if you’re a content creator, Writing Room becomes Script Lab; if you’re a developer/freelancer, swap design for engineering and become Intake / Production / Delivery. The 3-layer routing model is the durable primitive; the specific folder names are interchangeable.
  • Long lineage claim — 200 years of software engineering principles. The author is writing a research paper on the history of programming (back to 1972 — rules of transparency, rules of composition) and how those principles apply to modern AI. Mentions a five-layer architecture in the paper but says three layers is enough for most operators. The claim: this isn’t a prompt trick or new infrastructure — it’s folders + markdown + advanced software-engineering principles applied to LLM context.
  • One Claude Code subscription = N “apps.” “All you need is one subscription to Claude Code and you can generate a hundred quote-unquote apps that are just folders creating what you need.” The cost-discipline argument for the pattern.

The minimum viable folder structure

your-workspace/
├── CLAUDE.md                    # Layer 1: the map (always loaded)
│                                # — folder structure, naming conventions,
│                                #   where files go, what each workspace is for
│
├── writing-room/                # Workspace 1
│   ├── context.md               # Layer 2: writing-room rules
│   │                            # — router table: for blog post, read these
│   │                            #   files, skip those, load humanizer skill
│   ├── drafts/
│   │   ├── post-1-draft.md
│   │   └── post-2-v2.md
│   └── final/
│       └── 2026-05-19-launch-week.md
│
├── production/                  # Workspace 2
│   ├── context.md               # Layer 2: production rules
│   │                            # — brief → spec → build → output pipeline
│   ├── briefs/
│   ├── specs/
│   ├── builds/
│   └── outputs/
│
└── community/                   # Workspace 3
    ├── context.md               # Layer 2: distribution rules
    └── posts/

Each workspace’s context.md includes the router table — the most load-bearing pattern.

A router table (the structural primitive)

TaskRead these filesSkip theseSkills to load
Write blog postvoice.md, style.md, audience.mdproduction/*, design.mdhumanizer, doc-co-authoring
Build demotech-stack.md, components.mdvoice.md, audience.mdfront-end-design, web-app-testing
Distributechannels.md, tone-by-platform.mdtech-stack.mdsocial-skills, scheduling

Without this table, the agent reads everything per workspace (wastes tokens) or guesses wrong about what matters (misses context).

Try It

  • Start with a single CLAUDE.md + one workspace. Don’t try to build all three workspaces at once. Spin up Writing Room (or Engineering, or Intake) with its own context.md and a basic router table. Confirm Claude routes correctly when you say “work in writing room.”
  • Bake naming conventions into CLAUDE.md from day one. Pick a format (YYYY-MM-DD-name.md or name-vN.md) and document it in the map. The agent will use the filename system as a query mechanism.
  • Embed the router table in every workspace’s context.md. This is the single most important deliverable. “This table eliminates all of those problems.”
  • Add skills inside the router table, not in CLAUDE.md. The discipline: skills load only when the router table says they’re needed for the current task. Loading all 15 skills into Layer 1 defeats the context-discipline gain.
  • Use VS Code (or Cowork) optionally, not required. The author shows VS Code because it’s faster to navigate, but explicitly says everything works the same way in plain folder browsers + Claude Cowork.
  • Talk to your folders instead of clicking. Once layers are wired, the workflow shifts from filesystem navigation to verbal commands: “pull my v2 demo script and start building it” → the agent traverses naming conventions, loads the spec context, and runs the build stage.
  • Customize, don’t copy. The template names are placeholders. If you’re a real-estate agent, Writing Room becomes Listings, Production becomes Marketing Collateral, Community becomes Buyers. The 3-layer pattern is the durable part.

Where this fits in the wiki’s AIOS / folder-routing cluster

SourceWhat it addsSpecific differentiator
This article (Folder-as-Workspace)The pure 3-layer routing primitive itself”Don’t build agents — build a folder + router-table” framing
Ben’s Five-Skill AIOSA specific folder template + 5 named skills (/os-setup, /os-operator, /os-optimizer, /team-os, /os-mcp)Opinionated about Obsidian + Relay + Railway
Simon Scrapes’ Nine-Component AIOSNine primitives listed (identity, brand context, memory, skills, planning levels)Architectural catalog
Cowork Jarvis BuildThree-level CLAUDE.md hierarchy (root → workstation → project)Cowork surface specifically; voice profile auto-generation
Moritz Kremb’s Claudia OSOpenClaw folder architecture ported into Claude CodeHeartbeat-as-routine + tools.md registry + CLI > MCP > API
Nate Herk’s AIOS courseThe 3 Ms + 4 Cs of AIOS frameworkMost comprehensive single course; tool-agnostic

Open Questions

  • The author references writing a research paper “on the history of programming, rules of transparency, rules of composition, 1972, modern AI” with a five-layer architecture version of this same pattern. Worth fetching when published — the three-layer model is a simplification of that work. Author’s name not surfaced in transcript; channel attribution would help locate the paper.
  • “VIP / premium accounts” gating the actual template files — the author offers downloadable workspace templates to subscribers. Should we attempt to identify the creator + check whether public versions exist? Discoverable via the YouTube channel handle.
  • Voice-first folder navigation — author predicts within 6 months everyone is doing voice-to-folder. Worth watching for the practical implementations (likely overlaps with ElevenLabs voice agents + Claude Cowork voice mode).
  • The router-table effectiveness in practice — anecdotal claim of context savings is plausible but not measured. Would benefit from a sample CLAUDE.md vs. no-routing comparison with token-counting (compare to context management reproducibility benchmarks).

Graph View

Backlinks