# What is an AGENTS.md file > Use AGENTS.md to give coding agents durable project instructions, from commands and conventions to scoped rules, verification, maintenance, and common mistakes. Author: [Flavio Copes](https://flaviocopes.com/about/) | Published: 2026-09-03 | Topics: [AI](https://flaviocopes.com/tags/ai/) | Canonical: https://flaviocopes.com/agents-md/ `AGENTS.md` is a Markdown file that tells coding agents how to work in a repository. Think of it as a README for the agent. A human README explains the product and helps people get started. `AGENTS.md` records the commands, boundaries, conventions, and traps an agent needs while changing the project. The file is plain text. The useful part is not the format. The useful part is keeping durable project knowledge beside the code. ## Why the file exists A new agent session does not reliably know yesterday's correction. It can guess the package manager, run the wrong test, edit generated files, or miss a deployment constraint. You then repeat the same instructions in every chat. `AGENTS.md` moves those facts into the repository: ```text repeated correction -> durable rule -> every future task sees it ``` This is a small change with a large effect. The agent spends less time discovering conventions, and you spend less time repairing avoidable mistakes. The free [AI Fundamentals course](https://flaviocopes.com/courses/ai-fundamentals/) explains how durable rules fit with prompts, context, tools, and verification. ## Create the first file Put `AGENTS.md` in the repository root. Start small: ```markdown # Project instructions ## Setup - Install dependencies with `npm install`. - Run the development server with `npm run dev`. - Run the complete check with `npm test`. ## Code - Application code lives in `src/`. - Generated files live in `dist/`. Do not edit them. - Use two spaces for indentation. ## Before finishing - Run `npm test`. - Report any test you could not run. ``` This gives the agent commands, a map, a hard boundary, and a definition of done. You do not need to document the whole system. Add the facts that prevent expensive guesses. ## What belongs in AGENTS.md Good instructions are **durable**, **specific**, and **actionable**. ### Commands that really work List the exact commands an agent should run: ```markdown ## Commands - `npm run dev`: start the site on port 3000. - `npm run check`: validate Astro and TypeScript. - `npm test`: run the test suite. - `npm run build`: build the production site. ``` Explain unusual requirements beside the command. If tests need Docker or a local database, say so. Do not write “run the tests” when the repository has five test commands. Name the command that proves the change is safe. ### A short architecture map Point to the important boundaries: ```markdown ## Architecture - UI components live in `src/components/`. - HTTP routes live in `src/pages/api/`. - Database access goes through `src/data/`. - Do not query the database from UI components. ``` The last line is more useful than a long architecture essay. It tells the agent which dependency direction is allowed. ### Project conventions Record choices that cannot be inferred from the language: ```markdown ## Conventions - Use `npm`, not `pnpm` or Yarn. - Keep public API errors free of internal details. - Add a migration for every schema change. - Add a 301 redirect when deleting or renaming a public page. ``` A formatter can enforce spacing. `AGENTS.md` should focus on choices a formatter cannot make. ### Safety boundaries State actions that need special care: ```markdown ## Safety - Never print or commit secrets. - Never write to the production database from local tests. - Do not deploy unless the user explicitly asks. - Ask before adding a production dependency. ``` These rules do not replace permissions or sandboxing. They add project-specific intent. ## What does not belong Do not put secrets in `AGENTS.md`. The file normally lives in version control and may be sent to an AI service with the task. Do not put temporary status there: ```markdown - We are fixing checkout this week. - Sara is reviewing pull request 42. - The staging server is down today. ``` That information expires. Put it in a ticket, work log, or current task. Do not copy entire manuals into the file. Link to stable project documentation when the agent only needs the detail occasionally: ```markdown ## Deployment - Follow `docs/deployment.md` for releases and rollback. - Never force-push a release branch. ``` Do not fill the file with rules the codebase already enforces automatically. If Prettier fixes quote style, let Prettier own quote style. ## How scope works Support differs between coding agents, so check the documentation for the tool you use. Codex builds its instruction chain in two parts. It first checks the Codex home directory, normally `~/.codex/`, for global guidance. `AGENTS.override.md` wins when it exists. Otherwise Codex reads `AGENTS.md`. It then starts at the project root and walks down to the current working directory. In each directory, it checks `AGENTS.override.md` before `AGENTS.md` and reads at most one instruction file. Instructions from deeper directories appear later, so they can override broader project guidance. The combined project instructions have a size limit. Codex uses 32 KiB by default. If a large root file is approaching that limit, move detailed procedures into focused documents and link to them instead of assuming every line will be loaded. This lets a monorepo define a general rule at the root and a narrower rule inside one package: ```text shop/ ├── AGENTS.md ├── apps/ │ ├── storefront/ │ │ └── AGENTS.md │ └── admin/ └── packages/ └── payments/ └── AGENTS.md ``` The root file might say: ```markdown - Use `npm` workspaces. - Run `npm test` before finishing. ``` `packages/payments/AGENTS.md` can add: ```markdown - Treat amounts as integer minor units. - Run `npm test --workspace payments` after payment changes. - Never log payment payloads or webhook secrets. ``` Keep shared rules at the root. Add a nested file only when a subtree has genuinely different commands or constraints. Some agents only read the root file. If a nested rule is critical across tools, keep a short version at the root and link to the detailed file. ## Resolve conflicts deliberately Instructions can disagree. Imagine the root says: ```markdown - Use PostgreSQL for application data. ``` A nested test fixture says: ```markdown - Tests in this folder use SQLite. Do not replace it. ``` The narrower rule makes sense because its scope is clear. Accidental conflicts are different. If one section says `npm test` and another says tests must never run locally, the agent has to guess which instruction is current. Remove old rules instead of stacking exceptions on top: ```markdown - Run `npm test`, except in old projects, unless CI is active, but only... ``` When a rule needs that many conditions, move the logic into a script. Give the agent one command. ## Write for execution An agent needs to decide what to do next. Write instructions that support that decision. This is vague: ```markdown - Be careful with content. ``` This is executable: ```markdown - Before deleting an image, search `src/posts/` for references. - A missing referenced image makes the production build fail. ``` This is also vague: ```markdown - Follow best practices. ``` Replace it with the project choice: ```markdown - Validate request bodies at the route boundary with Zod. - Return `400` for invalid input. ``` Use short bullets. Put the reason on the same bullet only when it changes how the agent applies the rule. ## Include verification Every important rule should have a way to check it. For example: ```markdown ## Content checks - Run `npm run content:check` after editing posts. - Run `npm run build` after adding images or internal links. - Confirm future-dated posts do not link to later drafts. ``` The agent now knows both the expected behavior and the evidence needed before finishing. This is especially useful for tasks that look done after a file edit but can still fail during the production build. ## Maintain the file from real mistakes Do not try to predict every future problem. Use a simple maintenance loop: 1. Notice a correction you had to repeat. 2. Decide whether it is durable project knowledge. 3. Put it at the narrowest useful scope. 4. Remove any older instruction it replaces. 5. Test it on the next relevant task. Repeated corrections are strong candidates. One unusual task is not. Review the file when commands, deployment, or architecture changes. A stale instruction is worse than a missing one because it sounds authoritative. ## Common mistakes ### Turning the file into a novel Long context competes with the task and the code. Keep the main file scannable. Move deep operational procedures into `docs/`. ### Mixing preferences with hard rules “Prefer small functions” is guidance. “Never run migrations against production” is a boundary. Use direct language for both, but do not pretend every preference has the same risk. ### Depending on chat memory If the fact must survive a new session, put it in the repository. Chat is not durable project state. ### Describing a command that no longer works Run the command yourself after adding it. An instruction file full of broken commands teaches the agent to ignore the file. ### Adding tool-specific claims as universal rules Nested-file discovery and precedence differ. Name the tool when behavior belongs to one agent. ## How I use AGENTS.md I use `AGENTS.md` as the memory of the repository. I put the build commands there, but the most valuable lines are usually the strange ones: a configuration name that must match a hosted project, a folder that looks generated but is not, or a redirect rule that must stay at the end of a file. Those facts are easy to forget after three months. They are also expensive for an agent to rediscover by breaking something. I do not use the file as a daily to-do list. Plans and current work belong elsewhere. `AGENTS.md` is for the facts I still expect to be true next month. It is a poor fit for product documentation meant for customers. If an agent needs the site's actual content, I can point it at [Markdown versions of the site](https://flaviocopes.com/serving-markdown-to-ai-agents/) or the source files. `AGENTS.md` tells it how to work, not what every page says. ## A practical final template Use this as a starting point: ```markdown # Project instructions ## Setup - Install with `npm install`. - Start development with `npm run dev`. ## Project map - Application code: `src/` - Tests: `tests/` - Operational docs: `docs/` - Generated output: `dist/` — do not edit. ## Rules - Keep changes inside the requested scope. - Never commit secrets or `.env` files. - Ask before adding production dependencies. ## Verification - Run `npm test` after code changes. - Run `npm run build` after routing or content changes. - Report skipped checks and the reason. ``` Delete the lines that do not apply. Add project facts only when they earn their place. The goal is not a perfect instruction manual. The goal is to stop the repository from teaching the same lesson twice.