The Agent-as-a-Folder Pattern, Four Months Later

The agent-as-a-folder pattern is simple: each agent is a directory with a prompt, a set of tools, and context files. No database, no runtime magic, just files. I adopted it early and four months later it has become the default way I build everything.

Why the Pattern Keeps Winning

Agents defined as folders are reviewable. I can git diff an agent the same way I diff source code. I can see history. I can run two versions side by side. None of this is true for agents baked into a SaaS admin panel.

The pattern also composes. I have a research agent, a writer agent, and a reviewer agent. Each is a folder. A pipeline is a shell script that chains them. No framework, no orchestration library, just Unix.

The Folder Structure That Stuck

agents/
  researcher/
    SYSTEM.md        # role and goals
    TOOLS.md         # tool contracts
    examples/        # few-shot examples
    context/         # static context files
  writer/
    SYSTEM.md
    style-guide.md
    templates/
  reviewer/
    SYSTEM.md
    rubric.md

SYSTEM.md is always the entry point. Everything else is context the agent pulls in as needed. This separation maps perfectly to how I think about the problem and how I debug it when an agent misbehaves.

What I Would Change

I used to put evaluations alongside the agent folder. That was wrong. Evaluations belong in a parallel tree because they serve a different lifecycle: you edit agent prompts often, you edit evaluation fixtures rarely. Mixing them created merge noise.

I would also be stricter about versioning from day one. I now tag agent folders with git tags before major prompt changes. Rolling back a bad prompt change is one command. This discipline saves me roughly once a month.

The pattern's power comes from its boringness. It uses tools every developer already knows: folders, files, git. See the broader pattern discussion in the Anthropic cookbook for related approaches.