AGENTS.md and the Repository Control Plane for Coding Agents

Something important changed in AI-assisted coding over the last year. The prompt is no longer the only interface that matters.

More teams now work in repositories touched by multiple coding agents across terminals, IDEs, pull requests, and cloud task runners. In that environment, one good prompt is not enough. The repository itself needs to explain how it should be read, changed, tested, and constrained.

That is why files like AGENTS.md, CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, and .cursor/rules matter. They are not just convenience notes. They are becoming part of the operational surface of software engineering.

This issue focuses on the persistent repository layer around AI-assisted coding: the instruction files that make a codebase legible to agents before any individual task begins.

Why This Matters Now

This is no longer a niche workflow pattern. It is now visible in official product guidance across the industry.

• OpenAI Codex uses AGENTS.md to guide repository-aware coding work and now also documents plan files like PLANS.md for longer execution flows
• Anthropic Claude Code treats CLAUDE.md as project memory, with shared, local, and user-scoped layers
• GitHub Copilot supports repository instructions, path-specific instructions, and agent instruction files such as AGENTS.md, CLAUDE.md, and GEMINI.md
• Cursor supports a simple root-level AGENTS.md file as well as more structured project rules
• Gemini CLI loads GEMINI.md hierarchically and supports modular imports into the active instruction context

Different tools arrived at the same conclusion: repositories need durable instruction surfaces that survive across prompts, sessions, and models.

AGENTS.md Is Not the Spec

This distinction matters.

A task specification and a repository instruction file solve different problems:

• A spec defines one change
• AGENTS.md defines how any change should be approached in this repository
• A spec is task-scoped and disposable
• AGENTS.md is persistent and cross-task
• A spec answers "what should be built now?"
• AGENTS.md answers "how should an agent operate here at all?"

If you merge those responsibilities into one file, you usually get the worst of both worlds: stale repository guidance, bloated task context, and instructions that are too general to enforce real scope.

The Repository Control Plane

The best pattern is layered. The root instruction file should behave like a map, not an encyclopedia.

AGENTS.md
CLAUDE.md
GEMINI.md

.github/
copilot-instructions.md
instructions/
  backend.instructions.md
  docs.instructions.md

.cursor/
rules/
  backend.mdc
  docs.mdc

docs/
architecture/
  index.md
product/
  index.md
reference/
  tool-loading-notes.md
runbooks/
  testing.md

plans/
checkout-validation.md
repository-control-plane-rollout.md

In this structure:

• AGENTS.md is the portable repo map
• Deep documentation in docs/ remains the system of record
• Tool-specific files adapt the repo to a particular agent product
• Task-specific plans in plans/ define one bounded execution at a time

That separation keeps context small while still giving agents stable access to the right knowledge.

What Goes in the Root File

A good AGENTS.md file is short, concrete, and operational. It should tell the agent where to start, what commands matter, what boundaries are real, and when to stop.

# Project Map

This repository demonstrates a portable control plane for coding agents.
Treat it as a source of reusable patterns, not as an application runtime.

## Start Here

- Read README.md for repository purpose and file map
- Read docs/architecture/index.md for the layered model
- Read docs/reference/tool-loading-notes.md for tool behavior differences
- Read docs/runbooks/testing.md before declaring changes complete
- Read plans/ when a task requires bounded execution

## Working Rules

- Keep edits narrow and artifact-specific
- Keep the root instruction files short
- Put long-form knowledge under docs/
- Use plans for bounded changes, not for permanent repository guidance

That is enough to establish orientation and working behavior. The file does not need to restate the full architecture, business domain, or historical design discussion.

If the root file becomes a 1,000-line document, it starts competing with the task, the code, and the real docs for attention.

The Wrong Way to Do This

Most failures come from treating the instruction file as a dumping ground.

• Copying large chunks of architecture docs into AGENTS.md
• Mixing one-off task scope into shared repository guidance
• Committing personal preferences that should live in local or user-scoped files
• Writing soft policy in markdown that is not backed by tests, hooks, approvals, or code enforcement
• Maintaining multiple vendor files that slowly drift into conflicting truth

A large instruction file often feels thorough, but it usually makes agent behavior worse. The model spends attention budget reading duplicated prose instead of the exact files and constraints that matter for the current task.

Portable Instructions Across Tools

The industry trend is not just "use a markdown file." The more important trend is portability.

A single repository may now be touched by Codex, Claude Code, Copilot cloud agent, Cursor, and Gemini CLI. That means you should avoid maintaining five separate repositories of truth.

A practical approach looks like this:

• Keep shared repository guidance in AGENTS.md
• Keep authoritative technical knowledge in docs/
• Use vendor-specific files as thin adapters, not independent manuals
• Use path-specific instruction systems only where local scoping is genuinely useful
• Keep personal workflow preferences out of shared source control when the tool supports local memory files

For example, thin adapter files can stay almost trivial:

# CLAUDE.md
Read AGENTS.md first.
Use this file as a thin project adapter, not as a second knowledge base.

- Repository-wide behavior is defined in AGENTS.md
- Architecture and rollout notes live under docs/
- Task-shaped changes should be driven by files in plans/

# GEMINI.md
Read AGENTS.md first.
Use imported docs as the deeper source of truth when context is needed.

@docs/architecture/index.md
@docs/runbooks/testing.md

# .github/copilot-instructions.md
Read AGENTS.md first for repository-wide operating rules.

- keep changes narrow and intentional
- prefer updating source-of-truth docs instead of duplicating guidance
- if a plan exists in plans/, follow it before making multi-file changes

This keeps the repository legible across tools without forcing every product into the exact same feature model.

Specs Still Matter, but They Sit One Layer Lower

A repository instruction file should define when a plan or spec is required, but it should not become the plan itself.

# Plan: Repository Control Plane Rollout

## Goal

Create a minimal but durable control plane that multiple coding agents can use
without relying on repeated prompt boilerplate.

## In Scope

- add a short root AGENTS.md
- create indexed docs under docs/
- add a thin Copilot adapter
- add one path-specific instruction file for backend code
- define the rule for when a plan is required

That is the clean separation.

• The repository file defines ambient operating rules
• The plan file defines one execution contract
• The human decides when a task is large enough to deserve a plan

This is much stronger than prompt-first coding and much cleaner than stuffing all behavior into one giant shared markdown file.

Instructions Are Not Enforcement

Instruction files matter, but they do not replace actual control systems.

If a rule is important, it should eventually be enforced somewhere deterministic:

• Tests should lock behavior
• Linters should lock structure
• Hooks should lock workflow requirements
• Approval gates should lock risky actions
• Sandbox and tool permissions should lock operational boundaries

Markdown tells the agent what good behavior looks like. The harness, the policy code, and the validation steps make that behavior real.

The New Operating Model

The next mature step in AI-assisted coding is not better prompting alone. It is repository design for agents.

The pattern now emerging across the industry is relatively clear:

• Keep a short root instruction file that maps the codebase
• Keep deep knowledge in docs, not in prompt-sized prose
• Use scoped rules when a tool supports them
• Use per-task plans or specs for bounded execution
• Back important rules with deterministic enforcement

Once you do that, the repository starts behaving less like a pile of source files and more like an environment that agents can actually operate inside.

Final Notes

Reliable AI-assisted coding needs explicit execution contracts. That remains true.

The next layer is now visible: reliable agentic coding also needs a repository control plane. Not one more clever prompt, but a durable instruction surface that survives across tools, sessions, and model upgrades.

If you are building for agents today, write the task spec. But also write the map.

Explore the source code at the GitHub repository.

See you in the next issue.

Stay curious.