Your Codebase Needs a Manual for AI

Why AGENTS.md may be the beginning of a new layer of software architecture

Code used to explain itself to developers. Now it also needs to explain itself to machines.

In short

• AGENTS.md is a plain Markdown file at the root of a repository that tells AI coding agents how to work in that project: commands, constraints and the rules that are not obvious from the code.
• It is read by more than twenty coding tools, including Codex, Cursor, Gemini CLI and Copilot. Since 18 September 2026, Claude Code reads it too.
• Since December 2025, AGENTS.md has been stewarded by the Agentic AI Foundation under the Linux Foundation, alongside MCP.
• Research from ETH Zurich shows that more context is not better: short, human-written files help a little, while long or auto-generated ones add cost without improving results.
• The most valuable lines in the file are not coding rules. They are business lessons the code cannot tell by itself.

HOW WE STARTED

Before It Was a Story

At PERETZ, we don't work inside a single AI ecosystem. Different projects use different models and different coding environments. Sometimes the choice depends on the task, sometimes on the stage of development, and sometimes we simply know that one model is better at something than another.

An AI coding environment is no longer autocomplete with a chat window attached. Modern agents inspect a repository, search through files, run commands, edit code, execute tests and work through multi-step tasks. Claude has become a particularly useful part of that workflow for us, and I deliberately call it an assistant rather than a tool. A tool waits for you to operate it. An agent looks at the problem, investigates the codebase, makes a change, tests the result and continues.

For a while, every agent needed its own instructions. Codex, Cursor and others were already reading AGENTS.md, while Claude Code read only its own CLAUDE.md. On 18 September, with version 2.1.277, Claude Code started reading AGENTS.md too: if a folder has no CLAUDE.md, it uses AGENTS.md instead.

We started using it almost immediately, and today it is being introduced across several of our projects: an old OpenCart store, the website of an international professional organization, and a medical education platform. One file now explains a project to every agent that works in it. We no longer explain each project from scratch or keep the same instructions in several places.

After actually working with it, rather than just reading about it, we can say something more useful than "this looks promising": it works. Not magically, not perfectly, but it makes working with agents noticeably more convenient. And that small improvement points to a much larger change.

THE GAP

The Code Is Not Enough

Imagine joining a large software project as a developer. You receive the repository. You can search the entire codebase, inspect the database, read the API definitions and run the application. Technically, you have everything.

But you still don't know everything.

You don't know that the strange payment function cannot be rewritten because an old ERP depends on one particular response. You don't know that the apparently redundant service exists because of a client integration nobody wants to break. You don't know which conventions are architectural decisions and which are historical accidents. And, most importantly, you don't know why.

A human developer usually gets that information through conversation. "Don't touch that." "We tried this before." "The client requires it." "That looks strange, but there is a reason."

Now introduce an AI agent. It can read every file, search faster than any human and understand patterns across thousands of lines of code. It can even propose a cleaner architecture.

But cleaner is not necessarily correct. The agent can understand the code. It may not understand the business that created the code.

The agent can understand the code. It may not understand the business.

BEYOND README

README Was for Humans

For decades, the README was the closest thing a project had to a manual. Install this. Run this. Build this. Here is what the application does. Useful, but written primarily for people.

An AI coding agent needs another layer of information. Not necessarily more information. Different information.

What should it touch? What should it never touch? How should the application be tested? Which patterns should new code follow? Where does business logic live? Which dependencies are intentional? And perhaps the most important question: when should the agent stop and ask a human instead of making a decision?

This is where AGENTS.md becomes interesting. It is closer to a contract between a repository and the agents working inside it than to documentation in the traditional sense.

ONE PROJECT

Different Agents, One Project

Imagine a project where one developer uses Claude Code, another prefers Codex and a third works in Cursor. The models are different. The interfaces are different. The tools available to them are different.

But the project is the same project. The architecture, the business rules, the deployment constraints and the things you absolutely must not break are the same. Why should every agent have to rediscover them independently?

