A Handbook for AI (AGENTS.md): How to Write It Short, Right and Useful

For anyone working with an AI agent on a project, beginners included. Every term comes with an everyday explanation.

Figures come from public studies and articles listed at the end. The two main studies have not been independently confirmed, and research on this topic is very new. Examples marked "from this project" are real data from the repository of this very blog.

---

Quick summary#

• AGENTS.md (or CLAUDE.md, another name for the same idea) is a text file in the project that tells AI what it cannot work out by itself. Picture the notebook on the desk of a newcomer to the team.
• The effect is mixed: one study found AI ran faster and used fewer tokens, another found more steps and higher cost. Do not trust either side, measure it yourself.
• The principle that follows: short, written by a person, and only what the AI cannot read from the code.
• Six sections worth having: commands, the big picture, conventions, easy mistakes, prohibitions, and "what done means".
• The file is a living document: add a line when the AI repeats a mistake, delete a line when it goes stale.
• On safety: never paste secrets into it, and read it carefully in an unfamiliar repository, because the AI will follow it.

---

Hard words, plain meaning#

---

1. What AGENTS.md is, and why there are several names#

Each time it starts a job, an AI agent remembers nothing about your project. It has to reread the code, guess how to run things and guess the conventions. A file that records those things spares it the guessing, like handing a notebook to a new colleague.

According to public articles, the AGENTS.md idea appeared around May 2025, when developers complained that each tool read its own file such as CLAUDE.md or GEMINI.md. AGENTS.md proposes a common name. One report says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation (a weak source, check it again). Several sources say more than 20,000 repositories on GitHub use it, and Codex is the most clearly named tool that supports it. I found no source confirming each of the other tools, so do not assume every tool reads the AGENTS.md name.

Practical approach: if your tool reads another name, use that (this project uses CLAUDE.md), or create AGENTS.md and have the tool point at it.

---

2. Does it actually help?#

Two new studies, going in two directions.

The two measure different things on different sets, so neither can be taken as the final answer. I have read summaries, not both original papers closely.

A safe reading for work:

1. A context file can cost something. Every line is read at every job. Extra lines are a real cost.
2. Written by a person seems better than generated by AI. Use a tool to produce a starter file (for example the /init command), then trim it by hand.
3. Measure before and after. Run the same job with and without the file and compare time, rounds of fixes and bugs. How to keep such a log is in three hours with an AI agent.

---

3. What to write, what not to write#

The question that filters each line: can the AI work this out from the code? If yes, do not write it. If no, and it matters, write it.

Write in short imperative sentences rather than introduction paragraphs. "Run npm test before saying you are done" beats "This project has a fairly complete test suite".

---

4. Six sections worth having#

1. Commands. Install, run, build, test, check. Include the command to run one test, because AI often needs to run a single one.
2. The big picture. One or two paragraphs on how the parts connect and why. This is what takes reading many files to understand.
3. Conventions. Naming, the language of visible text, error handling, commit style.
4. Easy mistakes. Errors that have happened before. Each repeated mistake is a line.
5. Prohibitions. Folders, commands or actions not to touch without asking.
6. What done means. The conditions for reporting completion: tests, checks run, a screenshot.

None needs to be long. The goal is that a reader skimming for a minute still gets it.

---

5. A real example: this project's CLAUDE.md#

This blog project has a CLAUDE.md of 49 lines, 5 sections, about 5 KB. The structure:

What is not in the file: a list of every post, an explanation of Markdown syntax, the detailed content of the guides (they live in their own files, and the main file only points at them).

The detail is split into four guide files in their own folder, 327 lines in total, which the AI reads only when the job is relevant. This split keeps the main file short. Many lines in those files were born from a real bug, for example "the mascot needs overflow: visible" or "all visible text must go through the translation mechanism", exactly the loop in section 7.

---

6. Before and after examples#

A vague line

Write clean code and follow best practices.

The AI already tries to do this, so this line only costs tokens.

A concrete line

