AGENTS.md Considered Harmful

Yesterday Anthropic yielded to common conventions over exclusive proprietary instructions, and adopted AGENTS.md as a standard location for placing instructions targeted at AI agents. In general, open, shared conventions are helpful. The larger problem is that the idea of AGENTS.md indicates a deeper issue: the lack of disciplined documentation whether directed at humans or AI assistants. Trying to cordon off the problem instead of addressing it head-on is short-sighted, and will only perpetuate the “knowledge gap” that most projects carry already.

The title “Considered Harmful” is somewhat tongue-in-cheek, reflecting the decades of humorously flamboyant articles using this cliché to make a point. I'm not suggesting that AGENTS.md is directly harmful to a project or raises security risks (at least not by its mere presence). But when Anthropic announced yesterday that “Claude will check for and use AGENTS.md”, The Register was enthusiastic in its article, Anthropic decides to support OpenAI's markdown instructions spec:

Anthropic on Friday surprised the developer community by supporting rival OpenAI's mechanism for passing marching orders to AI agents. This makes life easier for folks who use both platforms. … Until now, developers who use Claude Code alongside OpenAI Codex or other non-Anthropic tools have had to maintain two sets of Markdown instructions for their AI agents: CLAUDE.md and AGENTS.md, not to mention project-specific versions of these files.

On its face this is indeed good news: open interoperability conventions help an industry grow better than do proprietary files. I'm a proponent of open file formats: I was a co-author and the co-chair of the technical group that put out the Open eBook Publication Structure, which later became EPUB—an open publishing pipeline storage format for electronic books. Settling on common conventions is a fine thing. But a lurking problem is revealed when we ask ourselves why AGENTS.md needs to exist at all.

The Dearth of Project Documentation

A recurring theme of my posts on this site will be how the new AI age impacts both humans and AI agents in the field of leadership. On the human side, sadly people have been horrible at documenting their projects. Even at some of the top tech companies, I've seen production projects in which the README file was not only stale, it consisted of only a few lines—the same template that some project generator produced years before. The project issue trackers are often full of features or bugs in which the entire “description” is simply a terse ticket title.

The need for AGENTS.md is a symptom of a lack of documentation that has existed for decades. With AI agents based upon LLMs, we have been forced into the realization that we have to share knowledge about the project, or the agents won't “know” what to do. But why do we need a special file to share this knowledge with AI agents? Why can't teams have the discipline to record knowledge in a form that can be used by humans as well? Now that we have AI, it would be possible to coax the agents to produce this documentation for us. AGENTS.md merely hides the documentation problem by tucking away this deficiency and placing it in a single file that is inadequate as a long-term solution.

AGENTS.md on Its Own Terms

Let's take a step back and look at the official AGENTS.md site to find out why the file exists in the first place. The site purports to answer that very question front and center:

Why AGENTS.md?

README.md files are for humans: quick starts, project descriptions, and contribution guidelines.

AGENTS.md complements this by containing the extra, sometimes detailed context coding agents need: build steps, tests, and conventions that might clutter a README or aren’t relevant to human contributors.

So: README.md files are for humans, and AGENTS.md is for AI agents. But … why? The modern AI era is based upon Large Language Models (LLMs), and agents are in many ways better and faster than we are at reading instructions in bulk. Why is it that we need two files: one to talk to humans, and another to talk to AI agents?

Let's explore further by looking at the example the site gives of a useful AGENTS.md file:

# Sample AGENTS.md file

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.

## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Now think back 10 years ago when we only had humans working on our teams. If you were joining a team, would you find the information in the above AGENTS.md file helpful? Of course you would! Your only surprise would have been that someone had taken the time to actually document this in the first place, because project documentation historically does not carry such well-organized information. (The reasons are varied, from humans not wanting to do the “boring parts”, to managers who don't give them time to work on “non-customer-facing stuff” even if the developer wants to.) All that information is useful both to humans and to agents.

The Need for Separate, Semantically Distinct Files

An immediate response to my observation is probably, “but we don't want all that stuff in a README”. To that I would agree heartily. But just because it shouldn't be in the README doesn't mean it should be targeted only to agents. Should we hide from developers instructions for testing, or should conventions for creating pull requests remain undocumented?

Going further, the same argument that this information should not be in the README is an argument that this information should not be combined into any one single file in the first place! If someone were hired solely for curating documentation in a project, even before modern AI agents existed, the curator would immediately recognize that this guidance belongs in separate files, each with a semantic purpose. Here is one possibility for illustration:

dev/docs/setup.md
# Project setup

