AGENTS.md Is Not a README: Why AI Coding Tools Need a Rulebook, Not a Welcome Mat

Foreword

Nowadays, many companies have fully adopted AI-assisted development for their projects. Our company is now fully AI-assisted for development. The company provides a fixed monthly quota for us to use.

However, I've noticed that many colleagues, when using AI tools like Codex for development, basically fall into these two approaches:

Either they directly open the dialog box and enter a bare conversation mode to make requests. Or, those with some AI knowledge will use the built-in command /init for project initialization, but that's about it. It's as if they just wrote a README project description document for the project.

Then, during the development process, they easily encounter various problems:

For example, the agent doesn't follow design specifications, always forgets testing and verification steps, and even randomly modifies or deletes files. Some repetitive prompts have to be repeated every time, causing the context window to become increasingly bloated. As a result, not only are there many bugs, but rework is needed, and the monthly token quota provided by the company is simply not enough.

Many colleagues think it's because the model being used is wrong. Although model selection does have a certain impact, I think a large part of the reason is that the AGENTS.md file hasn't been truly and reasonably utilized and managed.

So here, based on my personal understanding, I'll briefly explain these few issues: what exactly AGENTS.md is for, how it's used by the agent, what problems /init solves, and why we still need to maintain it after generation.

First, what exactly is AGENTS.md?

Before talking about /init, I still need to briefly understand AGENTS.md again.

AGENTS.md is an open standard. Let's look at the official introduction here AGENTS.md

Simply put, we can think of AGENTS.md as an agent's README: a dedicated, predictable place to provide context and instructions to help AI coding agents work within our projects.

The tools it supports include OpenAI Codex, GitHub Copilot, Cursor, Aider, Zed, JetBrains, Claude Code, and more.

It can be said that with one file, we can use it across multiple Agents.

A very simple AGENTS.md looks something like this

`# Project Rules`

`## Build and Test`
`- Build: npm run build`
`- Test: npm test`
`- Format: npm run lint`

`## Coding Standards`
`- API input parameters uniformly named with XxxParams`
`- Responses uniformly wrapped with XxxResponse`
`- Do not use console.log, use logger uniformly`

`## Prohibitions`
`- Do not manually modify the generated/ directory`
`- Do not commit .env files`
`- Do not add new dependencies to packages/core`

`## Linkage Rules`
`- If you change an API interface, synchronously update docs/api.md and the corresponding tests`
`- If you change a command entry point, synchronize src/cli.ts + tests + README`

Although not much, it's basically sufficient.

So let's first get a general understanding of AGENTS.md. It will be easier to understand when we talk about /init and maintenance rules later.

But I find that many people don't really use it or just treat it as a README file. However, it's not the same thing as our common README.md at all.

Although both are md-type markdown files, their usage is completely different.

First, README.md is for people to read. For example, when a new developer enters a project and opens README.md, they can know what kind of system this is, what the tech stack is, how to set up the local environment, and where the code repository is. It's clear at a glance. For example, my own project's README.md is like this:

So we read README.md to quickly understand the project, get started quickly, and find entry points.

But AGENTS.md is different; it's for the agent to read. For example, after the agent loads the project and opens AGENTS.md, it can clearly and quickly know what the build command is, how to run tests, which specifications must be followed, what verifications need to be done after code changes, etc. For example, my project's AGENTS.md is written like this:

So the agent reads AGENTS.md to follow the rules, reduce errors, and maintain delivery quality.

Here, I'll summarize simply with a picture:

So how is AGENTS.md loaded?

After roughly understanding what AGENTS.md is above, we also need to briefly understand how AGENTS.md is loaded by the agent. Why, after writing this md file, is the agent more likely to follow the rules?

Simply put, when the agent starts, enters a project, or starts a new session, the tool will bring in the content of AGENTS.md as part of the context.

Although the implementation details differ slightly between different tools, the general direction is the same:

The closer the rules are to the currently processed project or directory, the more specific they usually are.

Since I mostly use the Codex tool for project development now, I'll mainly use Codex as an example to explain the general loading logic.

Let's first see how the official Codex documentation explains it.

Codex has an official documentation page about AGENTS.md: https://developers.openai.com/codex/guides/agents-md

Here, I'll briefly summarize. The document mainly covers these points:

How Codex discovers guidance

Builds an instruction chain at startup

First reads the global scope (~/.codex)

