The five-layer stack
Every piece of information an AI agent reads belongs in exactly one of five layers. Mixing them is the single most common cause of "the agent did the right thing locally and broke conventions globally".
The five layers
Click each layer to see what lives there, an example or two, and how long it persists.
01 System Role, persona, hard guardrails.
What lives here. Role definition, persona, safety guardrails, output-format constraints. The model's character before it sees any project.
Examples. The harness's built-in role prompt, safety filters, an "always respond as JSON" output rule.
Persistence High · static
02 Project Repo-level rules everyone shares.
What lives here. Rules and conventions every contributor working in this repo inherits. Versioned alongside the code.
Examples. AGENTS.md (canonical),
CLAUDE.md as a symlink to it,
.cursor/rules/, the lean canonical root plus per-area
overflow in docs/agents/ (and optionally
.claude/rules/ for Claude Code's auto-load layer).
Persistence Medium · versioned
03 Codebase Deep awareness of the actual code.
What lives here. Indices and pointers into the real code, loaded on demand. Not statically written rules, but references that fetch the source of truth when the agent actually needs it.
Examples. Semantic search indices, file
mentions in chat, @-references to docs that load
when the agent asks for them.
Persistence Medium · dynamic
04 Session The state of the task right now.
What lives here. Everything specific to the current conversation: chat history, recent tool output, the file just opened, the user's machine state.
Examples. The last twenty messages, the lint errors from a minute ago, the variable the user just renamed, the agent's working directory.
Persistence Low · transient
05 Tooling What the agent can do.
What lives here. The agent's capabilities and the wiring to them: MCP servers, CLI permissions, API definitions, scoped credentials.
Examples. A "deploy" MCP server limited to
staging, a read-only database connection, the
.agents/skills/ directory the agent can invoke.
Persistence Medium · infrastructure
The decision tree
Before writing a rule, ask:
- Every interaction in every repo? → System.
- Every task in this repo? → Project.
- Something the agent looks up about the code? → Codebase. Reference, do not inline.
- True only for this task or this user? → Session.
- What the agent is allowed to do? → Tooling.
If a rule fits two layers, it is too big. Split it.
What good looks like
A Project-layer file that says, in three sentences:
We use pnpm, not npm. Tests run with `pnpm test`. Lint with `pnpm lint`.
For Python tooling see `pyproject.toml`. For deploy steps see `docs/deploy.md`.Static facts named. Dynamic facts pointed to. Verification commands spelled out. Everything else in its own layer.