Your AGENTS.md Is Not Documentation. It Is an Execution Contract

Most teams start using coding agents by writing instructions.

Then the instruction file grows.

First it says how to run tests. Then it adds style rules. Then security reminders. Then deployment notes. Then architecture summaries. Then a few "always remember" bullets from last week's failed run. Six weeks later, the file has become a junk drawer: part README, part onboarding doc, part policy memo, part prompt library, part tribal memory.

That is the moment `AGENTS.md` stops helping.

`AGENTS.md` is not documentation in the normal sense. It is not a place to explain everything a human might want to know about the repository. It is an execution contract: the global agreement every agent must accept before it performs work in the workspace.

That distinction matters because agents do not read instructions like humans read docs. A human can skim and ignore irrelevant sections. An agent consumes the file as working context. If the contract is bloated, vague, stale, or internally contradictory, you have not made the agent smarter. You have added noise to every run.

The job of `AGENTS.md` is to answer a narrow set of questions:

• What is this workspace for?
• What global rules apply to all work?
• Where should the agent route itself next?
• What must never be done without permission?
• What does "complete" mean at the highest level?

Everything else should be routed somewhere else.

The contract is global, so it must be small

OpenAI's Codex documentation describes `AGENTS.md` as a way to give Codex extra project instructions and context, loaded before work begins. The AGENTS.md open format points teams toward project overview, build commands, tests, style, and security guidance. Claude Code uses `CLAUDE.md` instead, but its memory docs point to the same pattern: project-level instruction files are loaded into agent sessions and can import or mirror `AGENTS.md` for cross-tool consistency.

The pattern is clear: these files shape behavior before the task starts.

That means they should be treated like any other shared interface. A global instruction file is not harmless because it is "just Markdown." It changes what the agent reads, prioritizes, asks permission for, runs, and claims as done.

If a rule applies to every task, it probably belongs in `AGENTS.md`.

If a rule applies only to one product area, one workflow stage, one language, one deployment path, one customer, one incident, or one recurring task, it probably does not.

This is the core operating principle:

That separation is Agent Context Architecture. It turns context from a large prompt into a repository-native operating model.

What belongs in AGENTS.md

A good `AGENTS.md` should be boring, durable, and enforceable. It should contain the rules you would want applied even if the agent is working in an unfamiliar directory.

Start with identity. One short paragraph should tell the agent what the repository is and what the organization is trying to accomplish. Not a brand essay. Not a product manifesto. A practical orientation that prevents category mistakes.

For example:

Then define the first step. Do not ask the agent to explore broadly. Tell it where routing begins.

This turns the root contract into a dispatcher. The agent does not need the whole repo map in `AGENTS.md`. It needs a rule that sends it to the map.

Next, define ownership and collaboration rules. In multi-agent or multi-worker environments, agents must know whether they own the whole tree, one package, one file, or one stage artifact.

Then define global safety and permission rules: never expose secrets, do not run destructive commands without explicit approval, do not change generated files unless the workflow requires it, do not add dependencies casually, and do not publish or deploy without a release contract.

Finally, define the completion standard.

That is the shape of an execution contract. It tells the agent how to enter the system, which boundaries it must respect, and what evidence it owes before leaving.

What does not belong in AGENTS.md

Most broken `AGENTS.md` files fail because they become too successful. Every time an agent makes a mistake, someone adds another rule. Over time, the global file fills with local fixes.

The first thing to keep out is detailed architecture. A short repo overview is useful. A full architecture guide is not. Architecture belongs in reference files that can be routed when relevant.

The second thing to keep out is stage-specific process. Planning, implementation, code review, verification, release, incident response, and content drafting need different inputs and different proof. If all of that lives in the global file, every agent pays for every stage on every task.

The third thing to keep out is one-off memory. "Last time the agent forgot X" is not automatically a global rule. If it was a routing failure, update `CONTEXT.md`. If it was a workflow failure, update the stage contract. If it was a repeated procedure, create or update a skill. If it was missing domain knowledge, update a reference. Only promote it to `AGENTS.md` if it is truly global.

The fourth thing to keep out is tool-specific clutter. Teams often use more than one agent: Codex, Claude Code, Cursor, GitHub Copilot, CI agents, internal bots, or review agents. The global contract should express repo-level behavior in plain Markdown. Tool-specific configuration belongs in that tool's config file or a short adapter.

Claude Code is a useful example. It reads `CLAUDE.md`, not `AGENTS.md`, but its docs recommend importing `AGENTS.md` when a repository already uses it for other agents. That suggests a clean pattern: one shared contract, thin tool adapters.

Use the adapter for tool-specific additions only. Do not fork your operating model across five instruction files unless you want five different behaviors.

CONTEXT.md is the routing layer

If `AGENTS.md` is the contract, `CONTEXT.md` is the map.

The routing layer answers a different set of questions:

• What kind of task is this?
• Which directory owns this work?
• Which files must be read first?
• Which files should be skipped?
• Which stage contract applies?
• Where should outputs go?

This keeps the global contract short while still giving the agent precise local guidance. It also scales to monorepos and cross-functional workspaces.

In this model, the agent starts with the global contract, then routes through the workspace one decision at a time. It does not scan the whole repository, guess which docs are canonical, or load product strategy for a CSS bug.

A practical root `CONTEXT.md` can be mostly a routing table:

| Path                       | Use when                                           | Skill |
| -------------------------- | -------------------------------------------------- | ----- |
| [apps/](apps/)             | Build the web application.                         |       |
| [content/](content/)       | Create, organize, or repurpose content.            |       |
| [strategy/](strategy/)     | Use durable positioning before planning work.      |       |
| [products/](products/)     | Build templates, resources, or productized offers. |       |

The value is explicit context selection. Every routing file is a small decision surface that limits irrelevant reading and preserves team intent.

Stage contracts define what good work looks like

Routing tells the agent where to go. Stage contracts tell it how to behave once it gets there.

This is where many agent workflows fail. Teams tell agents what to build, but not what stage the work is in. The agent treats a planning conversation, bug fix, review, and release note as variations of the same activity: produce plausible text or code.

Engineering work is staged. Agent work should be staged too.

A planning stage should produce scope, assumptions, trade-offs, open questions, and acceptance criteria. An implementation stage should make scoped changes, follow local patterns, update tests, and preserve unrelated work. A review stage should look for bugs, regressions, missing tests, security issues, and operational risk. A verification stage should produce command output, screenshots, eval results, diff review, or a clear explanation of what could not be run.

Put these contracts in workflow-specific files, not in the global agent contract. A verification contract, for example, should name the required inputs, the smallest meaningful checks, when to expand to broader checks, and the output format for command results and remaining risk.

The agent is not done when it says "done." It is done when the stage contract has evidence.

Skills are reusable procedures, not more global prose

Some instructions are not routing and not durable reference knowledge. They are procedures: code review, content drafting, CI debugging, release notes, context audits, or visual generation.

These should become skills, commands, scripts, or workflow templates. They should not be pasted into `AGENTS.md` as long sections that load on every task.

The rule is simple: if the agent should execute a repeatable process only when a task calls for it, make it invocable. Do not make it global.

This also improves governance. A team can review a skill as a reusable asset with a purpose, inputs, outputs, and verification standard. That is much better than burying the same process in an ever-growing instruction file.

In a mature agent system, `AGENTS.md` does not contain every workflow. It tells the agent to use routing that will select the right one.

References hold stable knowledge

Reference material is where most documentation actually belongs.

Architecture decisions, coding standards, design systems, brand voice, security policies, API contracts, domain models, deployment runbooks, and examples are all reference material. They are important, but not equally important to every task.

Agent Context Architecture separates references from instructions. The instruction says, "For this task, read this reference." The reference contains the actual knowledge.

This creates two benefits. References can be maintained for humans and agents at the same time, and they can be routed selectively. A content drafting agent should read positioning and brand voice. A backend implementation agent should read architecture and test commands. A release agent should read deployment and rollback procedure. No single task needs all of it.

This is where structured Markdown becomes infrastructure. Front matter fields like `type`, `name`, `description`, `status`, `tags`, and `source` make files easier for agents to identify and for teams to index. The Markdown body remains human-readable. The metadata gives the workspace a lightweight schema.

The goal is not to over-engineer docs. The goal is to stop making the agent infer document identity from filenames and vibes.

A practical installation pattern

If your team wants to install this pattern, do not start by rewriting all documentation. Start with the smallest control plane that changes agent behavior.

Step one: audit the current instruction file. Highlight every line and classify it as global contract, routing, stage contract, skill or procedure, or reference knowledge. Only the first category stays in `AGENTS.md`.

Step two: write the root contract. Keep it short enough that every engineer can review it. Include purpose, first-step routing, collaboration rules, safety constraints, and completion expectations.

Step three: create the root `CONTEXT.md`. Add a routing table for major directories and task types. Make it obvious where strategy, code, content, products, research, and operations live.

Step four: add local `CONTEXT.md` files only where routing decisions are recurring. Create one where agents need a local map.

Step five: define stage contracts for workflows that create the most risk or rework. Usually that means planning, implementation, review, verification, and release.

Step six: extract repeated procedures into skills or commands. If humans keep typing the same prompt, that is a workflow asset trying to be born.

Step seven: move stable knowledge into references. Keep references concise, linked, and owned.

Step eight: add a maintenance loop. When an agent fails, do not automatically add a new global rule. Diagnose the layer that failed:

• Did the agent start in the wrong place? Fix routing.
• Did it misunderstand the stage? Fix the stage contract.
• Did it miss a repeated process? Fix the skill.
• Did it lack domain knowledge? Fix the reference.
• Did it violate a universal rule? Fix `AGENTS.md`.

This is the difference between context architecture and prompt accretion.

The payoff is less waste and better proof

The business case for Agent Context Architecture is not that the repo looks tidy. The business case is lower waste.

Bad context systems waste tokens by loading irrelevant files. They waste time by making agents rediscover setup instructions. They waste review attention by producing preventable mistakes. They waste trust because every run feels like a new negotiation.

Good context systems reduce that waste. They make the entry point consistent, route tasks to the right files, keep global instructions small, preserve stage outputs, and require evidence before completion. They make failures diagnosable because the team can trace a bad output back to a contract, route, skill, or reference.

This is why `AGENTS.md` should be treated as an execution contract. It is the top of the control plane, not the whole control plane.

The best teams will not win because their `AGENTS.md` is longer. They will win because it is smaller, sharper, and connected to the rest of the system.

Models will keep changing. Agent tools will keep changing. The durable advantage is the operating system around them: the contracts, maps, stages, references, and verification loops that make agent work repeatable.

Your `AGENTS.md` is where that operating system begins.

Do not turn it into a junk drawer.