Then traverses from the project root directory down to the current working directory

Each directory looks for AGENTS.override.md → AGENTS.md → fallback filenames

Formulating global guidelines

Can create global default settings in the Codex home directory

Create ~/.codex/AGENTS.md for general rules

Use AGENTS.override.md to temporarily override global rules

Repository project instructions

Place AGENTS.md in the repository root to override basic settings

When specific teams need different rules, override rules can be added in nested directories

Custom fallback filenames

If the project already uses other filenames (like TEAM_GUIDE.md)

Can configure project_doc_fallback_filenames in ~/.codex/config.toml

Size limits

Codex skips empty files and stops adding files after the total file size reaches the limit (project_doc_max_bytes, default 32 KiB)

If the limit is exceeded, you can raise the limit or place override files near the specific work area

Simply put, Codex's loading order is actually like this:

First, Codex builds an instruction chain each time it starts. The loading order is:

Global config → Project root directory → Current working directory.

Each layer's AGENTS.md is concatenated together layer by layer, with later ones having higher priority than earlier ones.

For example, suppose our project structure is like this:

my-monorepo/`
├── AGENTS.md              # Global project rules`
├── frontend/`
│   └── AGENTS.md          # React-related rules`
├── backend/`
│   └── AGENTS.md          # Java/Spring-related rules`
└── infra/`
    └── AGENTS.md          # Deployment-related rules`

If we start Codex in the frontend/ directory, it will first read the global ~/.codex/AGENTS.md, then my-monorepo/AGENTS.md, and finally my-monorepo/frontend/AGENTS.md.

If we start in backend/, it will read ~/.codex/AGENTS.md + my-monorepo/AGENTS.md + my-monorepo/backend/AGENTS.md.

Ultimately, the contents of the three files are concatenated together.

Then the official documentation also mentions that Codex's default limit is 32 KiB. If all files combined exceed this, they will be truncated.

How to understand this? For example, I encountered this once before. I wrote many rules in AGENTS.md, but found that Codex didn't seem to follow the rules. Later, I realized it was because the limit was exceeded, and the later rules were truncated.

Although according to the documentation, we can increase project_doc_max_bytes in ~/.codex/config.toml, I don't think it's necessary.

After all, if you write too many rules, the agent can't remember them all. I think streamlining the rules is more useful than increasing the limit.

Of course, there's one thing we need to pay attention to: AGENTS.md is not a real-time configuration center.

That is to say, it's not like changing a line of rules will immediately take effect globally in the current conversation. Codex builds the instruction chain at startup and does not dynamically reload it during runtime. So a safer approach is to start a new session window after making changes.

If we use Claude Code, can we still use AGENTS.md?

Because I also use Claude Code, and many of you probably use a combination of tools, I'll briefly explain this here too. Many people might think AGENTS.md is only for Codex, and that Claude Code's own CLAUDE.md is enough.

Actually, that's not the case.

AGENTS.md is not exclusive to Codex. As we mentioned earlier, it's an open protocol rule that multiple agents can use. Claude Code can also use it. It's just that Claude Code has its own system, so the usage is slightly different.

Although the implementation details differ between tools, you can first understand it in this direction:

Global rules manage personal habits, project rules manage the current repository, and subdirectory rules are usually more specific. The Codex side typically uses AGENTS.md to manage project instructions, while the Claude Code side typically uses CLAUDE.md to manage project instructions. The closer the rules are to the currently processed project or directory, the more specific they should usually be.

So what exactly is the difference between AGENTS.md and CLAUDE.md?

As we said above, AGENTS.md is an open standard, universal across multiple tools. Rules written here can be read whether using Codex, Cursor, Aider, or Claude Code. It's more suitable for general project rules, such as build commands, test commands, coding standards, prohibitions, linkage rules, etc.

CLAUDE.md, on the other hand, is a Claude Code-specific format, only recognized by Claude Code itself. Content written here can only be read by Claude Code. It's suitable for Claude Code-specific configurations, such as which skills are used (e.g., /lark-base, /verify), which hooks are configured (e.g., automatically run prettier after code changes), Memory-related instructions, etc.

So if we use both Claude Code and Codex in development, how should we place our rules?

I personally suggest understanding it this way:

General rules go in AGENTS.md, and Claude Code reuses them via CLAUDE.md.

