How AGENTS.md turns repositories into agent-readable systems

AGENTS.md earns its place when it tells a coding agent how work actually gets done in a repository. It is not a second README, a long prompt full of personality rules, or a substitute for tests. A useful file turns tribal knowledge into instructions an agent can discover before it edits code: where to work, which commands prove a change, what boundaries it must respect, and which local conventions are expensive to rediscover.

That changes onboarding in a practical way. A new engineer still needs the product story and architecture, but an agent can stop spending its first ten minutes guessing whether the team uses npm test, a Make target, or a filtered monorepo command. The payoff is fewer plausible but wrong changes. The cost is that the team now owns another operational document, and stale instructions can be worse than no instructions.

What AGENTS.md standardizes and what it leaves open

AGENTS.md standardizes a location and a convention, not a formal configuration language. The official AGENTS.md project describes it as a predictable place for context and instructions, comparable to a README written for coding agents. The file is ordinary Markdown. It has no required fields, fixed headings, parser schema, or official vocabulary. That lightness is why several tools can support it without agreeing on one vendor's configuration format.

This distinction matters because teams often call it a standard and then assume every agent resolves it identically. The portable part is the filename, the human-readable content, and the idea that instructions can follow the directory tree. Discovery timing, maximum size, override filenames, and precedence against global settings belong to the agent implementation. Before you depend on any of those behaviors, check the manual for the tool running in your repository.

Codex offers a concrete example. Its documentation says it builds an instruction chain once per run, starting with global guidance and then walking from the project root toward the current working directory. It concatenates the files in that order, so guidance closer to the working directory appears later and can override earlier text. Codex also recognizes AGENTS.override.md, supports fallback filenames through configuration, and stops when the combined project guidance reaches its configured byte limit. Those are Codex behaviors, not universal promises made by the open format.

The official AGENTS.md site takes the broader position: put a file at the repository root, add nested files for subprojects, and let the closest relevant instructions win when rules conflict. That principle travels well. The exact implementation still needs testing. An agent that reads only the root file and an agent that discovers nested files progressively may receive different context for the same task.

Treat the format as an interface with a small common core. Write portable instructions in plain Markdown. Document tool-specific assumptions when they matter. If your automation depends on precedence, launch the actual agent from two or three representative directories and ask it to report the instruction sources it loaded. A convention becomes dependable only after you verify the consumer.

Put operational truth in the file

The best content answers questions that source code cannot answer cheaply. An agent can inspect package.json, but it cannot reliably infer which of six scripts CI treats as the merge gate. It can find three database clients, but it may not know that one is retained only for migrations. It can read a service directory, yet miss that integration tests require a local dependency and should never run against a shared environment. AGENTS.md should resolve those ambiguities directly.

A root file usually needs five kinds of information:

• A short map of the repository, including the directories that own the main applications, shared packages, generated files, and tests.
• Exact setup, build, lint, type-check, and test commands, including the narrow command for one package or test.
• Architectural boundaries that reviewers enforce but static tools cannot express, such as which layer owns persistence or which API client all network calls must use.
• Safety constraints around secrets, migrations, production resources, generated artifacts, and destructive commands.
• A definition of done that names the checks and artifacts expected for the common change types.

Specificity beats volume. "Run the tests" makes the agent search for a command and choose one. "For changes under packages/billing, run make test-billing; run the full suite only when shared schemas change" supplies a decision rule. "Follow existing style" forces pattern matching across arbitrary files. "Use the repository formatter, keep public functions typed, and do not edit generated clients" narrows the work.

Include negative instructions only when they block a failure you have seen or a risk you can explain. A hundred prohibitions compete for attention and hide the rules that protect production. If the agent repeatedly edits a generated file, state where its source lives and name the generation command. If nobody can remember why a prohibition exists, put the rationale beside it or delete it.

Do not copy whole sections of the README, contributor guide, or architecture decision records. Pointing agents to other local files is useful only when the tool can read them and the instruction says when to do so. A sentence such as "Before changing authentication, read docs/auth-boundaries.md" is actionable. A bibliography of every document in the repository is not.

Scope should follow ownership boundaries

Nested AGENTS.md files work when the repository's directory tree reflects real ownership. Put rules shared by every package at the root, then add local instructions where commands, architecture, or risk change. A frontend package may require screenshot checks and component conventions. A payments service may require an emulator, a migration check, and explicit approval before credential work. Mixing all of that into the root makes every task pay the context cost.

