What Is Agents.md?
Author: Domeny.ForSale editorial team Published
In brief: AGENTS.md is a text file containing instructions for AI agents working on a project, most often on code. It describes, among other things, how to run tests, how the project is organised and the rules for making changes. It does not run anything itself: its effect depends on whether the tool being used reads the file and how it interprets the guidance it contains.
What the AGENTS.md file is for
An AI agent is a tool that can not only answer questions but also perform tasks, such as browsing files, editing code and running commands. To do this, it needs context specific to the project. Without that context, it may choose the wrong way to install dependencies or modify files that the team does not edit manually.
AGENTS.md lets you record this context in the repository, the place where code and its change history are stored. The file uses Markdown, a simple text format that supports headings, lists and code blocks. You can edit it in a plain text editor and review it alongside other project changes.
It is a convention for providing instructions, not a program, an AI model or a mechanism for granting permissions. A statement such as “do not change the production configuration” is guidance for the agent, but it does not technically block access to that configuration.
AGENTS.md and README — different roles for documentation
README.md usually introduces a project to a human reader: it explains its purpose, installation and basic usage. AGENTS.md focuses on how an agent should carry out work in a particular repository. The two files can complement each other rather than duplicate the same documentation.
For example, a library’s README might show how to use it in your own application. Instructions for the agent, on the other hand, might specify that after changing the public interface, it must update the examples and run a particular set of tests.
Nor should AGENTS.md be confused with llms.txt, a file proposed as a way to provide language models with information about a website’s content. AGENTS.md is primarily about working on a project, not presenting a website’s content. Its presence is not a statement about the site’s visibility in search engines or AI services.
Where to put the file and whether every tool will read it
The typical location is the repository’s root directory. When creating the file, use the name AGENTS.md, in uppercase: on case-sensitive systems, Agents.md may be a different file. Do not assume that a tool will recognise every variation of the name.
In larger projects, you may encounter additional AGENTS.md files in subdirectories, for example separate files for the user interface and the server-side components. This allows rules for different technologies to be kept separate. However, the scope of the instructions and the way conflicts are resolved depend on the tool, so you should not assume a single hierarchy applies to all agents.
Before introducing the file, check the official documentation for the agent you use:
- whether it supports
AGENTS.mdand requires additional configuration; - which directories it searches for instructions;
- whether it reads files in subdirectories;
- how it combines them with the user’s prompt and other instructions.
Simply adding the file to a repository does not mean that every AI feature in the editor will start using it.
What to include in the agent’s instructions
The most useful information reduces guesswork: actual commands, the locations of important files and the boundaries of the requested change. A general recommendation to “write good code” does not tell the agent how to verify the result.
An example file for a JavaScript project using npm might look like this. The commands only make sense if they match the configuration of the particular repository:
## Working on the project
## Running and verification
- Install dependencies with `npm ci`.
- Run tests with `npm test`.
- Check code rules with `npm run lint`.
- If you cannot perform a check, state the reason.
## File organisation
- Application code is in `src/`.
- Do not manually edit the `generated/` directory.
## Scope of changes
- Do not add dependencies without the user's confirmation.
- When fixing a bug, add a test that reproduces it.
- Do not combine the fix with unrelated code cleanup.
In a project with several applications, add the directory from which each command must be run. If tests require an additional service, describe the requirement and a safe way to prepare the environment. Do not include passwords, tokens or other secrets in the instructions.
How to check effectiveness and keep the file up to date
A small task, such as fixing validation for a single form field, makes a good test. Observe whether the agent uses the correct commands, avoids automatically generated files and reports tests it has not run. If the tool shows which instructions it has loaded, check that information too.
When the agent makes a mistake, first establish whether it read the file. Adding more prohibitions will not help if the problem is a lack of support or an incorrect location. If the instruction was read, replace unclear wording with a specific action or condition.
Treat AGENTS.md as part of the documentation you maintain: update it when commands, the directory structure or the testing process change. Enforce access restrictions through permissions and environment configuration, not merely through sentences in a file. To begin, record working verification commands and the most important constraints, then test them on one small task.
Read also
