Give the agent rules it can act on
A README explains the project to people. AGENTS.md should tell a coding agent how to work in it. A short rule such as “run npm run check:site after changing a page” is more useful than “write high-quality code” because its result can be checked.
Keep stable repository knowledge here. Put the current feature request, temporary deadlines, and one-off exceptions in the task prompt. This keeps the file useful when the next task is different.
- Describe the product and stack in two or three lines.
- Name the source directories and the files generated during a build.
- List working install, development, test, and build commands.
- State boundaries: sensitive files, secrets, and areas that require a separate request.
- Define evidence of completion, including manual checks when needed.
A small example tied to a real project
DottorLone is an Astro site that renders editorial pages as static HTML. Its articles live in src/data, routes live in src/pages, and the production build must agree with the sitemap. The following example turns those facts into actionable instructions.
Replace the paths and commands before copying it. A command that exists in this repository may not exist in yours.
# AGENTS.md
## Project
- Editorial Astro site deployed as static HTML.
- Article data lives in src/data; page routes live in src/pages.
- Never put API keys or other secrets in frontend code.
## Before editing
- Read README, the relevant files, and Git status.
- Preserve unrelated local changes.
- Keep the task within the requested scope.
## Conventions
- Reuse existing components and CSS classes.
- Avoid a new dependency when a small local solution will do.
- Check that text and layout work on mobile.
## Verification
- Run npm run check:site for the build, routes, sitemap, and metadata.
- Run npm test when pages, data, or components change.
- Check factual claims and examples separately from the build.
- Try the changed flow in a browser and inspect the console.
## Final report
- Describe the change and why it was made.
- List checks actually run and their results.
- State any remaining risk or unverified part.Make boundaries explicit
An agent cannot infer that a legacy directory is outside the current site just because the build ignores it. If editing it would be a mistake, say so. Also explain whether publishing or pushing a branch has an external effect.
Instructions are guidance, not a technical permission system. A rule saying “do not publish” does not replace repository permissions, a sandbox, or an approval step in the client.
- Name folders that should only change on an explicit request.
- State when a branch push triggers production deployment.
- Keep credentials, tokens, and private URLs out of the file.
- Avoid conflicting rules that leave the agent guessing which one wins.
Check behaviour, not just acknowledgement
Asking an agent to recite AGENTS.md only shows that it can read the file. After a real task, compare the changed files, commands it ran, and the final report against the rules. If mobile verification was required but the report mentions only a successful build, that check is still open.
Codex documents how it discovers project instructions and how more specific AGENTS.override.md files take precedence. If you change the instructions, start a fresh run and verify which rules apply at the directory where the agent works.
Keep it useful over time
- When the agent repeats a mistake, decide whether a stable rule is missing.
- When a command or directory changes, update the file immediately.
- Remove duplicated or vague instructions instead of growing the file indefinitely.
- Test the revised rules on a real task and inspect the resulting diff and checks.