The usual inheritance model is additive until a local rule conflicts with a broader one. Write the local file so the conflict is explicit: "In this directory, use make test-payments instead of the root npm test command." Do not make the agent infer that a different command silently replaces the root rule. Clear override language helps humans too.

Scope can fail in two directions. A single giant root file gives an agent irrelevant instructions and may hit implementation limits. Too many nested files create a scavenger hunt, especially when directory names do not match team boundaries. I add a nested file only if at least one of these changes below that directory: the build or test workflow, the architecture rules, the release process, or the safety boundary.

Generated directories and vendored code deserve a short local warning when agents routinely enter them. "Do not edit files here; regenerate them from schemas/ with make clients" is enough. There is no benefit in repeating the root's formatting, PR, and testing sections beneath it.

Monorepos expose an awkward edge case: an agent launched at the root may not load guidance stored in a package until it works there, depending on the tool. An agent launched inside the package may receive a root-to-package chain. Test both entry points. If a root-level task can touch several packages, keep cross-package invariants at the root and package details local. That split avoids relying on discovery behavior for rules that must govern every change.

A useful AGENTS.md is short enough to inspect

A first version should fit on one screen or two and describe the normal path. Teams often respond to every agent mistake by adding another paragraph. The file then turns into an incident archive, with contradictory rules and obsolete commands. Start with the smallest set that changes behavior, watch actual runs, and expand only when evidence justifies it.

This template is deliberately concrete without pretending every repository needs the same headings:

# Repository working guide

## Repository map
- apps/web owns the customer application.
- packages/api owns request validation and persistence.
- generated contains derived clients; do not edit it directly.

## Commands
- Install: pnpm install
- Web checks: pnpm test -F web
- API checks: pnpm test -F api
- Full merge gate: make verify

## Change rules
- Keep database access inside packages/api.
- Update contract tests when a public response changes.
- Generate clients with make clients after editing schemas.

## Safety
- Never use production credentials for local tests.
- Ask before adding a runtime dependency or changing a migration.

## Done
- Run the narrow checks for the changed package.
- Run make verify when shared code or schemas change.
- Report commands run and any checks that could not run.

The failure this prevents is familiar. Without the map, an agent edits a generated client because that file contains the visible type error. Without the command distinction, it runs a quick unit suite after changing a shared schema and misses the contract break. Without the definition of done, it may describe the code change and omit the fact that an unavailable service blocked integration tests.

Notice what the template does not contain: a job title for the agent, generic advice to write clean code, a demand to think hard, or detailed syntax rules already enforced by a formatter. Those words consume context without resolving repository-specific choices. Static rules belong in linters, formatters, type systems, and CI. AGENTS.md tells the agent which checks to run and what judgment those checks cannot encode.

Commands must be safe to copy. State the directory when a command does not run from the root. Avoid placeholders if a real narrow command exists. If setup requires secrets, name the variable and the safe source without placing a secret value in the file. If a command can mutate shared data, do not present it as an ordinary verification step.

Real repositories use it as an operations manual

Public projects show that effective files look less like prompts and more like compressed maintainer knowledge. Their value lies in details a competent contributor could eventually discover, but only after reading many scripts, CI files, and review comments.

The OpenAI Codex repository's root AGENTS.md is heavily operational. In its Rust area, it names crate conventions, tells contributors to use just test instead of calling cargo test directly, requires just fmt after Rust changes, and gives package-specific test guidance. It also records less obvious build facts, such as updating Bazel data declarations when compile-time Rust macros read source-tree files. That is strong instruction design because every rule points at a concrete choice or known failure.

The same file sets size guidance for Rust modules and change sets, then gives detailed conventions for the terminal interface. Whether another team agrees with those thresholds is irrelevant. The agent working in that repository needs the maintainers' actual review expectations, not generic Rust taste. A local instruction file is the right place for those expectations when automated checks cannot cover them fully.

GitHub's awesome-copilot repository uses AGENTS.md to define its content production workflow. It maps directories for agents, instructions, skills, hooks, and workflows; lists exact build and validation commands; and specifies required front matter for several file types. It also includes a review checklist. The lesson is not to copy its structure. The lesson is to join a repository map, authoring contract, generator commands, and validation steps in one discoverable place.

LangChain's documentation repository has a docs/AGENTS.md tuned to documentation work. It explains content locations, front matter requirements, special MDX constructs, and the command used to check broken links. More useful still, it documents the real output shape of that checker and tells the reader which indented lines represent actual failures after known false positives are filtered. "Run the link checker" would leave an agent to misread noisy output; the added interpretation closes the loop.

