Will Ayers
← Back to all postssystems /

AGENTS.md Is a Communication Protocol

How I use AGENTS.md to define clear communication, bounded autonomy, and repeatable engineering behavior for AI coding agents.

aiagentsworkflowcommunication

Most examples of AGENTS.md begin with build commands, test scripts, and code conventions. Those details are useful, but they leave out a larger opportunity.

I use AGENTS.md as a working agreement.

It tells an AI coding agent how we communicate, when it can act, when it must ask, how it should recover when a plan stops making sense, and what evidence it needs before calling work complete. Framework preferences and validation commands are part of the file, but they sit inside that broader operating system.

This is the first article in a series about building systems that make AI more useful. It covers the complete shape of my setup without publishing the exact instructions. Later articles will go deeper on the individual protocols, beginning with reference codes and bounded autonomy.

The file is not a bigger prompt

A prompt describes the task in front of us. AGENTS.md describes the recurring relationship around those tasks.

That difference matters. I do not want to restate the same expectations every time I open a session:

  • answer questions before changing code
  • make small, reversible changes without waiting for permission
  • ask before changing authentication, billing, migrations, secrets, or deployment configuration
  • run focused validation before claiming success
  • do not commit or deploy unless explicitly asked
  • adapt a plan when implementation reveals better information

These are not details of one feature. They are rules for how work moves from intent to implementation.

The open AGENTS.md format gives coding agents a predictable place to find repository instructions. It is plain Markdown, has no required schema, and supports nested files where the closest instructions can take precedence. That flexibility makes it useful for more than repository onboarding.

A useful mental model is:

1user request
2  + global working agreement
3  + repository instructions
4  + local package conventions
5  + source code and validation
6  = bounded task context

The request still has the highest practical importance. The instruction files reduce everything that should not need to be renegotiated inside it.

Start with observable communication behavior

Instructions like "be concise" or "communicate well" sound reasonable, but they are difficult to apply consistently. Concise compared with what? What should happen when the shortest answer omits an important risk?

I prefer observable rules:

1- Lead with the answer, outcome, or most important information.
2- Use plain, specific language.
3- State each fact once.
4- Match the level of detail to the task.
5- Challenge incorrect assumptions directly and explain why.
6- Include file paths when discussing changed files.

I also include negative patterns:

1- Do not repeat the same conclusion in multiple sections.
2- Do not add praise or agreement that does not help the decision.
3- Do not turn every response into a long explanation.
4- Do not use analogies when the concrete system can be described directly.

Positive and negative examples work together. The positive list defines the target. The negative list removes common interpretations that technically satisfy the target but produce poor collaboration.

This section is not about making an agent sound like me. It is about reducing communication overhead while keeping important uncertainty visible.

Give long discussions stable reference points

The most useful communication rule in my setup is a small notation system.

When a response contains three or more options, decisions, questions, risks, or recommendations, each item gets a short code:

1O1  Keep content in the repository
2O2  Move content to a hosted CMS
3O3  Fetch content from a source repository at runtime
4

5K1  Runtime content introduces an external production dependency
6K2  Build-time content requires a deployment to publish changes

Those references remain stable for the rest of the conversation.

Instead of replying with:

Use the option where content stays in the repository and gets included in the production build, but make sure we account for needing a new deployment whenever an article changes.

I can say:

Take O1. K2 is acceptable.

The point is not saving a few tokens. The point is preserving identity.

Long descriptions are easy to paraphrase differently. "The second option" becomes ambiguous after another option is inserted. Quoting a paragraph creates more text for both sides to parse. A stable code lets us refine, combine, reject, and revisit ideas without losing which idea we mean.

The prefixes carry useful semantics:

  • O for an option
  • D for a decision
  • Q for a question
  • R for a recommendation
  • K for a risk

The exact letters matter less than using them consistently. Mine stays intentionally small because the notation only works if it remains easy to use.

There are two important constraints. First, codes are unnecessary for one or two simple items. Adding them everywhere creates ceremony instead of clarity. Second, they should disappear from copy intended for an email, article, or customer message. They are coordination metadata, not part of the final artifact.

Define autonomy by consequence

"Always ask before editing" makes an agent slow. "Use your best judgment" leaves too much room around consequential actions.

I define autonomy based on reversibility and risk:

1- If the task is clearly scoped and reversible, make the change.
2- If multiple directions have meaningful tradeoffs, explain them and ask.
3- Ask before modifying authentication, billing, data deletion, migrations,
4  deployment configuration, or secrets.
5- Prefer the smallest useful change that solves the problem.

This gives the agent room to fix a typo, update a component, or run a test without asking for procedural approval. It also creates a hard boundary around changes where a technically valid implementation can still carry business or operational consequences.

The goal is predictable autonomy, not maximum autonomy.

An agent should know which decisions have already been delegated and which still belong to the person responsible for the system.

Treat questions as read-only

Natural language does not reliably distinguish curiosity from instruction.

Consider:

Could this loader be simpler?

A person may read that as a request for an opinion. An action-oriented agent may interpret it as permission to rewrite the loader.

My working agreement makes the distinction explicit:

1Questions are read-only. Answer first and do not edit files unless the user
2asks for a change.

This rule has a high return because it protects the thinking phase. We can explore feasibility, tradeoffs, and architecture without creating a patch that anchors the discussion around one implementation.

If the change is obvious and small, the agent can offer to make it. It still answers the question first.

Plans are hypotheses, not contracts

Agents are good at producing plausible plans before they have inspected every implementation detail. The plan can become wrong as soon as the work reaches an unexpected API, dependency, or data constraint.

I want planning, but I do not want blind plan completion.

