Agent-as-a-Folder: Organizing AI Agents for Real Projects

I wasted weeks trying to build a smart agent orchestration system with custom routing, state machines, and handoff protocols. Then I realized the best agent architecture is embarrassingly simple: it is just a folder with the right files in it.

The Problem

When you use AI agents on real projects, you quickly run into chaos:

• Which agent knows about the database schema?
• Where are the project conventions documented?
• How do you ensure consistency across sessions when each session starts fresh?
• How does a new team member get the same agent behavior you have?

These are not AI problems. They are information architecture problems. And the solution is the same one programmers have used for decades: put the right information in the right files.

Agent-as-a-Folder

The solution is that each agent's context is a folder containing everything it needs:

.claude/
  CLAUDE.md          # Project instructions and conventions
  commands/          # Custom slash commands for common tasks
project/
  .planning/         # Planning artifacts, state, decisions
  src/               # Actual source code
  tests/             # Test suite

The folder IS the agent. When you start a Claude Code session in that directory, the agent inherits all the context it needs from the files around it. No external configuration, no database of agent memories, no API calls to fetch context.

Why This Works

1. Version controlled: Agent context lives in git, just like your code. You can review changes, revert mistakes, and see the history of decisions.
2. Shareable: Anyone who clones the repository gets the same agent behavior. No setup required beyond installing the AI tool.
3. Composable: Different projects have different agent configurations. A Python API project has different conventions than a WordPress theme project.
4. Debuggable: When the agent does something unexpected, you can read the CLAUDE.md file to understand exactly what instructions it received.

The CLAUDE.md File

This is the most important file in the folder. It tells the agent what conventions to follow, what tools are available, what patterns to use, and what to avoid:

# Project Instructions
- Use FastAPI for all new API endpoints
- Follow the existing Pydantic model patterns in src/models.py
- Run tests before committing any changes
- Never use em dashes in content
- Commit messages follow conventional commits format

Planning Artifacts as Agent Memory

The .planning/ directory gives agents persistent memory across sessions:

• STATE.md: Current project position, accumulated decisions, and blockers
• SUMMARY.md files: What was built, why, and what was learned
• PLAN.md files: What to build next and how

When a new Claude Code session starts, the agent reads these files and knows exactly where the project stands, what decisions were already made, and what to work on next.

The Practical Takeaway

Stop building complex agent orchestration frameworks. Put the right files in the right folders. Let the agent read them. Ship code. The best agent architecture is no architecture at all.

For more on structuring AI agent projects, see the Claude Code project configuration docs.