Skip to main content
Back to blog

NOVEMBER 22, 2026

What to Put in AGENTS.md (and What to Leave Out)

An AGENTS.md file is loaded into your coding agent's context when it works, so treat every line as a cost. Put in the commands, the decisions the code cannot show and the definition of done. Leave out the tour of the codebase.

By Umar Abdullah · AI-Native Development

Light cover reading "Write down the decisions, not the tour" beside a short AGENTS.md file with four sections: commands, decisions, boundaries and done
November 22, 20268 min read

Short answer

Put four things in AGENTS.md: the exact commands to build, test and check the project; the decisions an agent cannot work out from the code; the boundaries it must not cross; and what "done" means. Leave out anything the agent can see by reading the repository. The file travels with every task, so a short file of real decisions beats a long tour of the codebase.

What is AGENTS.md, and how do agents use it?

The AGENTS.md project calls it "a simple, open format for guiding coding agents" and suggests thinking of it as "a README for agents". Its site says the format is used by over 60k open-source projects and is now stewarded by the Agentic AI Foundation under the Linux Foundation.

There is no schema. The project's FAQ answers "Are there required fields?" with "No. AGENTS.md is just standard Markdown." What gives the file its force is how an agent is told to treat it. Codex's own base instructions tell the model that for every file it touches, it "must obey instructions in any AGENTS.md file whose scope includes that file."

Two mechanics follow from that, and both shape what you should write.

The file is loaded with the task. Codex's instructions say the root file, and any between the working directory and the root, are included with its developer message; files deeper in the tree it is told to check for as it works. Gemini CLI's context file documentation is blunter: it concatenates all the context files it finds and "sends them to the model with every prompt." So it is reasonable to treat every line as a cost, in tokens and in attention taken from the task itself.

The agent takes it seriously. A README can say "we generally prefer small pull requests" and a person will use judgment. Codex is told it must obey the file. Our working assumption for any agent is the same: it will try to apply what you wrote, so write only what you want applied.

What belongs in AGENTS.md?

Four kinds of content earn their place.

1. Exact commands

How to install, build, run one test, run all tests, lint and type-check. Exact, copy-ready, with the flags you really use. The format's FAQ says that when you list testing commands, the agent "will attempt to execute relevant programmatic checks and fix failures before finishing the task." We think this is the highest-value part of the file, because it turns "I think it works" into a check the agent runs on its own.

2. Decisions the code cannot show

This is the part we think matters most. An agent can read your folder structure. It cannot read why the structure is that way, or which of two existing patterns is the one you want copied.

When we build with AI, the split is explicit. In implementation, AI writes the CRUD, schemas, tests, migrations and glue code. Our senior engineers own where business rules live, what runs on the server, failure handling and the security-critical paths. Our recommendation is to write decisions of that kind into the instructions file, so the agent applies them without being told each time. For example:

  • "Prices and totals are computed in server/billing. Never accept them from the client."
  • "Every new route needs an ownership check. Use requireOwner(); see routes/invoices.ts."
  • "External calls go through lib/http so retries and timeouts stay in one place."

In our view, lines like these are worth more than any style rule. In the 35+ audits we reported on in September, 18 had broken or missing authorization. As we wrote then, the code does what it was asked to do; nobody asked for the check. An instructions file is where you ask, once, for every future task.

3. Boundaries

What the agent must not touch or do: generated files, migration history, the payments module without a human, production configuration, new dependencies without asking. Keep the list short and concrete. A boundary the agent can check ("do not edit files under generated/") works better than a value it has to interpret ("be careful with core code").

Boundaries in a text file are requests, not enforcement. For anything that matters, back them with a real control, as we described in the post on sandboxing coding agents.

4. What "done" means

The checks that must pass before the agent reports success: tests green, lint clean, types clean, a test added for the changed behaviour, no skipped tests. Without this, "done" means "the code was written". The same audits found no automated tests at all in 23 codebases. A definition of done that includes a test is a cheap guard against that.

Diagram sorting AGENTS.md content into three groups: keep in the file (commands, decisions, boundaries, definition of done), move elsewhere (package rules, long docs, secrets) and cut (what the code already shows, what a linter enforces, vague values)
Diagram sorting AGENTS.md content into three groups: keep in the file (commands, decisions, boundaries, definition of done), move elsewhere (package rules, long docs, secrets) and cut (what the code already shows, what a linter enforces, vague values)

What should you leave out?

This section is our recommendation, and it is stricter than the tools' own suggestions. The AGENTS.md site lists a project overview and code style among popular sections, and Codex's generator asks for project structure and style conventions. We would cut most of that.

Leave out Why Do this instead
A tour of the folder structure The agent can list directories itself One line per non-obvious location
Rules your linter or formatter enforces The tool already fails the check List the lint command under "done"
Long architecture documents Loaded on every task, mostly irrelevant to it Link to the document; say when to read it
Rules for one package They load for work elsewhere too A nested file in that package
Values and slogans ("write clean code") Nothing to act on, nothing to check A concrete rule, or nothing
Secrets, tokens, internal URLs The file is committed and sent to a model Environment configuration
History ("we used to use X") The agent may follow the old pattern State only the current rule