Another simple and effective way is to explicitly import @AGENTS.md in the project's CLAUDE.md, and then only add Claude Code-specific things below.

For example, we can write a line @AGENTS.md in CLAUDE.md, and Claude Code will automatically load the content of AGENTS.md.

Of course, I need to briefly explain here: the @file reference syntax is a capability of Claude Code, not a general capability of AGENTS.md itself. So don't expect to write a bunch of @xxx.md in AGENTS.md and have all tools understand it. General files should still contain general content as much as possible.

For example, I have a project planned like this:

AGENTS.md contains general rules: build command npm run build, test command npm test, coding standards (API parameters use XxxParams, responses use XxxResponse), prohibitions (don't manually modify generated/, don't commit .env), linkage rules (if you change an interface, synchronously update documentation and tests).

These rules need to be followed whether using Codex or Claude Code.

And CLAUDE.md only needs to supplement things only Claude Code uses: skills (/lark-base for operating Feishu multidimensional tables), hooks (automatically run prettier after code changes), memory prompts, etc.

The benefit of designing rules this way is:

General rules are maintained in only one place. Claude Code imports them via @, no need to rewrite. Other tools directly read AGENTS.md. No matter what tool is used, the project rules are consistent.

Actually, there's another method: we can also put a convention in the global ~/.claude/CLAUDE.md. For example, I saw another user share this before:

Follow and maintain/create the nearest AGENTS.md file. It is the project description for AI agents, containing project context and work instructions.

Original post here: https://linux.do/t/topic/1036584

This way, after Claude Code enters the project, it will be more inclined to actively work around the project's AGENTS.md.

However, I personally recommend explicitly placing team project rules in the repository. Because global configurations only take effect locally on your own machine. When others pull the project down, they might not know what you've configured locally. For team collaboration, the CLAUDE.md + @AGENTS.md approach within the project is clearer and easier for the team to maintain together.

Another point, Claude Code also has a Memory mechanism

Besides AGENTS.md and CLAUDE.md, Claude Code actually has a third thing: Memory.

Memory is stored under ~/.claude/projects/<project hash>/memory/MEMORY.md. Each record is an independent md file, and MEMORY.md is the index file. The difference from the previous two is:

AGENTS.md and CLAUDE.md are both project rules, committed to git, shared by the team. Memory, on the other hand, is a record of experience during collaboration, local only, not committed.

For example, problems we recently encountered, temporary rule conventions, and experiences not yet refined into rules are all first recorded in Memory. Each time a new session starts, the first 200 lines of Memory are automatically loaded into the context window.

So here, I think we can check the content of Memory from time to time. If we find some instructions or rules that we've repeatedly prompted several times, we can actually refine them into AGENTS.md. After refining, this entry in Memory can be deleted. This way, our development efficiency and rule constraints will be much better.

Actually, Codex also has a similar Memory mechanism (stored under ~/.codex/memories/), which can carry context across threads. For detailed configuration and usage, you can refer to the relevant official documentation: https://developers.openai.com/codex/memories

So what problems does /init solve, and when should it be used?

After understanding the role of AGENTS.md above, looking at the /init command becomes much simpler.

In my personal view, /init is a very valuable built-in command.

Simply put, it helps the agent first scan the project, letting it know what the general architecture of our project is like. For example, how the project directories are divided, what the tech stack is, where the startup commands are, what the test commands are, and whether there are any notes in the README.

If this information isn't sorted out first, the agent can only guess as it goes when first entering the project. Completely unaware of our project's architecture information, although it can search for files and read code on its own, this consumes context and easily misses some project conventions. That's why I say /init is very valuable.

For example, after we use Codex to run the command in the project root directory, it usually generates an AGENTS.md file.

Before generation, this command generally does these things:

Scans the project structure, such as directories and files

Analyzes dependencies, like package.json, pom.xml, requirements.txt

Reads README.md, looking for startup commands and test commands

Generates a basic project description

Sounds simple and quick, right? But the problem is also here: It can only generate a starting point, seeing more of the project's surface-level information. It's equivalent to just doing a simple inventory and initialization of the project.

So when should we use the /init command?

Here I need to clarify: If it's a brand new empty project, just starting to write code, I don't recommend immediately running /init.

Because at this time, the project directory, dependencies, startup scripts, and testing methods are not yet stable. The generated content will likely be very generic, and even after a few days when the project structure changes, this file will immediately become outdated.

