The Agent-as-a-Folder Pattern in Practice

I described the agent-as-a-folder concept in a previous article. Now let me show you what it looks like in a real production project with actual files, actual conventions, and actual results.

The Project: PLAI Blog Platform

This blog runs on a custom platform. The agent configuration for this project looks like this:

plai-website/
  .claude/CLAUDE.md            # Agent instructions
  .planning/
    PROJECT.md                  # Project vision and scope
    ROADMAP.md                  # Phase structure
    STATE.md                    # Current position and decisions
    phases/
      00.1-initial-setup/       # Completed phase artifacts
      00.2-frontend-admin/      # Completed phase artifacts
      00.4-technical-content/   # Completed phase artifacts
      00.5-content-library/     # Current phase
  plai-backend/                 # FastAPI backend code
  peaklight-ai-official-frontend/  # Next.js frontend code

How the Agent Uses This Structure

When I start a Claude Code session, the agent:

1. Reads .claude/CLAUDE.md for project conventions
2. Reads .planning/STATE.md to understand current position
3. Reads the current phase's PLAN.md for specific tasks
4. Has full context without me explaining anything

This is the key benefit: zero re-explanation across sessions.

The STATE.md File in Action

STATE.md tracks accumulated decisions, blockers, and progress:

## Current Position
Phase: 0.5 of 12 (Daily Technical Content Library)
Plan: 1 of 8 in current phase
Status: In progress
 
## Accumulated Decisions
- DynamoDB provisioned mode for free tier
- Plain fetch() with revalidate:60 for API client
- Python urllib scripts for batch content creation

A new agent session reads this and immediately knows: we are in Phase 0.5, working on Plan 1, and these decisions have already been made. No need to re-debate them.

SUMMARY.md as Session Memory

After each plan completes, a SUMMARY.md captures what was built and why:

## What Was Built
- 8 technical articles published via Python scripts
- Dynamic sitemap with API-driven content
- JSON-LD structured data for all blog posts
 
## Decisions Made
- Python urllib over requests (zero dependencies)
- Delete-and-recreate pattern for categories (no PUT endpoint)

Future sessions read these summaries to understand the full history of the project without replaying every conversation.

The Result

With this folder structure in place:

• Every agent session starts productive immediately
• Decisions do not get re-debated
• New agents (or new team members) have full context
• The project state is version-controlled and auditable

The agent-as-a-folder pattern is not theoretical. It is how I ship code every day. The folder is the agent.

See the Claude Code docs for CLAUDE.md configuration reference.