Working Directories for AI Agents: A Practical Guide
By Tyler Cyert
Working directories for AI agents are the single biggest unlock most teams skip when setting up agent workflows. Without them, your agents dump files wherever they want, overwrite each other's output, and leave you with no way to trace what happened. With them, you get a file system contract that makes every run predictable, debuggable, and repeatable.
What Is an AI Agent Working Directory?
An AI agent working directory is a folder with a defined purpose inside your project. It has three properties:
- A name that describes its role (e.g.,
specs/,designs/,output/) - A description that gets injected into your main instruction file so agents know it exists
- An optional INSTRUCTIONS.md that tells agents exactly how to read from and write to it
When you define working directories up front, you are giving your agents a file system contract. Agent A knows to write specs into specs/. Agent B knows to read from specs/ and write designs into designs/.
Why Your Agent Directory Structure Matters
Predictable State
Without defined directories, agents make up their own file paths. With working directories, every agent reads from upstream directories and writes to its own. raw/ is always source materials. wiki/ is always compiled knowledge. output/ is always deliverables.
Controlled Handoffs
When Agent A writes requirements to requirements/ and Agent B reads from requirements/ to produce designs, the contract is visible in the file system. This is the foundation of agent orchestration.
Debuggable Workflows
If something goes wrong, you open the relevant directory and see exactly what the agent produced. The intermediate state is right there, not hidden in a chat log.
Reusable Templates
Define your directory structure once, export it, and apply it to every new project. Especially powerful when combined with a full Claude Code directory structure.
A Real Directory Layout
Here is a content agency workflow where three agents collaborate through shared working directories:
content-agency/
├── .claude/
│ └── agents/
│ ├── researcher.md
│ ├── writer.md
│ └── editor.md
├── CLAUDE.md
├── briefs/
│ └── INSTRUCTIONS.md
├── research/
│ └── INSTRUCTIONS.md
├── drafts/
│ └── INSTRUCTIONS.md
├── reviewed/
│ └── INSTRUCTIONS.md
└── output/
└── INSTRUCTIONS.mdEach agent has clear read and write boundaries. The researcher reads from briefs/ and writes to research/. The writer reads from research/ and writes to drafts/. The editor reads from drafts/ and writes to reviewed/.
Working Directory Patterns by Use Case
| Pattern | Directories | Best For | Agent Flow |
|---|---|---|---|
| Linear pipeline | input/ → process/ → output/ | Simple transformations | One agent reads input, writes output |
| Multi-stage handoff | briefs/ → research/ → drafts/ → reviewed/ | Content creation, documents | Each agent owns one stage |
| Shared workspace | specs/ → src/ → tests/ | Software development | Agents read specs, write to their domain |
| Hub and spoke | raw/ → wiki/ + reports/ + summaries/ | Knowledge management | One source, multiple consumers |
| Feedback loop | drafts/ ↔ feedback/ → final/ | Iterative refinement | Agents alternate between writing and reviewing |
You can define these roles in your AGENTS.md or CLAUDE.md file so every agent knows the full layout before it starts.
How Working Directories Connect to Agent Definitions
- CLAUDE.md (or AGENTS.md) lists every working directory with a one-line description. This gives every agent a map of the full system.
- Agent definitions specify which directories an agent reads from and writes to.
- INSTRUCTIONS.md inside each directory adds local context — formatting rules, file naming, examples of expected output.
Setting Up Working Directories with DotBox
DotBox lets you visually define working directories, set their purposes, write INSTRUCTIONS.md content, and wire them into your agent definitions. When you are done, export the complete directory structure as a zip. The directory paths automatically inject into your CLAUDE.md, so your agents know the full system layout from the first session.
Getting Started
- Map your workflow. Identify the stages and handoff points.
- Pick a pattern. Use the table above to find the one that fits.
- Write INSTRUCTIONS.md files. One per directory — what goes in, what comes out.
- Reference directories in your instruction file. List every working directory with a one-line description.
- Define agent boundaries. Each agent should know which directories it reads from and writes to.
Working directories are the foundation that makes everything else in your agent system actually work.