1- Treat plans as working hypotheses.
2- Adapt when implementation reveals a better path.
3- Pause when the remaining plan becomes wrong, risky, or unnecessarily complex.
4- Make small corrections and summarize them later.
5- Ask before changing scope, architecture, data models, dependencies,
6  migrations, or user-facing behavior.

This creates two lanes for course correction.

Small implementation discoveries can be handled immediately. Material changes return to the person making the product or engineering decision. The boundary prevents both failure modes: following a stale plan and silently replacing it with a different project.

Encode engineering preferences at the right level

Some instructions belong everywhere. Others only make sense inside one repository.

My global working agreement contains durable preferences such as:

  • use type safety instead of broad casts
  • prefer existing project conventions over personal defaults
  • avoid dependencies for small utilities
  • add dependencies when they meaningfully reduce complexity
  • keep comments accurate when behavior changes
  • write focused tests for real risk rather than broad test volume

The repository-level file contains facts about the specific system:

  • framework and runtime
  • route and data-loading conventions
  • source directories
  • generated files
  • package commands
  • validation sequence
  • deployment constraints

A large monorepo may add another AGENTS.md inside an application or package. The format documentation and GitHub Copilot documentation both describe nearest-file behavior for scoped instructions.

That hierarchy keeps a React preference from leaking into a Go service and keeps one package's test command from becoming a global rule.

Make completion observable

An agent saying "done" is not evidence that a change works.

The working agreement should define the expected validation behavior:

1- Run focused tests, typechecks, or linters when relevant.
2- Validate the user-facing behavior when practical.
3- Do not add broad smoke tests without a concrete risk to protect.
4- If validation is slow or environment-dependent, say what remains to run.

This does not mean running every command after every edit. The validation should match the change.

A type-only refactor may need a typecheck and focused tests. A responsive interface change may need browser checks at desktop and mobile widths. A content edit may need front matter parsing, link checks, and a production build.

The important part is that success has an observable basis. OpenAI's early Codex guidance made a similar connection between repository instructions, configured environments, reliable tests, and verifiable agent work.

Put irreversible workflow actions behind explicit approval

Editing a local file and deploying production are not equivalent actions.

My Git rules state that the agent should not commit unless asked. Deployment, secrets, migrations, and destructive data operations have separate approval boundaries. When a commit is requested, the agent checks for unrelated working-tree changes and keeps the commit focused.

These rules prevent a common category error: treating "the implementation looks good" as approval to publish it.

They also make the final handoff clear. The agent can report:

1Implementation complete
2Validation passed
3Changes remain local and uncommitted

That is more useful than leaving the state implicit.

Match the process to the task

AI tooling makes it easy to add ceremony: a plan, several subagents, a research panel, a review panel, a generated specification, and a large test suite for a small change.

My instructions explicitly push against that behavior:

1- Use the smallest process that safely completes the task.
2- Do not delegate work a single agent can finish in one pass.
3- Use parallel work for independent investigation, adversarial review,
4  or separate expertise.
5- Prefer direct implementation for small, reversible changes.

The system should become more rigorous as uncertainty and consequence increase. It should not become more elaborate simply because the tools are available.

Maintain the agreement from real failures

An AGENTS.md file should be living documentation, but not a diary of every agent mistake.

I add a rule when three conditions are true:

  1. The problem is likely to happen again.
  2. The desired behavior can be stated clearly.
  3. The rule will apply across enough tasks to justify permanent context.

I remove or revise rules when they become stale, overlap with stronger instructions, or create more exceptions than useful behavior.

Contradictions are especially expensive. An agent cannot reliably follow "always act autonomously" and "always ask before changes" at the same time. The agreement needs explicit precedence and narrower boundaries rather than more emphatic wording.

A compact starting structure

Do not copy someone else's complete AGENTS.md and treat it as your setup. A working agreement encodes personal tradeoffs: how much autonomy you want, what risks require approval, how you make decisions, and what good communication means to you. Rules that work well for one person or team can create friction for another.

Borrow useful sections and patterns, but rewrite each rule around how you actually work. If you cannot explain which recurring problem an instruction prevents, it probably does not belong in the file yet.

With that in mind, a useful first version does not need to be long:

1# Working agreement
2

3## Communication
4

5- Lead with the answer.
6- Use plain, specific language.
7- Label three or more options, decisions, questions, or risks with stable codes.
8

9## Autonomy
10

11- Make clearly scoped, reversible changes without asking.
12- Ask before consequential or difficult-to-reverse changes.
13- Treat questions as read-only.
14

15## Engineering
16

17- Follow existing repository conventions.
18- Prefer the smallest useful change.
19- Keep types, tests, and documentation aligned with behavior.
20

21## Validation
22

23- Run checks relevant to the change.
24- Report what passed and what could not be verified.
25

26## Git and deployment
27

28- Do not commit, push, or deploy without explicit approval.
29- Call out unrelated working-tree changes before committing.

From there, add repository architecture and commands. Expand the agreement only when repeated work shows that a missing rule would improve decisions or reduce friction.

Where the series goes next

This article is the overview for a planned series on AI working agreements. The next entries will go deeper on:

  1. Reference codes as a low-friction protocol for long technical decisions
  2. Designing autonomy boundaries around reversibility and consequence
  3. Turning validation into executable instructions for agents
  4. Layering global, repository, and package-specific context
  5. Maintaining instruction files without building a policy landfill

Each article will link back to this overview, and this roadmap will become the index as they are published.

The larger idea is simple: better models help, but collaboration quality also depends on the system around the model. A good AGENTS.md makes that system explicit, inspectable, and easier to improve.

Resources