## Dev environment tips

- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
dev/docs/testing.md
# Testing instructions

- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
dev/docs/process.md
# Development process

## Pull requests

### PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.

Those files would be fleshed out as needed. Show me one developer who would not find that information useful. What part of it is specific to agents?

The Fallacy of a Unique Need

The motivation for AGENTS.md seems to be that “AI agents need something different than humans”. AI agents can certainly read things much faster than humans. But even if humans can't read all the relevant documents in a matter of seconds, don't humans still need to know which specifications and designs are relevant? Couldn't a table of contents in a README be used both by humans and agents to know what needs to be read, to discover the basis on which the implementation will be made?

Perhaps another objection might be that “AI agents need a special language”. That is utterly false. LLMs were trained on human language. They are excellent at comprehending well-written human language. What might give rise to this misconception is that even the current cutting-edge LLMs produce outrageously horrible human-language prose. Maybe subconsciously there is an aversion to having the README full of slop. This is indeed a concern: just look at the monstrosity that Claude Opus 5 (on “max” reasoning level) produced today in a specification (shown here verbatim):

The rule widens what an import covers rather than postponing what it already covers — a fact intake reads is recorded on the run that reads it, a later pass having a source to read only if one survives.

That is indecipherable. The solution is not to have an empty human-authored README alongside an AI-authored AGENTS.md full of verbose cruft. If AI outputs an unreadable mess, it is because companies producing the models have not made prose output a priority. If an LLM can write complex logic in Rust, it can be fine-tuned to write readable documentation.

The Fallacy of a Single File

The supposed need for an AGENTS.md rests on the root cause of a lack of documentation, and the fallacy that it should all be crammed into a single file. Projects with good, extensive documentation typically have a well-structured, consistent layout of documentation files, reflecting a division of semantic concerns for carrying project knowledge. Reaching for a single AGENTS.md is short-sighted in that it avoids thinking of a standardized set of files that carry the recurring things projects need documented, such as setup, testing, and change-tracking submission.

AGENTS.md standardizes little more than a filename. But we already have README.md as a standard filename for documentation. (I prefer readme.md because UPPERCASE.ext is an obsolete holdover based upon ancient assumptions, but that is a soapbox for another day.) The problem is that README.md content is typically inadequate and inconsistent.

Unfortunately AGENTS.md provides no path to address that problem: as the use of AGENTS.md explodes, I predict that you will see that the contents in many of these files will be both inadequate and inconsistent—and worse, they will drift from similar instructions to humans. AGENTS.md will turn into a grab-bag of off-the-cuff stuff people think of to tell agents. Some teams' projects will have good AGENTS.md content. Most teams will have arbitrary and inconsistent AGENTS.md content.

AI agents can help us with the historically inadequate documentation humans produce. The solution is to guide agents to produce documentation usable for themselves and for humans. That solution is not a single file.

Another objection to a dual-use source of documentation might be that “the breadth of repository layouts makes a README troublesome for agents, because projects are all different.” Inconsistent project documentation organization across projects is in fact the root problem. There are few conventions for where extensive, categorized documentation should be found, and that is a problem that AGENTS.md will not solve. Even if you give instructions to AI in AGENTS.md, where do you put the specifications? Where do you put the design documents? Outside of a few general directions such as a README or a docs/ directory, most projects decide from scratch where to place documentation files and what they contain—and often the places chosen are different across projects. If we introduce AGENTS.md into the mix, many projects won't take the time to consider some reasonable organizing layout ahead of time, but instead accrete artifacts, throwing some link to them in AGENTS.md thinking that “the agent will figure it out”.

A Place for Everything

Someone (Benjamin Franklin is one among many possible authors) coined the phrase, “A place for everything and everything in its place”—the idea that if you have a convention for storing things and keep things in their conventional location, it's easier to find them. Tools such as Maven exemplified this with “Convention Over Configuration”, as explained nicely by Sonatype. AGENTS.md is a small attempt at this sort of standardization, and it's indeed welcome that Anthropic is following a convention rather than trying to promote a proprietary approach. But the solution to missing semantics does not lie in a single file.

A better approach would be to standardize on a set of conventions for general documentation across a project that is useful for humans and AI agents at the same time. Here are some directories and files such conventions might describe:

This list is in no way intended to be exhaustive, fully considered, or even a proposal. Instead I present them as examples of the type of conventions that could be established so that humans and AI agents would need to be told less, and instead would know where to look to find the answers related to the project.

Jekt as a Case Study