This is why the convergence around AGENTS.md matters more than any single product announcement. The format was formalized in August 2025 by OpenAI together with Google, Cursor and Factory. In December 2025, the Linux Foundation formed the Agentic AI Foundation, and AGENTS.md became one of its three founding projects, next to Anthropic's Model Context Protocol and Block's goose. With Claude Code joining in September 2026, the major coding agents now read the same file.

It is still better described as a convention than a formal specification: a simple Markdown file with no required structure. But sometimes conventions matter more than standards, because people actually use them.

Sometimes conventions matter more than standards.

OUR MANUAL

What Our Manual Says

We can't show files from client projects. But we can show our own. This is part of the AGENTS.md in the repository of the PERETZ website:

## Never
- Never add noindex, nofollow or an X-Robots-Tag header, and never edit
  public/robots.txt. The live site must stay open to search engines.
- Never block AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot).
- Never regenerate APP_KEY on an existing environment.
- Never change the URL or alias of an existing page. If it is unavoidable,
  add a 301 redirect and ask first.

## Before deleting anything
Code that looks unused may be called from database content, cron scripts
or external integrations. Search for usages and ask before removing it.

None of these lines is really about code. Each one is a business lesson.

The rule about noindex exists because a single tag added "temporarily" during development can quietly remove a site from Google. The rule about AI crawlers exists because a site that ChatGPT and Perplexity cannot read does not exist for a growing share of buyers. The rule about URLs exists because every address that changes without a redirect throws away years of search history.

And the rule about deleting code is the one we would put in every AGENTS.md. "This looks redundant, remove it" is a perfectly reasonable engineering instinct and a surprisingly expensive business mistake. In a site where the content lives in the database, code that no file references can still be used every day.

That is exactly the kind of knowledge that usually disappears from software projects: not how the code works, but what the business learned the hard way.

THE SETUP

How We Set It Up

One detail matters if you use Claude Code. It reads AGENTS.md only when there is no CLAUDE.md in the folder or any parent folder. If a CLAUDE.md exists, Claude Code reads that and ignores AGENTS.md.

So we split the two files by audience:

• AGENTS.md holds everything every agent needs: the stack, the commands, the hard rules, the non-obvious parts of the project and when to ask a human.
• CLAUDE.md starts with a single line, @AGENTS.md, which imports the shared file, and then adds only what is specific to our own work with Claude: how we connect to the server, how changes are saved and deployed.

The result is one source of truth. A developer on our team can use a different agent, and it will follow the same rules as ours.

One more rule for both files: no passwords, keys or server addresses. A manual for agents is still a file in a repository, and it should be safe to read for anyone who can read the code.

LEGACY CODE

Legacy Makes It Harder

Legacy software often contains the history of a business. Someone made a workaround. Someone added an exception. Someone kept a strange API response because another system depended on it. The developer who made the decision may have left years ago. The code remained.

This is why modernizing legacy software is not simply "find old code and replace it with better code". It is archaeology. You have to understand what must survive before deciding what can disappear. We wrote about this in more detail in Upgrading an Old Laravel or PHP Site in 2026.

An AI agent makes this both more powerful and more dangerous. It can inspect a legacy system much faster, find patterns and modernize repetitive structures. But it may not know which ugly piece of code is carrying an invisible business requirement.

AI can read the code. Who reads the business?

A good AGENTS.md does not solve that problem by itself. But it gives the team one place to write down the business and architectural context an agent genuinely needs, before the people who remember it are gone.

LESS IS MORE

We Don't Need a Novel

The natural reaction is to write a huge file: every convention, every historical decision, every exception and warning. That is probably the wrong direction.

In 2026, the SRI Lab at ETH Zurich tested repository context files across several coding agents, including Claude Code and Codex, on hundreds of real GitHub issues. Overall, the files did not improve task success rates and increased inference cost by more than 20%. The agents did follow the instructions: they tested more and explored more files. But unnecessary requirements made the tasks harder.

