How to Write an AGENTS.md for Codex, Claude Code, and Cursor

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.

What an AGENTS.md file should do

An AGENTS.md is not a long prompt or generic advice. It should answer the questions an experienced contributor would ask before editing:

• What does this repository contain?
• Which commands install, test, lint, type-check, and build it?
• Which files are generated or protected?
• Where should new code go?
• What evidence is required before a task is complete?
• Which changes need extra review because they affect security, data, payments, or public APIs?

The best file is short enough to scan and specific enough to execute.

1. Start with a repository map

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.

2. Write commands that can actually run

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.

3. Define boundaries and protected areas

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.

4. State the workflow

Describe the smallest reliable sequence for a task:

1. Inspect the relevant files and existing tests.
2. State material assumptions before editing.
3. Make the smallest complete change.
4. Add or update focused regression coverage.
5. Run the narrow checks first, then broader validation.
6. Report what changed, what passed, and what remains uncertain.

This workflow matters because coding agents often optimize for producing code quickly. Your repository instructions should optimize for producing verified results.

5. Make “done” testable

A definition of done should describe evidence, not confidence:

• The requested behavior works on the primary path.
• Relevant failure states are covered.
• Type checks, focused tests, and the production build pass.
• Unrelated behavior and existing user changes are preserved.
• The final handoff names residual risk and checks that could not run.

If a validation step is impossible, require the agent to say why. An honest limitation is more useful than a false green check.

6. Put specific instructions close to the code

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.

Common mistakes

• Copying a generic template without checking the actual repository.
• Listing commands that do not exist.
• Writing philosophy instead of executable rules.
• Omitting generated files and protected areas.
• Requiring every possible test for every tiny change.
• Forgetting to define what the final handoff must contain.
• Letting task instructions conflict with repository constraints.

A practical AGENTS.md should reduce decisions the agent must invent while preserving the decisions that belong to the developer.

A compact starter structure

Use these sections as a first draft:

• Repository map
• Setup and commands
• Editing rules
• Protected areas
• Testing and quality gates
• Definition of done
• Handoff requirements

Then replace every generic sentence with evidence from the repository itself.

Verify the method or skip the setup work

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.