A useful test for each line: would a capable new engineer get this wrong on their first task, even after reading the code? If not, delete it.

Ship faster with senior engineers

Direct collaboration, AI-augmented delivery, and no agency markup.

Get in touch

How long should it be?

Shorter than you think. The clearest number we found comes from a tool vendor's own defaults. The prompt Codex uses when it generates an AGENTS.md for a repository instructs the model: "Keep the document concise. 200-400 words is optimal." It also asks for explanations that are "short, direct, and specific to this repository."

That is a starting size for a generated guide, not a law. A file with real decisions in it may run longer. Treat length as a budget: when you add a line, look for one to remove.

How do nested files and precedence work?

In Codex's instructions, the scope of a file is the directory it sits in and everything below. When files disagree, the format's FAQ gives the rule: "The closest AGENTS.md to the edited file wins; explicit user chat prompts override everything." Codex's instructions say the same in their own words: more deeply nested files take precedence, and direct instructions in a prompt take precedence over the file.

Use this to keep the root file small.

  • Root file: commands and rules that hold everywhere.
  • Package files: what is special about that package, such as its own test command or a stricter rule for the billing code.
  • Your prompt: anything that applies to this task only.

The AGENTS.md site notes that, at the time it was written, OpenAI's main repository had 88 of these files. You do not need 88. You probably need more than one.

If your team uses several tools, pick one file as the source. Gemini CLI reads GEMINI.md by default but lets you set the file name, and its own example lists AGENTS.md. It also supports importing other files, which is another way to keep a single source.

A starting template

## Commands
- Install: `pnpm install`
- Test one file: `pnpm vitest run path/to/file.test.ts`
- All checks: `pnpm lint && pnpm typecheck && pnpm test`

## Decisions
- Business rules live in `server/domain`. Routes and UI call them; they do not copy them.
- Money, permissions and user data are handled on the server only.
- Every route that returns user data checks ownership. Pattern: `routes/invoices.ts`.
- Outbound HTTP goes through `lib/http` (timeouts and retries are set there).

## Boundaries
- Do not edit `generated/` or existing files in `migrations/`.
- Ask before adding a dependency or changing `server/billing`.

## Done means
- All checks pass, with no skipped tests.
- Changed behaviour has a test that fails without the change.

That is under 150 words. Most of it is something the agent would otherwise have to guess.

How to keep it honest

  • Review it like code. A change to this file changes the behaviour of every future task. It deserves a second pair of eyes, most of all when an agent proposed the change.
  • Add a line when the agent repeats a mistake. Twice is a pattern. Write the rule, and point to an example file.
  • Remove a line when it stops being true. A stale rule is worse than a missing one, because the agent will follow it.
  • Do not trust files you did not write. An instructions file in a cloned repository is input from a stranger, written to direct your agent. Open unfamiliar repositories with the sandbox on.
  • Re-read it every few weeks as if you were the agent. If a line would not change what you do on a typical task, cut it.
  • Writing decisions down fits the way we run AI-augmented development: AI handles repetitive execution while senior engineers handle decisions. If you want a team where senior engineers own those decisions on your product, see our SaaS development service.

    Sources: AGENTS.md project README and site content (FAQ, how-to); OpenAI Codex base instructions and AGENTS.md generation prompt; Gemini CLI context files documentation, all as published in their repositories on 22 November 2026. Entalogics figures are from our own audit reports.

    COMMON QUESTIONS

    Straight answers.

    Eight questions we get on every first call. If yours isn't here, it'll be the first thing we cover.

    It is a plain Markdown file in a repository that gives coding agents instructions for working on that project. The project behind the format describes it as a README for agents. There are no required fields or headings; the agent reads whatever text you put there.
    Short. The prompt Codex uses to generate one asks for a concise document and calls 200 to 400 words optimal. The file is loaded into the model's context along with your request. Our reading is that a long file adds cost and gives the agent more instructions that may not matter for the job in front of it.
    They do the same job. AGENTS.md is the shared, open format. Gemini CLI uses GEMINI.md by default and lets you configure other file names, with AGENTS.md shown in its own example. If your team uses more than one agent, keep one source of truth and configure each tool to read it where the tool allows.
    The one closest to the file being edited wins. The format's own FAQ says so, and Codex's instructions say more deeply nested files take precedence. A direct instruction in your prompt overrides both. This is what makes per-package files in a monorepo work.
    Usually, yes. The format's FAQ says that if you list testing commands, the agent will attempt to run the relevant checks and fix failures before finishing. That is the project's description, not a promise for every tool. It is still the main reason to list exact commands. It is also a reason to list only commands that are safe to run without asking.
    It can write a first draft. Codex has a command that generates one. Then a person should cut it down, because a generated file tends to describe what the code already shows. The lines worth keeping are the ones only your team knows: decisions, boundaries and what counts as done.
    Yes, when it comes from a repository you do not control. It is text written to instruct your agent, so a hostile file can steer it. Review changes to it like code, and open unfamiliar repositories with the agent sandboxed to limit what a hostile file can cause.

    Ready to Build Something Amazing?

    Let's discuss your project and see how we can help you achieve your goals with quality software at fair pricing.