AGENTS.md is a markdown file, conventionally placed at the root of a repository, that gets loaded into an AI coding agent’s context on every prompt to convey project-specific conventions and constraints. Common coding agents can auto-generate one via an /init-style command, which scans a codebase and produces a description of its directory structure, tech stack, and testing conventions.
Origin and Naming
One adopter’s account fills in how the file came to carry the name it has. Taming Agents in the Mercari Web Monorepo records a team finding the standard at a point when it was AGENT.md, singular — described there as an RFC proposed by Sourcegraph through its AmpCode project — and consolidating its existing Cursor and Claude rules into one such file, while the rest of the team wondered about that RFC’s longevity. The post then reports that OpenAI secured the agents.md domain, which it describes as the only thing that had been holding the standard back from the plural wording, and which was also the filename OpenAI’s own Codex had already been using. It credits OpenAI’s backing with the standard gaining much more traction among the tools that team used, and the team adopted the pluralized form as its single source of truth. This is one team’s account of what it observed as an adopter, not a participant’s account of how the standard was designed, and the announcements it refers to are not themselves among this wiki’s sources.
That post also describes a practical consequence of adopting it in a codebase that already had per-tool rule files: CLAUDE.md and many other rule files simply became symlinks to the main one, so the pre-existing formats kept working without the content being maintained twice.
A later account adds where the standard ended up.
AIに渡す指示書の役割分担: AGENTS.md/SKILL.md/DESIGN.mdと仕様駆動開発の現在地 names Sourcegraph’s Amp team as its starting
point — agreeing with the adopter account above on where it began — and describes it as since being
promoted jointly by OpenAI, Google, Cursor, Factory and others, before being donated to the Linux
Foundation in December 2025. So the question that adopter account leaves open, whether one vendor’s
RFC would last, was answered by moving the standard out of any single vendor’s hands. That
post also gives the symlink arrangement as the format project’s own recommended pattern rather than
one team’s expedient: because Claude Code reads CLAUDE.md and not AGENTS.md, the recommendation is
to make AGENTS.md the real file and CLAUDE.md a symlink to it. It characterises CLAUDE.md as
simply the Claude-specific AGENTS.md.
Usage
Addy Osmani’s post “Stop Using /init for AGENTS.md” summarizes research finding that a human-authored AGENTS.md recording genuinely non-discoverable, operationally significant facts (e.g. “use uv for package management”) measurably changed agent behavior and improved task success, while an auto-generated file — typically a codebase overview the agent could otherwise discover by reading the repository directly — was found to add cost without improving, and in some cases while reducing, task success. Osmani’s post also describes an “anchoring effect”: once a technology or pattern is mentioned in the file, it stays in context on every subsequent prompt, which can bias the agent toward it even where it is no longer the current convention.
Another post by Osmani cites OpenAI’s Codex documentation as recommending an AGENTS.md file to give an agent consistent expectations about which tests to run, lint rules, dependency policies, and documentation requirements — likened there to onboarding a new hire with a map of conventions before they start writing code. That post also frames updating AGENTS.md and related checklists as the final “retro” step of a repeatable orchestration loop, so the next run starts smarter (Your AI coding agents need a manager).
GitHub adopted the file as one configuration surface for custom agents in VS Code, announced
alongside Agent HQ (see Introducing Agent HQ: Any agent, any way you work). It describes
AGENTS.md files there as source-controlled documents for setting clear rules and guardrails —
its examples being “prefer this logger” and “use table-driven tests for all handlers” — and states
the point as shaping Copilot’s behaviour without re-prompting it every time.
GitHub’s documentation for GitHub Copilot Code Review places the file
among four customization surfaces and separates them by scope, which is the clearest vendor
statement this wiki holds on when not to use it. .github/copilot-instructions.md holds
repository-wide always-on rules specific to Copilot; path-specific *.instructions.md files under
.github/instructions/ hold always-on rules for particular paths, file types or directories;
AGENTS.md, read from the repository root, holds always-on rules meant to be shared across AI
tools and agents; and skills under .github/skills/ hold task-specific workflows run on demand or
when relevant. GitHub compresses the distinction into four rules of thumb — “Copilot, always know
this for this repository”, “Copilot, always know this when working in these paths”, “Any agent,
always know this”, and “Do this when needed” — so what marks AGENTS.md out on this account is
not scope within the repository but reach across tools, the same property the adopter account
above was choosing it for. The same documentation states that during a pull request review Copilot
reads custom instructions, agent instructions and skills from the head branch rather than the
base branch, so a change to any of them can be tested in the pull request that introduces it
without being merged first.
Agentic Software Engineering: Foundational Pillars and a Research Roadmap discusses project-level configuration files such as CLAUDE.md, .clinerules, and AGENT.md as an early, grassroots practice of loading “institutional knowledge” before every agent task — codifying style guides, architectural constraints, and lessons learned into a continuously improving “employee handbook” for AI teammates. It frames this practice as an early example of what it proposes formalizing as MentorScript, and states the community has no consensus on what such files should contain or the appropriate level of detail, arguing that future work involves not only defining more formal languages for this purpose but also discovering best practices for these files’ effective use.
A practitioner account puts the file to a use none of the others describes at this depth: not only
as context the agent reads, but as the place whole procedures live.
人間は意図、AIは実装：Codexが導く「要件を伝えるだけ」のAI駆動開発ワークフロー writes AGENTS.md at project
initialization as what it calls the AI’s memory, holding the project overview, the folder layout,
the documents that must be consulted, the working rules and the current status. The four working
rules that post records in it are plan before acting and execute after approval, present three
options when planning or proposing, check and update the relevant specification before
implementing, and update the per-story context file on completion. Alongside those it stores the
auto-generation rules themselves — the phrases that trigger a routine, the steps to run, the
folder and file layout to produce, and the shape of the files that result. The consequence it
claims is on the prompt rather than on the agent: because placement and procedure are already
written down, a prompt can state a requirement (“read vision.md and generate the user stories”)
instead of enumerating output paths, and the author’s stated rule of thumb is that the more these
rule files are filled in, the simpler the prompts get and the better the output. That is one
engineer’s demonstration on a sample project, with no measurement behind it.
The file’s spread across tools has a measurable side effect on research into who uses which agent.
Agentic Much? Adoption of Coding Agents on GitHub, a study of coding agent adoption
across 128,018 GitHub projects, uses agent guidance files as one of its markers of adoption, and
describes AGENTS.md as a simple open format originally used by Codex and since adopted by several
agents, including Jules, Cursor, Aider and Copilot. For that reason the authors treat the file’s
presence alone as insufficient to identify which agent a project uses, and count its users in a
separate “Generic” category rather than crediting them to Codex, while suspecting that most of that
usage stems from Codex. The same study notes that guidance files of this kind are generally markdown,
are added to the prompt before it is sent to the model, and are usually committed so that they are
shared among developers — but that some projects keep agent configuration out of the repository, for
example by listing it in .gitignore.
When It Applies
Osmani’s “Stop Using /init for AGENTS.md” frames a good AGENTS.md as a living record of codebase friction rather than a permanent configuration: a line is added when an agent repeatedly makes the same mistake, and removed once the underlying problem (a confusing directory structure, a build pipeline that should catch something automatically) has been fixed instead. Osmani states the practical filter as: if the agent could discover a fact by reading the code, it doesn’t belong in the file. His post also treats a single, static, repository-root file as a structural limitation for any codebase past a certain complexity, since a flat instruction set cannot condition its content on what kind of task is being run, and proposes a hierarchy of directory- or module-scoped files, automatically maintained, as the intended replacement. It further describes a more elaborate three-layer version of this idea (a minimal routing file, task-scoped skill files, and a maintenance subagent), noting that no major coding agent yet exposes the lifecycle hooks needed to build that fuller architecture cleanly.
This wiki’s sources do not agree on what belongs in the file. Osmani’s post sets a discovery filter — a fact the agent could get by reading the code does not earn a line — which its author draws as the practical lesson of research finding an LLM-generated context file to reduce task success slightly while raising cost substantially. The practitioner account above stores the folder layout, the working rules and the auto-generation procedures in it, which is a good deal more than that filter would admit, and argues the opposite direction: that the fuller the rule files, the simpler the prompts and the better the output. The two are not measuring the same thing — one reports an experimental result about task success, the other one engineer’s working method on a sample project — and neither engages the other, so both are recorded here rather than reconciled. What separates them may be purpose: a discovery filter is about what an agent needs to know, while procedures written to be triggered are about what it should do, which no amount of reading the code would supply.
One team has put into practice something close to the minimal routing file Osmani’s layered design starts from, and its shape is worth recording because it sidesteps that disagreement rather than settling it. In Taming Agents in the Mercari Web Monorepo the root AGENTS.md holds almost nothing itself: each of its sections is a heading and a pointer to a separate document under docs/ — build and test commands, code style and standards, project architecture, authentication patterns, testing strategy. The post singles out the architecture document as crucial given its repository’s modular structure, and states the cost of omitting that context as most tools’ output having to be completely restructured by the developer unless the same initial context is carefully prompted every time. It also teaches the agent the project’s design system in emphatic ALWAYS/NEVER terms — always import components from the design system package rather than from source files, never add inline styles on a design system component or native HTML element — the stated reason being that the project must follow that design system and cannot rely on vibe-coded CSS.
That team’s answer to keeping such files current is to delegate it: for any pull request with significant impact on higher-level design, an engineer runs an agent against the changeset together with the rules folder and has the model itself suggest edits to the rules, or point out inconsistencies in the code. Its stated reason for automating this is that editing a non-local markdown file in a separate folder is tedious for an engineer focused on a task, and it calls the result self-enforcing and self-updating documentation. That is the team’s own characterization, offered without measurement, and what it was building at the time of writing — an agent on every pull request flagging code that diverges from the rules — had not yet shipped.
A later post on long-running agents gives the same file a further design principle for a developer running long or overnight coding jobs: treat AGENTS.md like a pilot’s checklist, kept short, with every line earned by a real prior failure. It separately describes Anthropic’s own scientific-computing agents using CLAUDE.md in a comparable role, as a living plan the agent itself edits as it learns, paired with a CHANGELOG.md acting as portable lab notes (see Ralph Loop).
Security Considerations
The property that makes the file useful is also what makes it a target. Because an agent loads these files as trusted project context by design, anything able to write one into the working tree can supply instructions carrying that standing. An NVIDIA AI Red Team report demonstrated this against Codex: a malicious Go dependency, executing during the build step as any dependency can, wrote an AGENTS.md whose directives claimed precedence over the user’s own request, and the agent followed them in preference to the task it had been given. The report is explicit that the file’s trust model is deliberate rather than a flaw, and that the attack presupposes a compromised dependency — which already implies code execution — so what it adds is a new use for that access rather than a new way to obtain it.
Among the mitigations it proposes, those aimed at the file itself are about its integrity rather than its content: limit which files an agent may read and write, enforce integrity controls on configuration files specifically, using endpoint security or centralized configuration management, and alert on unexpected file modifications. It proposes others that are not about the file at all — pinning exact dependency versions and scanning packages, auditing agent-generated pull requests with dedicated security agents, and scanning and guardrailing the model itself. See Indirect AGENTS.md Injection for the attack itself.
Related Terms
Harness Engineering, Agentic Context Engineering, Ralph Loop, Indirect AGENTS.md Injection, Indirect Prompt Injection, OpenAI Codex