The details are even more useful. Files written by people improved results by about 4% on average. Files generated by a model made results slightly worse than having no file at all. And the directory overviews that fill most auto-generated files did not help agents find the right files any faster.

Context has a cost, and more context is not better context. The researchers' own conclusion is that human-written context files should describe only minimal requirements.

So the goal is not a manual containing everything people know about a project. The goal is to give an agent the few things it would otherwise learn only through repeated mistakes. Our own file is under fifty lines, and we wrote it by hand.

NEW INTERFACE

The Repository Is an Interface

We usually think of an interface as something designed for a user: a screen, a button, an API. But an AI agent also needs an interface to the system it works on. It needs to know how the repository is structured, what it is allowed to do, where to look and when to stop.

In that sense, AGENTS.md is less a documentation feature than part of a new interface between software and the machines that work on it. Today it is a Markdown file. Tomorrow it may include structured metadata, skills, permissions and automated checks.

There is also a second side to this story. A manual helps agents build your software. But agents are also starting to use websites directly: searching products, comparing offers, filling in forms, placing orders. That requires something different: a website that exposes its data and actions to machines, not only pages to people.

We ran into this on the same old OpenCart store. Connecting AI agents to it meant upgrading the site itself first. We will come back to that side of the story soon.

WHAT'S NEXT

Where This Ends

It is too early to say how this will look in five years. Tools still have their own rule systems: some use CLAUDE.md, some use .cursor/rules, some use AGENTS.md, some use all of them.

For years, the relationship between people and code was simple. It is not anymore:

Different models, different capabilities, the same repository, the same business and the same consequences when something breaks.

We may even want different agents to approach the same problem differently. But they should at least understand the same reality.

The filename may change. The principle probably won't. Once machines work inside our codebases, the codebase needs a way to talk to its new collaborators.

The filename may change. The principle probably won't.

THE MANUAL

A Manual for AI

We started using AGENTS.md because it was practical. We kept using it because it made working with different agents easier. And the larger idea turned out to be more interesting than the file.

Software is acquiring another audience. Not only developers, not only users, but machines that can develop software. That changes how we think about documentation, about architecture and about legacy code.

A well-designed system has always tried to make its logic understandable to the people who maintain it. Now it has another responsibility: to make the right parts of that logic understandable to the agents working alongside them. Not everything, not blindly, not in a thousand lines. Just enough context to know what the code cannot tell by itself.

If your team is starting to work with AI agents, or your system is too old for them to work on safely, that is exactly the kind of problem our website modernization work starts with. And if you are still deciding how much to hand over to AI, read Do I Need a Developer, or Is AI Enough?

FAQ

Frequently Asked Questions

What is AGENTS.md?

A plain Markdown file at the root of a repository that tells AI coding agents how to work in the project: commands, constraints, conventions and when to ask a human. Think of it as a README for agents.

Does Claude Code read AGENTS.md?

Yes, since version 2.1.277 from 18 September 2026, but only when there is no CLAUDE.md in the folder or its parent folders. To use both, start CLAUDE.md with the line @AGENTS.md.

What is the difference between AGENTS.md and CLAUDE.md?

AGENTS.md is tool-neutral and read by most coding agents. CLAUDE.md is read by Claude Code. A practical setup keeps shared rules in AGENTS.md and only Claude-specific notes in CLAUDE.md.

How long should AGENTS.md be?

Short. Research from ETH Zurich found that extra context raises cost by more than 20% without improving results, and recommends only minimal requirements. Ours is under fifty lines.

What should not go into AGENTS.md?

Passwords, keys and server addresses, long directory overviews the agent can find itself, and anything generated automatically without review.

Sources

• Anthropic decides to support OpenAI's markdown instructions spec, The Register
• Claude Code now supports AGENTS.md natively, DEV Community
• Linux Foundation forms Agentic AI Foundation, SD Times
• OpenAI and Anthropic donate AGENTS.md and MCP to the Agentic AI Foundation, InfoQ
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?, SRI Lab, ETH Zurich
• Does AGENTS.md Actually Help Coding Agents?, DAIR.AI Academy