Actually, the /init command is more suitable for use after our project has a certain amount of code and the directory structure is basically stable.

At this time, what it scans will be closer to the real project, and it will be easier to continue maintaining this initial draft later.

Back to our opening question: Why does it still need maintenance after /init?

Here we can actually answer the question: Why is running /init far from enough?

It's actually because /init only helps us generate an initial file, but it doesn't know how our team usually develops, nor does it know what problems have occurred in the history of this project, or what pitfalls have been encountered.

For example, when I use AI Coding, I often add a sentence in the prompt to correct the AI's execution flow and rules whenever a problem occurs. For instance, if it always commits to git without my consent, I'll always specify in the requirements: remember to wait for my review and confirmation before committing to git.

In the short term, this certainly works. But over time, you'll actually find a few problems:

Every new session, you have to repeat the same things

Prompts get longer and longer, context becomes increasingly bloated

Forget to remind once, and the agent might act according to its own understanding again

Everyone on the team reminds differently, so the rules the agent receives are inconsistent

So at this time, we need to maintain AGENTS.md, not to write another project description document. More accurately, it's about putting these high-frequency, long-term, error-prone rules into the project context in advance.

These rule requirements and instructions are hard for /init to know at once, and they're not suitable to be stuffed into the prompt every time, because they're not just needed for this one task, but are needed for the long term in this project.

When we write these rule requirements into AGENTS.md, the agent is more likely to get these rules when entering the project. No need to repeat explanations in the prompt every time, context is saved, repetitive reminders are reduced, and the probability of the agent doing something wrong will also decrease.

Then another problem arises: Is it better to write as much as possible in AGENTS.md?

We might think, if we write all the rules in, the agent will be able to do things completely as required?

Actually, that's not the case either. Too many instructions, and the agent actually can't remember them. It's like giving a person 100 requirements at once; they definitely can't handle them all, only remembering the first few.

Here we can refer to this evaluation: How many instructions can an LLM execute at once?

So back to our AGENTS.md, the tool's system prompt itself already comes with many built-in instructions (permission control, tool usage, security constraints, code style). These already take up quite a few instruction slots. The AGENTS.md we write is actually superimposed on top of these. So the effective space left for us is really not as much as we imagine. Therefore, AGENTS.md is not about writing as much as possible, but about writing the most critical things, those that the agent cannot infer on its own.

If that's the case, what rules should be written, and what shouldn't?

Actually, I think this is very simple and easy to judge. As long as we think it needs to be followed long-term or has been reminded multiple times, it can be written into the rules. Here, I'll give a few simple examples:

But some people might not know how to write a correct rule instruction. For example, writing like this won't work:

Keep code elegant

Pay attention to maintainability

Follow best practices

Actually, we should clarify rule instructions like this, needing specific actions, like:

After changing frontend components, need to run pnpm lint

Do not manually modify the generated/ directory

API input parameters uniformly use the XxxParams naming convention

After changing an interface, need to supplement corresponding tests

For example, like the screenshot of my project at the beginning:

Simply put, what can be seen from the code doesn't need to be written. What's only needed for this task also doesn't need to be written. What's truly worth depositing are those project rules that repeatedly affect delivery quality.

Let's add one more point: How to go from Prompt to AGENTS.md

We've actually briefly mentioned this point before. The judgment standard is actually very simple: The second time you repeat a reminder, you should consider depositing it.

There's one point here, if using Claude Code, the process has one more layer.

Because as we mentioned earlier, Claude Code has a Memory mechanism, so the process should be:

Prompt → Memory → AGENTS.md

As we mentioned before, Memory exists in ~/.claude/projects/<project hash>/memory/MEMORY.md, like a draft notebook or history record. If possible, you can regularly review it to see if there are any rules or instructions that need to be refined.

If using other tools, we can directly deposit from Prompt to AGENTS.md, or we can check if the corresponding tool has a similar intermediate layer mechanism.

Then, slowly accumulating and depositing like this, the division of labor becomes very clear:

AGENTS.md is the project rules, committed to git, shared by the team

Memory (Claude Code only) is a personal draft notebook, stored locally

Prompt only handles temporary, one-time reminders

I'll stop here for now. Let me emphasize again, AGENTS.md is not about writing as much as possible, but about writing rules that the agent cannot infer, need to be followed long-term, and can be written as clear actions.