AGENTS.md Is a Constitution, Not a Brain: Layering Context for AI Coding

AI AgentArchitectureDeveloper Tools

AGENTS.md is not an agent’s brain — it’s more like its constitution. What makes AI coding reliably deliver isn’t cramming more content into one file, but putting context, actions, and quality boundaries in the right places.

A Common Failure Scene

The root AGENTS.md grows to hundreds of lines, and the agent still misses the interfaces it must call, treats expired conventions as current rules, and even knows it “should confirm first” yet goes straight for the write.

A Different Organization, Completely Different Results

In one context-optimization exercise, a config-query interface used to return a ~20k-token full payload on every call. After splitting the response into progressive tiers like full, summary, select, and out, an internal benchmark showed roughly a 96% maximum cut. What worked wasn’t one more prompt — it was making information unfold step by step according to the current task.

The problem isn’t that the model suddenly got dumber. It’s that we stuffed a constitution, a task contract, an operations manual, and long-term knowledge into the same context container. This post addresses one question only: how to organize a coding agent’s context into layers so it can understand the task without being flooded by irrelevant information.

First, Split the Responsibilities

An overgrown AGENTS.md usually serves all of these roles at once:

What got crammed into AGENTS.mdThe real problem it solvesBetter home
Agent role, boundaries, non-negotiable rulesWho you are, what you can’t doAGENTS.md / CLAUDE.md
Current requirements, scope, acceptance criteriaWhat this task must accomplish, and what “done” meansSpec
Project architecture, interfaces, terminology, directory knowledgeWhat this project isWiki / Reference
Repetitive steps, plus platform operations (query, modify, publish)How this kind of task is actually done, how to touch external systems safelySkill + CLI / MCP
Testing, Review, auditing, human sign-offHow you prove it’s rightCI / Review gates

What’s easiest to overlook in this table is lifecycle.

Project rules may change once every few months; the current task’s Spec can go stale within days; the transient context a task produced should be discarded as soon as the task ends. If they all share one resident file, the model not only spends attention distinguishing between them — it also has to judge on its own which parts are already outdated.

Anthropic’s Effective context engineering for AI agents calls this context rot: a longer context doesn’t mean more useful information. On the contrary, irrelevant and stale content dilutes the signal that actually matters.

Context Layering: Each Layer Answers One Question

I prefer to see a coding agent’s working environment as the layered system below, rather than one ever-longer prompt:

Context layering: each layer answers one question

AGENTS.md: Constitution, Not Encyclopedia

It’s a good fit for three kinds of things:

  1. The agent’s role in this repository;
  2. The safety and collaboration boundaries it must respect;
  3. Entry-level working conventions, e.g. “which checks must run after a change.”

It should not carry the project’s entire body of business knowledge, nor should it record the concrete steps of each individual task.

A good test: if a rule only applies to a single task, it doesn’t belong in the resident AGENTS.md.

Spec: Contract for the Current Task

A Spec turns “help me do X” into an executable task boundary:

  • What’s the background and goal;
  • Which files are in scope for modification;
  • What counts as done;
  • Which actions must be confirmed first;
  • What verification evidence should be left behind.

A Spec isn’t another flavor of requirements document — it’s a current-task contract shared by the agent and the human. When the task ends, it can be archived, distilled, or discarded outright.

A Spec is essentially the file-based form of the Session layer in the Agent Memory Management framework: for a multi-step task you use a contract both sides agree on instead of working memory that lives only in the conversation; the “archive and distill” that follows a task is exactly that framework’s Capture and promotion.

Wiki: Long-Term Knowledge, but Not Directives

Architecture explanations, interface semantics, terminology definitions, historical decisions, and battle-tested lessons should all live in a searchable knowledge base.

There’s a boundary here: the knowledge base answers “what is this project, and why was it designed this way,” while a Skill answers “how is this kind of task concretely done.” Mixing the two makes knowledge increasingly resemble an operations manual nobody dares to change.

Skill: Turning Repetitive Actions into Procedures

Skills fit tasks with clear inputs, steps, and outputs, such as:

  • Checking whether a page follows the project’s routing conventions;
  • Generating an interface-integration checklist in a fixed format;
  • Running tests, review, and risk checks on a change;
  • Doing a dry-run first, then producing a change plan awaiting confirmation.

A Skill’s value isn’t in being “very long” — it’s in fixing a stable order of actions while leaving the knowledge you only need on demand in the external store.

CLI / MCP: Boundaries for Action Capabilities

The agent understanding “please change config X” doesn’t mean it should hold a key that can write straight to production.