My Jekt™ context architecture is a case study of how an open, common set of conventions for well-organized and semantically significant artifacts can serve to carry project knowledge across development cycles. Currently Jekt is focused on producing and preserving project tracking information such as tickets, plans, design documents, minutes, comments, summaries, and related material. It stores files in a .jekt/ directory; a developer can browse the contained files in an editor, and an AI assistant can read and update those same files during development. A small project might have the following structure after a ticket has been planned and implemented. You can read more in the Jekt Primer.

.jekt/
├── readme.md
├── projects/
│   └── recipe/
│       └── description - Recipe App.md
├── tickets/
│   └── recipe-1/
│       ├── description - Ingredient Scaling.md
│       ├── description.yaml
│       ├── minutes.md
│       ├── summary.md
│       ├── plans/
│       │   └── 2026-05-18-quantity-scaling.md
│       ├── designs/
│       │   └── Quantity Model.md
│       └── comments/
│           └── 2026-05-19T14-30-00Z.md
└── releases/
    └── 1.2.0/
        └── description - Spring Update.md

Jekt is a small step in the direction of a conventional set of interoperability files for humans and agents. The project-tracking orientation of the current Jekt Specification is complementary to the type of project-wide information I described earlier in this article (whether it is stored in AGENTS.md or in individual, semantic artifacts as I advocate). Jekt may eventually grow to include and prescribe artifacts for the latter type of information as well. In a perfect world, industry tool vendors would recognize the need for a larger set of file conventions outside of AGENTS.md and come together to curate and publish those conventions to help everyone.

Jekt doesn't need to have some AGENTS.md file explaining what the state of the project is. Rather, a small “ambient” set of instructions (potentially placed in a skill in an upcoming Jekt improvement) explains what Jekt is and crucially where to find information about the state of development, such as ticket location, metadata filenames, common locations for designs, where releases are defined, etc. Here's an excerpt of the current Jekt ambient instructions; see the Jekt Reference Prompts for more. (A Jekt VS Code Extension is coming soon.)

# Jekt Ambient Instructions

Jekt is a context architecture for software projects. … A repository uses **Jekt** if it contains a `.jekt/` directory at its root. Jekt stores tickets, plans, designs, minutes, and other semantic working context as plain files. …

…

All files are optional. Tickets, releases, and projects share the same description form: a prose file `description - {Label}.md` and a structured metadata file `description.yaml`. The **label** is a short Title-Case lexical handle (the trailing portion of the description filename); the **heading title** is the level-one heading text of the prose file. Ad-hoc files at an entity root are tolerated.

## Artifact Roles

- **Description** — scope and intent of an entity (ticket, release, or project); label from filename, heading title from the prose file's `#` heading.
- **`description.yaml`** — structured metadata for the containing entity; an empty file is the legal degree-zero state asserting existence with no properties yet recorded.
- **Minutes** — append-only log of significant events (mental-state diff).
- **Summary** — retrospective synthesis near completion.
- **Plans** — ephemeral, file-first execution context for current work.
- **Designs** — durable reasoning that explains why a design is correct.
- **Comments** — timestamped entries for team interaction and discussion around the ticket. Other roles traditionally absorbed into comments by issue trackers (significant events, designs, summaries) belong in the artifacts above.
- **TODOs** — low-ceremony seeds of deferred work.

…

From AGENTS.md to Conventions

If the principles I advocate here were adopted, there would be little need for an AGENTS.md file other than to orient the agent by explaining where the project documentation is conventionally stored. As projects grow and AGENTS.md becomes overflowing with arbitrary information, it is inevitable that teams will begin splitting out information into separate files, and placing pointers to them in AGENTS.md. However that process in many cases will be haphazard and inconsistent—even though the common semantic patterns are largely the same across common project types.

A living, curated set of conventions for file locations would not stifle documentation, but instead make it richer and useful with patterns that a team might not even have thought of. Curation of the conventions by a body that continually incorporates new techniques and best practices will help, not hinder innovation, as the WHATWG showed when it invigorated HTML after years of dormancy. The underlying theme shines through: such a convention would have been useful for humans even before AI agents were used; the rise of agents only emphasizes the existing need rather than creating a new need unique to agents.

Having a single, aggregate, bespoke AGENTS.md is a short-sighted pattern that is more a symptom of a problem than its solution. Its very existence is a recognition of an existing documentation gap—but rather than fill that gap, it creates a separate, parallel one. Like the “junk drawer” in the typical household, it hides the “junk” by providing a single, standard place to toss it. What we need is less junk and a broader convention of semantically organized and well-written artifacts that carry project knowledge and are accessible to humans and agents alike.