Visible text lives in site/i18n.mjs and always has all three languages vi, en, ja. Do not type text directly in templates.

This line names the place, the reason and the consequence of doing it wrong.

A prohibition with its reason

Do not edit the dist/ folder by hand. It is regenerated on every npm run build and any change will be lost.

With a reason, the AI can apply the spirit of the rule to similar cases.

---

7. Keeping the file accurate#

The file decays over time if nobody tends it. A small loop:

1. When the AI repeats the same mistake a second time, add a line. The line should say what to do and why, not only name the mistake.
2. When a line goes stale, delete it. A command changed, a folder moved, a rule dropped.
3. When a line never helps, delete it. Try removing it and see whether the AI goes wrong.
4. Review changes to the file like code. It affects every job the AI does.
5. Reread it from the top every quarter. If you cannot skim it quickly, it has grown too long.

Two habits keep it short: move detail into separate files and only point at them (many tools let one file import another), and keep personal preferences in a separate file kept out of the repository (some tools suggest a name like CLAUDE.local.md and adding it to git's ignore list).

---

8. Safety#

• Never paste secrets into the file. Keys, passwords, internal addresses. The file lives in the repository and is sent to the model at every job.
• Read this file in an unfamiliar repository. The AI will follow its contents, so a file written by someone else could contain lines telling the AI to do things you do not want. This is reasoning from how these files work, not based on a specific incident I checked. Before letting an agent run in a repository you do not trust, open the file and read it.
• Limit permissions elsewhere. Do not expect this file to be a fence: an instruction in text does not replace real permissions (see the Replit incident in why you should not trust AI blindly).

---

9. A template to copy#

Trim it to fit your project. Keep it under a page.

# Project: <name>

## What it is
<Two sentences: what the project does, what it uses, which deliberate choices to remember>

## Commands
- Install: <command>
- Run: <command>
- All tests: <command>
- One test file: <command>
- Check before saying done: <command>

## The big picture
<One or two paragraphs: the main parts and how they connect>

## Conventions
- <Naming>
- <Language of visible text>
- <Error handling>

## Easy mistakes
- <Something done wrong before and the right way, with the reason>

## Prohibitions
- Do not <action> without asking, because <reason>

## What done means
- Has tests, ran <check command>, reread the diff

---

10. A balanced view#

The evidence on how well these files work is thin and conflicting, so do not treat it as magic. A long file, written in a hurry, or generated by AI without trimming can make AI slower and costlier. A short file, written by a person and updated from real bugs seems beneficial, but verify that on your own project.

A more certain benefit is another one: the file forces the team to write down what everyone assumes. Those lines help newcomers too, and are a place for the team to agree on shared decisions, as in IT teamwork in the AI era. The file is also where each bug becomes a lesson, which reviewing AI-written code calls point 14: follow the project's conventions.

---

11. A quick checklist#

1. Is the file under a page, skimmable in a minute?
2. Does each line answer "can the AI work this out itself"?
3. Is there a command for one test and a final check command?
4. Does each prohibition have its reason?
5. Are there no secrets in the file?
6. Is there a place recording mistakes that repeated?
7. When did you last delete a stale line?
8. Have you tried running one job with and without the file to compare?

---

12. Conclusion#

An AI agent starts each job with an empty memory. A short, accurate, tended handbook spares it the guessing and helps the people on the team look in the same direction. But the effect is not firmly proven, so treat it as a small experiment: write it short, measure before and after, add a line each time a mistake repeats, delete a line each time it is no longer needed.

Start with three things: the commands, one paragraph of the big picture and one prohibition with its reason. A week later, add the lines born from the mistakes you actually meet.

---

References#

Figures come from public sources as of October 2026. Many sources are retellings, and research on this topic is new, so open the originals to check before quoting.

• AGENTS.md: Socket.dev overview and InfoQ
• Lulla et al., On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents
• Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?
• Community guide to writing CLAUDE.md: DataCamp (not official vendor documentation)
• Data from this very project: the CLAUDE.md file and the .claude/skills/ folder in the repository