--- title: "A Handbook for AI (AGENTS.md): How to Write It Short, Right and Useful" url: https://www.thinnd.site/en/engineering/writing-agents-md/ language: en author: "Nhu Duy Thin (Thinnd)" published: 2026-10-29 updated: 2026-10-29 section: "Engineering" tags: ["AGENTS.md", "CLAUDE.md", "context engineering", "AI agent", "guide"] summary: "AGENTS.md is a text file in the project that tells an AI agent what it cannot work out by itself: commands, the big picture, conventions and prohibitions. Two studies disagree on how well it works, so write it short, by a person, and only with what the AI cannot read from the code, then measure before and after." license: "Cite with the author name and the canonical URL above." --- # 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 | Term | Plain meaning | |---|---| | **AGENTS.md** | A file that briefs AI about a project, an open format. Picture it as a "README for AI". | | **CLAUDE.md** | A similar file that Claude Code reads. Each tool used to have its own name. | | **Context file** | The general name for files of this kind: what the AI is allowed to read before it starts. | | **Agent** | An AI that does not just answer but reads the project, edits many places and runs tests. | | **Prompt injection** | Slipping instructions into text so the AI follows the intruder's wishes instead of the user's. | | **Token** | A piece of text that AI reads and writes. More tokens means more time and money. | --- ## 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. | | Lulla et al. (arXiv, 2026) | "Evaluating AGENTS.md" (arXiv, 2026) | |---|---|---| | Scale | 10 repositories, 124 real PRs | Four agents, the SWE-bench set and a new set called CTXBENCH | | Comparison | The same jobs with and without AGENTS.md | With and without a context file | | Main result | With AGENTS.md: median runtime fell about 28.6%, output tokens about 16.6%, completion similar | Context files raised cost and number of steps. Success changed little: AI-generated files slightly negative, person-written files slightly positive | | Authors' own caution | A first step, not a conclusion | The success difference is small and not statistically significant | 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](https://www.thinnd.site/en/field-notes/agent-field-notes-real-project/). --- ## 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. | AI can work it out, do not write | AI cannot work it out, do write | |---|---| | "The project uses JavaScript" (the files show it) | The right test command, for example `npm run check`, and what it runs | | "Write clean, readable code" | "User-facing messages in Vietnamese, function names in English" | | A list of every file and folder | The big picture that takes reading many files to see | | An explanation of the framework's syntax | Deliberate decisions: "use X, not Y, because Z" | | The whole API documentation | Easy mistakes: "build output lives in dist/, do not edit it by hand" | | General advice | Prohibitions: "do not edit the payments folder without a reviewer" | 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: | Section | Content | Why it is there | |---|---|---| | What this is | Two sentences: a Markdown blog, a hand-written page generator, only two dependencies | So the AI knows the scale at once and does not propose adding a framework | | Commands | The `npm run dev`, `build`, `seo`, `check`, `og` commands with the environment variables | Correct commands, no guessing | | Architecture | What each main file in `site/` does and how they connect | Takes reading many files to see | | Content model | Rules for file naming, languages, frontmatter, paths | The easiest place to slip when adding a post | | Project skills | The list of four specialist guides and when to use them | So the AI remembers to use them | 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** ```text Write clean code and follow best practices. ``` The AI already tries to do this, so this line only costs tokens. **A concrete line** ```text 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** ```text 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](https://www.thinnd.site/en/engineering/why-not-to-trust-ai-blindly/)). --- ## 9. A template to copy Trim it to fit your project. Keep it under a page. ```text # Project: ## What it is ## Commands - Install: - Run: - All tests: - One test file: - Check before saying done: ## The big picture ## Conventions - - - ## Easy mistakes - ## Prohibitions - Do not without asking, because ## What done means - Has tests, ran , 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](https://www.thinnd.site/en/experiences/team-work-in-the-ai-era/). The file is also where each bug becomes a lesson, which [reviewing AI-written code](https://www.thinnd.site/en/engineering/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](https://socket.dev/blog/agents-md-gains-traction-as-an-open-format-for-ai-coding-agents) and [InfoQ](https://infoq.com/news/2025/08/agents-md/) - Lulla et al., [On the Impact of AGENTS.md Files on the Efficiency of AI Coding Agents](https://arxiv.org/html/2601.20404) - [Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents?](https://arxiv.org/pdf/2602.11988) - Community guide to writing CLAUDE.md: [DataCamp](https://www.datacamp.com/tutorial/writing-the-best-claude-md) (not official vendor documentation) - Data from this very project: the CLAUDE.md file and the `.claude/skills/` folder in the repository