AGENTS.md File: What Goes In It (With Template)

Where the AGENTS.md file goes

Put it in the repository root, the same folder as the top-level README. In a Node project that is the folder with package.json. In a Python project that is the folder with pyproject.toml or requirements.txt. In a Go module that is the folder with go.mod. The file name is AGENTS.md, uppercase, with that extension.

Do not put the only copy inside src/, app/, or a package subdirectory if you want it to describe the whole repo. A second AGENTS.md inside a package is a different file for that folder. This generator writes one file and does not merge a root file with a nested one.

The eight sections

Each heading is a place for notes you already have. If the generator never saw a note for a heading, it writes “Not specified in the source.” That sentence means the paste was silent. In a file you type yourself, delete a heading you cannot fill, or write the real rule. Leaving the placeholder in a hand-written file tells the agent that you decided nothing.

Project overview

One short description of what the repo builds, the language, and what it refuses to be. “A CLI that sums a CSV. Go. No network.” is an overview. A tour of every function is not. When the generator sees a heading it does not recognize, it keeps that block under source notes inside the overview, so the words are not dropped.

Coding conventions

Naming, language level, formatting, and lint. “Standard library only. Exported names have a comment.” belongs here. A product requirement does not. The generator files lines about conventions, naming, lint, TypeScript, or formatting into this section.

Architecture constraints

The boundaries of the program: one command or many, which folders exist, whether a database or a network call is allowed. This is the shape of the system, not a style preference. Stack, structure, and boundary notes land here.

Do

Actions the agent must take. Start each item with a verb. “Reject a row whose amount does not parse” is a do. “We like clean code” is not, because nobody can check it. Lines that begin with do, always, or must are filed here.

Don't

Actions the agent must not take. “Do not skip a bad row silently.” “Do not add a database.” Lines with never, avoid, or must not are filed here. A don't that contradicts a do is two instructions. Fix the source. The generator will not pick a winner.

File and folder scope

The paths the agent may edit, and the paths it should leave alone. Name directories, not a feeling. “Edit the module root and internal/. Leave testdata/ alone unless the task names a fixture.” Scope, file, folder, and path notes land here.

PR and commit expectations

How a change is described. “The commit message names the flag or the column that changed.” This is not a code-style rule and it is not a test command. Pull request and commit notes land here.

Testing

The command, and one fact that a passing run must show. “go test ./... The fixture has 4 rows and 1 bad amount. Expect a total of 30 and a rejected count of 1.” A command with no expected result is weaker, because the agent cannot tell a green run from the wrong green run. Test, vitest, jest, playwright, and coverage notes land here.

AGENTS.md file and the README

The README is for a person who wants to install the project and run it. The AGENTS.md file is for an agent that is about to edit the project. Install steps, license, and a screenshot stay in the README. Edit rules, path limits, and the test command belong in AGENTS.md.

Some agents also open the README. This site does not claim they skip it. Splitting the two files keeps the install guide from becoming the only place the rules were written. If the only copy of “do not add a database” is a sentence in the middle of the README, an agent can miss it. Put that sentence in the don't section.

AGENTS.md file and .cursorrules

.cursorrules is a Cursor rules file. It is often one list of bullets, with no headings, in the repo. Cursor also stores rules under .cursor/rules. Those are Cursor's files. An AGENTS.md file is the headed Markdown this site writes for the repository root.

The bullets in a .cursorrules file can become the eight sections. The Cursor rules converter sorts each line by what it says and keeps your wording. It does not map every field inside .cursor/rules. A rule that only lives in .cursor/rules is not automatically inside AGENTS.md until you paste it.

You can keep both. Cursor can read .cursorrules while another agent reads AGENTS.md. If the two files disagree, you have two instructions. Update both, or generate AGENTS.md again from the Cursor file you trust.

What does not belong in the AGENTS.md file

Secrets, tokens, and customer data do not belong in the file. It is committed with the repo, and an agent will repeat whatever you put there. A long style guide does not belong there either. Link the guide from the conventions section in one line, and keep the file to the rules that change how the agent edits. A changelog, a roadmap, and a list of open bugs are not instructions. They go stale, and the agent will treat a stale bug list as current work.

One fact lives in one section. “Do not edit vendor/” is scope, not a don't, if the point is which folder is off limits. “Do not add a database” is a don't, and it is also an architecture boundary. Write it once, under don't, and leave architecture for the shape of the program. Repeating it in three headings does not make it stronger. It makes a later edit easy to miss.

A complete AGENTS.md file

This is a command-line ledger, not one of the three project files on the example page. Copy it and replace the sentences. A blank version with brackets to fill is the AGENTS.md template.