OpenHands shows the other end of the scale. Its root file records architectural boundaries, test separation, API access rules, environment behavior, and precise regression notes. Some entries name earlier approaches that failed and say why they must not return. This can save a maintainer from watching an agent "simplify" code back into a known bug. It also shows the maintenance risk: a long file full of volatile internals needs owners and regular pruning, or yesterday's correct instruction will steer tomorrow's change backward.

These examples share a pattern. They name real paths, real commands, expected outputs, and exceptions. None depends on motivational language. The repository itself supplies the subject; AGENTS.md supplies the operating decisions that are otherwise scattered across it.

Vague instructions fail silently

A bad command usually fails in the terminal. A bad natural-language rule often produces reasonable-looking code, which makes it more dangerous. "Use best practices" can justify almost any edit. "Preserve backward compatibility" does not say which interfaces count as public. "Test thoroughly" does not identify a suite, environment, or expected result. The agent can comply in words while missing the maintainer's intent.

Rewrite vague rules as observable decisions. Instead of "avoid large changes," state when the agent should pause and split work. Instead of "be careful with the database," identify which migration operations require approval and which local database is safe. Instead of "do not break the API," name the contract test and the compatibility policy. A useful instruction lets a reviewer point to evidence.

Conflicts deserve the same treatment. Suppose the root says to run make verify, while a package file says its integration suite needs credentials unavailable in local sandboxes. The local file should say whether the agent runs a smaller command, skips the suite and reports the blocker, or asks a human. Leaving both statements in place creates a compliance puzzle. The model may choose whichever instruction is easier, and two runs may choose differently.

Staleness is the most common structural failure. Package scripts change, services move, and temporary workarounds survive long after the bug is fixed. Add AGENTS.md to the review surface for changes to commands, directory ownership, generated outputs, and CI gates. OpenHands explicitly tells maintainers to update its relevant AGENTS.md section when they change the live end-to-end framework. That coupling is worth copying: the code change and its operating instructions land together.

Do not turn prose into a weak copy of CI. If a rule can be checked deterministically, add the check. Keep the sentence in AGENTS.md only if the agent needs it to select or interpret that check. For example, CI should enforce generated-file drift; the instruction should tell the agent which source to edit and which generator to run. This division makes failures loud and keeps the document focused on decisions.

Agent onboarding and human onboarding are different

Human onboarding builds a mental model over days. People learn why the product exists, who owns each subsystem, how decisions get made, and whom to ask when written guidance ends. Agent onboarding happens at the start of a task and competes for a limited context window. It needs immediate, scoped instructions tied to the files and commands in play. Treating the two as identical produces either a shallow human guide or an overloaded agent file.

The documents should complement each other. Keep product concepts, long architecture explanations, and contribution culture in human-facing documentation. Put task execution rules and machine-relevant boundaries in AGENTS.md. When an architecture document matters only for certain work, tell the agent exactly when to read it. That gives the agent progressive context without copying an entire handbook into every session.

A good file also makes human onboarding more honest. Writing down the narrow test command may reveal that only one senior engineer knows it. Describing generated-code ownership may expose a build step that exists solely in someone's shell history. Defining which API client is mandatory may uncover several exceptions nobody has reconciled. The exercise turns hidden process into reviewable process.

It does not remove the need for judgment. An agent cannot infer business priority from a build command, and a document cannot anticipate every production risk. State where authority ends: ask before changing dependencies, migrations, public contracts, or infrastructure when those choices need an owner. An agent-readable repository is not an autonomous repository. It is a repository that makes routine decisions easy to execute and exceptional decisions easy to recognize.

This is where small AI-augmented teams gain more than convenience. When one or two engineers supervise several concurrent agent tasks, repeated explanation becomes the bottleneck. Shared repository instructions reduce that repetition and make review standards consistent. They do not compensate for weak tests or unclear ownership, but they expose both quickly.

Security rules need actions and boundaries

Security prose should tell the agent what it may read, write, execute, and disclose. Generic reminders to "be secure" have little effect. Name prohibited environments, sensitive paths, allowed test credentials, approval points, and the safe fallback when access is missing.

Keep secrets out of AGENTS.md. The file belongs in version control and may enter model context, logs, forks, and generated summaries. Document variable names and provisioning paths, never values. Do not paste internal hostnames, tokens, customer identifiers, or incident details merely to make an instruction concrete. If the repository itself contains sensitive material, the agent's sandbox and permissions must enforce access; prompt text is not a security boundary.

