An AI coding agent can only work safely with the context it receives. A good AGENTS.md
gives that context once, close to the code, so every task starts with the same commands, boundaries, and definition of done.
This guide shows a practical structure you can use with Codex, Claude Code, Cursor, GitHub Copilot, and other repository-aware coding agents.
An AGENTS.md
is not a long prompt or generic advice. It should answer the questions an experienced contributor would ask before editing:
The best file is short enough to scan and specific enough to execute.
Name the important directories and what owns them. Avoid listing every folder. Focus on the paths that determine where an agent should inspect or edit.
app/ product routes and UI
db/ schema and database access
worker/ deployment entry point
tests/ focused regression coverage
public/ static assets only
Add a sentence about where business logic belongs and where it does not. This prevents an agent from placing a quick fix in the wrong layer.
Never say “run the tests” when the repository has several test modes. Provide exact commands and explain when each one applies.
npm install
npm run lint
npm test -- path/to/relevant.test.ts
npm run build
If a command requires credentials, external services, or a long-running environment, say so. Agents should not guess at missing access or silently skip validation.
Make risky surfaces explicit. Common examples include authentication, payment flows, migrations, deployment files, generated code, lockfiles, analytics contracts, and public APIs.
A useful rule is concrete:
Do not edit generated migrations by hand. Create a new migration and include a rollback note.
A weak rule is vague:
Be careful with the database.
Specific boundaries reduce accidental scope expansion and make review faster.
Describe the smallest reliable sequence for a task:
This workflow matters because coding agents often optimize for producing code quickly. Your repository instructions should optimize for producing verified results.
A definition of done should describe evidence, not confidence:
If a validation step is impossible, require the agent to say why. An honest limitation is more useful than a false green check.
Large repositories may need more than one instruction file. Keep repository-wide rules at the root, then add narrower instructions inside high-risk or specialized areas such as payments, infrastructure, or mobile apps.
The closer file can refine commands and guardrails without repeating the entire root document. Avoid contradictions: more specific rules should clarify the general workflow, not replace its safety standards.
A practical AGENTS.md
should reduce decisions the agent must invent while preserving the decisions that belong to the developer.
Use these sections as a first draft:
Then replace every generic sentence with evidence from the repository itself.
You can inspect the free AgentBrief starter and public release before buying anything.
If you want a larger reusable library, AgentBrief Pro includes 18 AGENTS.md templates, 12 task briefs, 8 recovery playbooks, and 5 quality gates. It is an editable Markdown kit with instant delivery for $25.
If you prefer a repository-specific result, the AgentBrief site links to a fixed-scope custom AGENTS.md service delivered in 24 hours.