Queries, modifications, and releases should go through a CLI or MCP tool with an explicit contract, providing:

  • Parameter validation;
  • --dry-run or an equivalent preview capability;
  • An explicit confirmation step;
  • Least privilege;
  • Traceable execution logs.

Building effective agents reminds us that complex agent systems should start from simple, verifiable combinations. The larger the tool surface, the more you need to define each tool’s boundaries first.

How a Task Should Actually Run

Below is a de-identified, typical end-to-end flow. It doesn’t depend on any particular platform — any team that needs an agent to query and modify external systems can adapt it.

A typical task execution flow

Before / After: The Same “Change a Config” Task

Say the request is “change config X.” The key difference isn’t whether the agent can finish — it’s whether every step has a boundary:

StepWithout layeringWith layering
Receiving the requestReads the long doc, then starts operatingSpec first locks the goal, scope, and acceptance criteria
Getting dataPulls all config at onceTakes summary first, then select on demand
Making the changeCalls the write interface directlySkill fixes the steps; CLI dry-runs first
Final confirmationRelies on the agent stopping on its ownHuman confirms the diff before it runs
Quality verificationRelies on human double-checkingReview / CI checks and leaves an audit trail

Without layering, the agent can jump straight from “understanding the request” to “calling a tool,” skipping scope confirmation, execution preview, and result verification. With layering, Spec pins down scope, Skill fixes the order of actions, CLI separates preview from execution, and Review / CI owns the final quality judgment. The agent is still free to reason — it just can’t skip system boundaries.

This is also where context engineering gets misread: reducing context isn’t reducing capability; it’s deferring information that shouldn’t be present at this moment.

A Directory Layout You Can Copy

Here’s an organization that’s small enough to start working immediately:

project/
├── AGENTS.md                    # identity, hard rules, entry-level conventions
├── docs/
│   ├── specs/                   # current-task contracts and acceptance criteria
│   ├── architecture/            # architecture, interfaces, terminology, long-term knowledge
│   └── memories/                # validated pitfalls and lessons
├── skills/
│   ├── feature-check/           # feature-change checks
│   ├── api-change/              # API-change flow
│   └── release-check/           # pre-release checks
├── cli/
│   └── platform-cli/            # query, dry-run, confirm, audit
└── .github/
    └── workflows/
        └── agent-quality.yml    # automated quality gates

You don’t need to stand up every directory up front. You can start from three files:

  1. An AGENTS.md that only states boundaries, not an encyclopedia;
  2. A Spec for the current task;
  3. One Skill that can actually be verified.

Once a class of experience has been repeatedly validated, promote it to long-term knowledge or a team rule — don’t copy every conversation into it.

Three Judgments I Care About

First, an Agent’s Edge Isn’t Prompt Length

A long prompt makes the system look “knowledge-rich,” but it’s hard to keep fresh, relevant, and executable at the same time. What’s genuinely worth optimizing is context hit rate: load only what the current task needs.

Second, Tool Boundaries Beat Wording

“Please don’t change production directly” is a reminder; a preview interface, least privilege, and enforced confirmation are constraints. Rules that can be written into a tool’s contract shouldn’t live only in a prompt.

Pi’s design makes the same trade-off: push constraints into tools and the runtime rather than stacking more system prompt. See the author’s notes on Pi coding agent for the reasoning.

Third, Knowledge Needs Promotion Criteria

Not every agent mistake deserves a new rule. A steadier flow is:

an issue
→ record the symptom
→ judge whether it reproduces
→ verify the fix
→ decide whether it becomes Wiki, a Skill, or a hard rule

Otherwise you end up with a “lesson collection” that gets longer and more contradictory over time.

When This Approach Isn’t Worth It

Context layering isn’t mandatory for every project.

  • A one-off personal script usually doesn’t need full Skills and quality gates;
  • When the project is tiny and the task boundary is obvious, a short AGENTS.md is enough;
  • When tools never touch external systems and there’s no clear security boundary, don’t add confirmation flows just to look “enterprise-grade”;
  • When the team doesn’t yet have stable, repeatable tasks, accumulate real cases first, then abstract directories and conventions.

Complexity should grow with risk and repetition — not with the number of concepts.

Closing

Engineering AI coding isn’t about stuffing more rules into an agent’s head. It’s about giving it a working environment that can be retrieved, executed, verified, and recycled.

AGENTS.md owns identity and boundaries, Spec owns the current task, Wiki owns long-term knowledge, Skill owns actions, CLI/MCP owns system interaction, and Review and CI own quality. None of the layers is perfect — but each knows what it shouldn’t be responsible for.

AGENTS.md is a constitution, not a brain. Make the agent remember less, but hand it more accurate information exactly when it’s needed.

References