Agent-as-a-Folder: Five Months Later, The Pattern That Stuck

Back in May I wrote about organizing AI agents as folders. I wasn't sure it would stick. Five months later, every project I start begins with a folder structure, and every agent I spin up knows where to look. The pattern survived because it matched how I already think about work.

The Minimum Viable Agent Folder

Here's what a working agent folder looks like in September 2025:

agent/
  CLAUDE.md      # identity, constraints, voice
  context/       # read-only background
  tools/         # scripts the agent can run
  output/        # where it writes artifacts
  log.md         # session notes the agent appends to

Five files, one folder. The agent's identity, knowledge, tools, outputs, and memory all colocated.

Why Other Patterns Lost

I tried agent-in-a-database, agent-as-service, agent-in-a-yaml-file. All of them failed the same test: they separated the agent from the filesystem where real work happens. The folder wins because it sits next to the code, the commits, the outputs. Git versions it for free.

The Discipline This Enforces

Putting the agent in a folder forces questions that are easy to skip otherwise. What does this agent do? What does it need to know? What can it touch? A CLAUDE.md file is a three-paragraph contract. If you can't write it, you don't have an agent. You have a prompt.

For the deeper philosophy, see my earlier agent orchestration notes.