Skip to content
TechTipsEasy Find a guide

Coding agents

How to write AGENTS.md for coding agents

Create an AGENTS.md that tells coding agents what to edit, what to avoid, how to verify work and when to stop for human approval in real projects.

By TechTipsEasy · · 4 min read

What AGENTS.md should do

AGENTS.md is a project contract for coding agents. It should answer the questions a careful teammate would ask before editing: what files are source, what files are generated, how to run checks, what should never be changed casually, and which human approvals are required. The Codex AGENTS.md guide describes how Codex discovers these files and applies the closest relevant instructions. Claude Code can also read repository guidance such as AGENTS.md and CLAUDE.md, according to the Claude Code overview. The format is simple; the discipline is deciding what belongs there.

Keep it short and operational

A good AGENTS.md is not a culture deck. It is a checklist the agent can execute. Prefer specific commands over vague advice. Write Run npm run build before changing deployed pages instead of make sure everything works. Name ownership boundaries. If generated files should not be hand-edited, say which directories are generated and which script creates them. If deployment is sensitive, say who owns deployment and what confirmation is required.

Starter template

# Project agent instructions

## Scope
- Source files live in src/.
- Generated output lives in site/ and must not be hand-edited.
- Article files live in src/articles/*.json.

## Verification
- Run npm run build before deployment-related work.
- For article-only work, validate JSON syntax and required metadata.

## Safety
- Do not commit, deploy, email, or change networking without explicit user approval.
- Never store secrets in repository files, examples, docs, migrations, or notes.

## Style
- Keep edits scoped to requested files.
- Preserve existing patterns unless the task asks for a refactor.

Adjust the template to your project. The point is not to cover every possible mistake. The point is to make the common safe path obvious.

Where to place details

Put repository-wide rules at the root. Put package-specific rules in a nested AGENTS.md near the package. If the frontend and backend have different test commands, each can have a local instruction file. Avoid copying the same rule into five places. When two instruction files conflict, closer instructions may matter more for the files being edited, so make local files more specific and root files more general.

Use context engineering

Anthropic describes context as a finite resource in its context engineering guide. That idea applies directly to AGENTS.md. Every extra paragraph competes with source code, diffs and test output. Include high-signal constraints: dangerous directories, verification commands, deployment rules, data privacy rules and project-specific terminology. Leave general software advice out. The agent already knows common practices; it needs your local facts.

Problems to check

  • Too vague: instructions say to test thoroughly but do not name commands or expected outputs.
  • Too long: the file becomes a manual, and important constraints are buried.
  • Too stale: commands change, but agents keep following old instructions. Review AGENTS.md when build scripts change.
  • Too permissive: deployment, networking and secret handling rules are missing because humans assume common sense.

Review checklist

  1. Can a new agent identify source versus generated files?
  2. Can it find the smallest valid verification command?
  3. Does it know which actions need explicit approval?
  4. Does it know where secrets must not appear?
  5. Does the file avoid one-off task instructions?

After you write AGENTS.md, test it with a harmless task. Ask an agent to explain which files it may edit and what command it would run. If the answer is vague, the file needs sharper instructions. If the answer is bloated, the file needs deletion more than addition.

Maintenance rhythm

Review AGENTS.md whenever you change package managers, deployment paths, validation scripts, article formats or ownership boundaries. A stale instruction file can send the agent confidently through the wrong procedure. Add a short date note only when it helps maintainers know why a rule exists. Delete rules that no longer guide real work.

Rule examples

Good rules name a behavior and a trigger. For example: ask before modifying database migrations, ask before changing public routes, and never overwrite user edits. Weak rules say be careful. Strong rules tell the agent when caution changes into a required pause.

Enforce permissions outside the instruction file

AGENTS.md explains a boundary to the model. Runtime permissions, account scopes and deployment controls enforce it. For example, a rule saying to draft customer replies cannot stop a sending tool that the agent is already allowed to execute. Keep that tool unavailable or require review at the action boundary. Test project guidance with two harmless prompts: one that asks for the normal edit path, and one that asks to bypass a listed rule. Check the actual commands and files touched. If a prohibited action runs, repair the permission setup as well as the wording. A longer instruction file is an unreliable substitute for restricting the capability.

Sources and further reading

Documentation checked October 4, 2026. Product features and availability can change.

Keep learning