Agent config is fragmented chaos. Here's how to standardize it.

Every AI-assisted project right now has a different answer to the same question: where does the agent know who it is, what it can do, and how it should behave?

Some projects use .cursorrules. Some use .claude/ directories. Some use a giant system prompt in a .env file. Some use .agents/. Some use nothing and just paste instructions every session.

The result: agent config is chaos. Nothing is portable. Nothing is version-controlled consistently. Onboarding a new developer to an agent project means reverse-engineering 15 different places where agent behavior is defined.

We ran into this problem at scale — 23 agents, 2 servers, 5 businesses — and iterated our way to a structure that works. Here it is.

The Problem With Current Approaches

.cursorrules — Cursor-specific. Doesn't work outside Cursor. No concept of identity or multi-agent hierarchy. A flat instruction file masquerading as configuration.

.agents/ folders — Better structure, but no standard schema. Every team implements it differently. No concept of agent identity vs tool access vs behavioral constraints.

Giant system prompts — Impossible to version meaningfully. Agents stop reading them above a certain length. No separation of concerns. You can't update the memory protocol without touching the identity definition.

Nothing — Most common. Agent has no persistent identity. Every session is a blank slate. Everything you taught it last week is gone.

The AGENTS.md Pattern

The core insight: agent configuration needs separation of concerns. Different things change at different rates. Identity is stable. Memory protocol changes occasionally. Tool access changes regularly. Lessons learned accumulate constantly.

workspace/
├── SOUL.md          ← Who the agent is (stable — rarely changes)
│                       Mission, personality, voice, values
├── USER.md          ← Who it's helping (semi-stable)
│                       Name, timezone, preferences, communication style
├── AGENTS.md        ← Architecture + behavioral rules (the config file)
│                       Session startup protocol, memory rules, safety constraints
├── TOOLS.md         ← What tools it has access to + how to use them
│                       API keys, credentials, CLI references
├── MEMORY.md        ← Curated long-term memory (updated weekly)
│                       Distilled learnings, past decisions, current context
├── GUARDRAILS.md    ← Hard constraints (max 15 items)
│                       Things the agent must never repeat
├── TODO.md          ← Active tasks
└── memory/
    └── YYYY-MM-DD.md  ← Raw daily session logs

Why it works:

1. Everything is a file — version-controllable, diffable, readable by any model, no proprietary format
2. Clear update cadence — SOUL.md changes rarely. MEMORY.md weekly. TODO.md daily. Daily logs are append-only. You know where to look for what.
3. Works across frameworks — Claude, GPT, local models via Ollama, any system that can read files at session start
4. Separation of concerns — the identity definition and the behavioral constraints and the tool access are separate files. Change one without touching the others.
5. Human-readable — a new developer joining the project can read SOUL.md in 2 minutes and understand what the agent is supposed to be

AGENTS.md as the Session Startup Contract

The most important file is AGENTS.md itself — it's the meta-file that tells the agent how to use all the other files.

A minimal AGENTS.md:

AGENTS.md

Every Session
Before doing anything:
1. Read SOUL.md — who you are
2. Read USER.md — who you're helping
3. Read memory/YYYY-MM-DD.md (today + yesterday)
4. Read MEMORY.md — your curated context
5. Read TODO.md — active tasks
6. Read GUARDRAILS.md — never repeat these mistakes

Memory
- Log everything significant to memory/YYYY-MM-DD.md during session
- At ~90% context: write WORKSTATE.md and stop
- Periodically: review daily files, distill into MEMORY.md

Safety
- Never send external messages without confirmation
- trash > rm
- When in doubt, ask

This is the startup contract. The agent reads it every session and knows exactly what to do before it does anything else.

GUARDRAILS.md: Why 15 Is the Right Number

One file worth calling out specifically: GUARDRAILS.md is a hard-lessons list with a strict max of 15 items.

Why 15? Because a list of 50 lessons isn't a list, it's noise. The agent skims it. Nothing sticks.

15 forces prioritisation: every time you add a lesson, you must decide which existing one is no longer worth keeping. This creates a living document of the most consequential behavioral constraints — the ones that actually changed outcomes.

Examples of items that belong:

• "Never mark a task fixed without verifying it runs"
• "Approval required before any external send — email, tweet, post"
• "trash > rm — recoverable beats gone forever"
• "Write things down — mental notes don't survive session restarts"

Why Not a Single File?

The most common counter-argument: "just put everything in the system prompt."

The problems:

• Length — beyond ~2000 tokens, models start ignoring early sections. A combined SOUL+USER+TOOLS+MEMORY system prompt hits that fast.
• Update friction — editing one part means the whole thing needs review
• No structure — you lose the ability to reason about what's in which layer
• Not portable — a system prompt is API-specific. Files work with any interaction pattern.

The file-based approach scales because each file stays focused and small. SOUL.md should be <200 lines. GUARDRAILS.md should be <15 items. MEMORY.md should be <500 lines (distilled, not raw).

Proposed Standard

If we're going to move toward something portable and interoperable across tools:

Required:
  AGENTS.md    ← session startup contract + architecture rules
  SOUL.md      ← agent identity
  GUARDRAILS.md ← hard behavioral constraints (max 15)

Recommended:
  USER.md      ← user context
  MEMORY.md    ← long-term curated memory
  TOOLS.md     ← tool access documentation

Convention:
  memory/YYYY-MM-DD.md  ← daily session logs
  WORKSTATE.md          ← context-limit save state
  TODO.md               ← active tasks

This isn't radical. It's just applying basic software engineering principles — separation of concerns, single responsibility, version control friendliness — to agent configuration.

Why This Matters Now

Agent projects are multiplying. Most of them will accumulate technical debt in their configuration layer the same way software projects accumulate it in their codebases — because nobody thought about structure early enough.

Getting the config architecture right at the start costs nothing. Migrating a 6-month-old agent fleet to a sensible structure when you're already in production is painful.

AGENTS.md isn't magic. It's just a sane default that people can actually use.

---

If you're building multi-agent systems, check out Mission Control OS — we've been running it in production for a year.