Skip to main content

The .agents/ Directory

The repo tier of the context hierarchy. An agent can read every line of your code and still write the wrong thing, because the knowledge that matters most is not in the code — it's in people's heads. The .agents/ directory is where you write that knowledge down so every agent starts each task already briefed.

An agent without your context makes confident, wrong assumptions about your requirements. A new hire reads the onboarding wiki before touching the codebase; an agent should read its briefing before every task.

11
markdown files, one per concern
7
role-scoped briefings routed from one directory
every task
re-read before work begins
in git
versioned and reviewed like code

Code is not context​

LLMs are good at reading code and bad at inferring intent from it. A model can see that you call a function, but not that you use Fernet for encryption everywhere, that every API route needs auth middleware, or that you never use VARCHAR because a past migration burned you. That is the non-obvious knowledge experienced developers carry — and an agent without it guesses.

So you write it down. A scaffold drops a handful of markdown files in .agents/, each split by concern, and agents read them before every task.

Routed by role​

The directory is not one big context dump. It is split by concern, and each agent in the pipeline reads only the files relevant to its job. A single monolithic context file forces every agent to read everything, which burns tokens and buries the three lines that matter. Splitting by concern means context is routed, not broadcast.

.agents/11 files · one per concern
FileWhat it containsWhich agents read it
SPECIFICATION.mdproblem, acceptance criteria, risksPlanner · Implementer · Reviewer · QA
ARCHITECTURE.mdsystem overview, boundaries, data flowPlanner · Implementer · Reviewer · Risk
DATABASE.mdschema, migrations, indexes, conventionsPlanner · Implementer · Risk
API_CONTRACTS.mdendpoints, request/response shapes, errorsPlanner · Implementer · QA
STYLE_GUIDE.mdconventions, naming, formatting, patternsImplementer · Reviewer
SECURITY.mdauth, secrets, input validation, OWASPImplementer · Reviewer · Risk
COMPLIANCE.mdPII handling, audit rules, regulatoryImplementer · Reviewer · Risk
TEST_STRATEGY.mdcoverage targets, fixtures, philosophyQA
RUNBOOK.mdhealth checks, incident response, rollbackRisk · Deploy · Monitor
DEPLOY.mdenvironments, CI/CD pipeline, feature flagsDeploy
MONITORING.mdkey metrics, SLOs, dashboards, alertingMonitor
Eleven files, each scoped to the agents that need it. Risk scores against SECURITY, COMPLIANCE, and RUNBOOK on top of the architecture it shares with everyone; TEST_STRATEGY exists for QA alone. Same directory, seven briefings, one per role.

A file is a contract​

Each file is plain markdown with one extra convention: a header line naming the agents that read it. Here is a filled-in ARCHITECTURE.md — none of which is inferable from any single file in the repo:

.agents/ARCHITECTURE.md
# Architecture

> Agents: Planner · Implementer · Reviewer · Risk

## Service Boundaries
| Service / Module | Responsibility            | Communicates With |
|------------------|---------------------------|-------------------|
| engine/api       | HTTP, auth, validation    | orchestrator, db  |
| orchestrator     | poll, dispatch, reconcile | workers, tracker  |
| workers          | run the coding-agent CLI  | code host, db     |

## Key Design Decisions
- Async everywhere (asyncpg, async SQLAlchemy).
- JWT in HTTP-only cookies; OIDC/SSO for enterprise.
- Fernet encryption for stored tokens; keys rotate quarterly.

The tables are deliberate — an agent parses "orchestrator talks to workers and the tracker" far more reliably from a row than from a paragraph. The reason behind async-everywhere is institutional memory; the Fernet decision is exactly the kind of thing an agent would otherwise reinvent three different ways.

Of the eleven, SPECIFICATION.md does the most work. The Planner writes it from an issue, and every downstream agent validates against it — especially the out-of-scope list, which is how you stop an agent from gold-plating a two-line change into a refactor nobody asked for. The acceptance criteria become the Reviewer's checklist and QA's test targets; the risks line is what the Risk agent reads before it scores. One file, read four different ways.

Be specific, or don't bother​

The failure mode is vagueness. The test is simple: if an agent could infer it from the code, leave it out; if it could not, write it down precisely — real paths, real function names, real table names.

✓Specific and current
All API routes are in src/api/ and use FastAPI routers
Auth uses JWT in HTTP-only cookies, in auth.py
Migrations use Alembic: alembic upgrade head
✕Vague or aspirational
We use a modern web framework
Follow best practices
We should eventually add more tests
Anything an agent could already read from the code is noise; the value is precisely what it cannot infer. Written-down standards also turn a vague “this looks risky” into a specific, citable objection — the difference between a review an engineer trusts and one they wave off.

CLAUDE.md, taken seriously​

If this feels familiar, it should. A coding agent already reads a root instruction file on every run — build commands, conventions, architecture notes — injected straight into the system prompt. The .agents/ directory is that same instinct taken seriously: instead of one catch-all file that grows into a monolith, a set split by concern and routed by role. One CLAUDE.md is a sticky note; eleven routed files are an onboarding program.

And the instinct itself is now an open standard, not a private convention.

agents.mdOpen Standardsource ↗
AGENTS.md: the industry converges on files-in-repo agent grounding

AGENTS.md began as a collaboration spanning OpenAI Codex, Amp, Google Jules, Cursor, and Factory, and is now stewarded by the Agentic AI Foundation under the Linux Foundation. The format is read natively by roughly twenty tools — Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Factory, Jules, and more — so one file in the repo briefs every agent that touches it. The standard already anticipates routing: nested AGENTS.md files scope instructions to subtrees, and OpenAI’s own codex monorepo ships 88 of them. The .agents/ directory on this page extends that single-file standard one step further — the same system of record, split by concern and routed by role rather than nested by path.

The repo as the agent's system of record is now an industry standard, not a niche practice — adopted in tens of thousands of public repositories, with over 60,000 searchable examples on GitHub.

The one rule that matters after you write these files is to keep them true. Out-of-date context is actively harmful — it leads agents to the confident wrong assumptions the directory exists to prevent. Because the files are plain markdown in the repo, the .agents/ update is part of the change, not a cleanup task for later.

That is the whole idea: the context layer for a single repo, kept honest, in the repo. To scale it across many repos, give the whole system one — the poor man's monorepo.