Folder as a Workspace: A Simple Architecture for AI Workflows

·6 min read
aiagentic-engineeringlearningprogramming

The Problem

Most people using AI right now follow the same pattern. Open a chat, type a big prompt, get something back, hit a wall, start over. Maybe you save some prompts somewhere and paste them in each time. Maybe you upload documents. But eventually you run into the same problems — lost context, repeated instructions, and conversations that just stop being useful.

There's a simpler way to work with AI that doesn't require frameworks, databases, or custom-built agents. Just folders and markdown files.

Tokens and Context Windows

To understand why the typical approach breaks down, you need to understand tokens.

A token is roughly three-quarters of a word. The word "hamburger" might be three tokens. AI models read everything you give them — your prompt, the conversation history, any files — and measure it all in tokens.

Every model has a context window — the maximum number of tokens it can see at once. That window is finite. If you dump everything into one giant conversation, the AI writing your blog post is also reading your video production notes. You're burning tokens on stuff that doesn't matter.

This is why conversations go off the rails. It's not that the AI is bad — it's that you're asking it to hold too much at once.

The Workspace Blueprint

Instead of one massive prompt or conversation, you separate your work into distinct workspaces. Each one handles a different kind of task.

For example:

  • Community — content, docs, community engagement
  • Production — scripts, animations, code, builds
  • Writing Room — blog posts, newsletters, drafts

Each workspace is just a folder. The AI only looks at what's relevant to the task you're working on right now. No wasted tokens, no confusion, no bleeding between unrelated work.

You can even run multiple Claude Code instances at the same time — one in your writing room, another in production — and they stay cleanly separated.

The Three Layers

This is the core of the system. Everything runs on three layers, and each one has a specific job.

Layer 1: The Map

This is your claude.md file — the router. It loads automatically every time the AI enters the workspace. You put everything the agent always needs here: folder structure, naming conventions, where files go, what each workspace does.

Think of it as a floor plan on the wall. The agent walks in and immediately knows where everything is without reading every file.

Layer 2: The Rooms

This is where the map sends you. Each workspace has its own context file — a markdown document that describes the process, what to load, what to skip, and how to approach the work.

Want to write a blog post? The writing room's context file says: first understand the topic, then find the angle, then write it, then catch problems. Want to build an animation? Production has its own context with its own steps.

Layer 3: The Workspace

This is where the actual output lives. Your drafts folder, your build output, your finished files. The structure here is what the AI writes into and organizes.

Most people only do one of these layers, maybe two. The reason you want all three is it stops the AI from doing too much at once while still letting you edit every part of the process.

The Routing Table

This is the most important pattern in the whole system. It's a simple table in your context file that tells the AI:

  • For this task → read these files
  • Skip → these files
  • You might need → these skills

Without this, the AI either reads everything and burns through tokens, guesses wrong about what matters, or produces output you can't easily adjust.

For example, a production workspace might have a four-stage pipeline:

  1. Brief — load the script and text standards
  2. Spec — load the design system and component library
  3. Build — generate the actual output
  4. Output — final deliverable

At each stage, the routing table tells the AI exactly what to reference. You can swap things around just by editing the table. It's traditional function-calling and software routing — something that's existed for decades — but now it's written in plain English.

Skills and MCP

Skills are pre-built process packages. Someone else figured out how to do a task — write PowerPoint slides, humanize AI text, co-author docs — and packaged the instructions into a set of markdown files or scripts. You can wire them into your workspace at specific points rather than loading everything at once.

MCP (Model Context Protocol) is how the AI talks to other apps and services. Think of it as plug-and-play integration. At certain points in your workflow, you might need a PDF skill, a web testing skill, or a front-end design skill. You wire them in where they're needed instead of having them loaded at all times.

The key insight: you're putting skills inside a system, not just running them in isolation.

Naming Conventions as a Database

Here's a trick that eliminates the need for any actual database. In your claude.md, you define naming conventions for every type of file:

  • Blog drafts: blog-post-title-draft.md, blog-post-title-v2.md
  • Newsletters: 2026-03-21-launch-week.md
  • Demo scripts: demo-name-v1.md, demo-name-v2.md

The AI knows how to find, organize, and move files just from these patterns. You can say "pull my demo v2 and build a spec from it" and it immediately knows where to look, what to pull, and what to do next.

No SQL. No vector database. No Python scripts. Just a naming convention that turns your folder into a queryable system.

Why This Works

This isn't a prompt trick. It draws from real software engineering principles that have existed for decades:

  • Routing — directing requests to the right handler based on context
  • Composition — building complex behavior from simple, swappable pieces
  • Separation of concerns — each layer does one job and does it well

The difference is that now these patterns are written in natural language instead of code. Your folder becomes your app. Your markdown files become your configuration. And the best part — you don't need to click on anything. You can just talk to your workspace.

Every conversation after setup, the AI knows where it is, what to load, what tools to use, and where to put the work.

Getting Started

If you want to try this yourself:

  1. Create a root folder for your workspace
  2. Add a claude.md at the root with your folder map and naming conventions
  3. Create workspace folders for each type of work you do
  4. Add context files in each workspace describing the process and routing
  5. Start small — you don't need 20 skills on day one

The system grows with you. Start with one workspace, get comfortable, then add more as your workflow demands it.

Inspired by this video.