A strong rule pairs a restriction with a next action. "Never run migrations against production" blocks one path but leaves the task unresolved. "Run migrations against the disposable local database; for any shared environment, stop and request approval from the service owner" tells the agent how to proceed. The same pattern applies to dependency installation, destructive commands, outbound network calls, and release actions.

Separate authorization from capability. An agent may have a command available and still lack permission to use it. Conversely, telling an agent not to read a secret does not prevent a broad shell tool from exposing it accidentally. Use least-privilege credentials, isolated environments, protected branches, review gates, and command allowlists for enforcement. Use AGENTS.md to explain the workflow inside those controls.

Review injection risk too. Repository text can contain instructions written by an untrusted contributor or generated from external data. The instruction hierarchy should make trusted maintainer guidance outrank arbitrary files, and agents should treat source content as data unless the trusted guide says otherwise. Keep high-impact authorization in the user request and platform policy, not in a nested Markdown file that any dependency or test fixture could imitate.

Test the instructions like an interface

You can evaluate AGENTS.md without building a formal benchmark. Pick representative tasks, record the agent's behavior before and after the file, and look for fewer wrong-path edits, fewer unnecessary commands, and clearer verification reports. The sample should include a routine change, a cross-package change, and a task that must stop for approval.

A simple repository audit gives you a reproducible starting point:

$ find . -name AGENTS.md -print
./AGENTS.md
./apps/web/AGENTS.md
./services/payments/AGENTS.md

$ wc -c AGENTS.md apps/web/AGENTS.md services/payments/AGENTS.md
1840 AGENTS.md
 912 apps/web/AGENTS.md
1107 services/payments/AGENTS.md
3859 total

The output shape matters more than these example numbers. The first command reveals where scope changes. The second exposes files growing large enough to deserve review. Then run the same agent from the root and from each representative package. Ask it to list active instruction sources, summarize conflicts, and name the verification command for a small change. Compare its answer with the team's intent.

Review the file through failure reports, not taste. When an agent chooses the wrong test, decide whether the command was missing, ambiguous, outside the loaded scope, or contradicted by another file. When it ignores a rule, check whether twenty lower-value rules buried it. When it follows stale guidance exactly, fix the ownership process rather than adding another warning.

Track changes to AGENTS.md in ordinary code review. The reviewer should execute new commands, verify referenced paths, inspect nested conflicts, and ask whether a deterministic check belongs in CI instead. A quarterly calendar reminder helps, but event-driven maintenance is better: directory moves, script changes, CI changes, dependency policy changes, and incidents should trigger a review immediately.

In my Team & AI Audit, I treat repository instructions as operating infrastructure because reducing a team from many manual handoffs to one or two AI-augmented engineers only works when agents receive the same tested constraints. The file is cheap; deciding which knowledge deserves to become a durable rule is the real work.

Adoption should start with observed friction

The fastest safe adoption path is to capture the five decisions agents and new engineers repeatedly get wrong. Pull them from recent review comments, failed runs, onboarding messages, and CI surprises. Convert each into a scoped instruction with a command, path, boundary, or expected result. Commit that first version and use it on real tasks for a week.

Do not begin by merging every existing agent-specific file into one universal document. Compare them first. A CLAUDE.md, custom IDE rule, and CI bot prompt may have different scopes and precedence. Extract the repository facts that should survive a tool change, place those in AGENTS.md, and retain tool-specific configuration only where the behavior truly differs. Symlinks can ease migration when two tools accept equivalent content, but a symlink does not reconcile incompatible semantics.

Assign ownership. The platform or developer-experience team can own the root, while package owners review nested files. Require changes to an instruction when the command or invariant it describes changes. Delete rules after automation makes them redundant, unless the agent still needs a pointer to the automated check. A short current file beats a comprehensive history.

AGENTS.md is worth adopting when agents already work in the repository or will soon. It gives every run a shared starting point and makes multi-agent work less dependent on one engineer repeating the same corrections. It is not worth treating as a compliance project before you have observed agent work. Without real tasks, teams write abstract rules that sound sensible and change nothing.

The first useful commit is not "add the standard." It is "teach agents how this repository proves a change is safe." If the file can answer that for each owned area, onboarding becomes faster for machines and clearer for people. If it cannot, add the missing command or boundary, then make someone responsible for keeping it true.