How to Write an AGENTS.md File for AI Coding Tools

An AGENTS.md file is a set of project instructions for AI coding agents. It tells the agent how your repo works, what commands to run, what not to touch, and what “done” actually means.

That last part matters. A coding agent with no project instructions will still try to help. It will inspect files, infer conventions, write code, run whatever tests it can find, and sometimes get surprisingly far. It will also make dumb assumptions with enormous confidence. That is the tax you pay for vague context.

A good AGENTS.md lowers that tax.

It does not need to be fancy. In fact, fancy is usually worse. The best version is short, specific, and boring exactly where boring prevents damage.

What Is AGENTS.md?

AGENTS.md is a Markdown file placed in a project so AI agents can read instructions before working in that directory.

Tool support varies. Some agents read AGENTS.md automatically, while others need you to point them at it. Either way, the file works as a reusable source of project instructions.

Think of it like a README for the agent, not the user.

A normal README explains the project to a human:

• what the app does
• how to install it
• how to use it
• where the docs live

An AGENTS.md explains how to safely work on the project:

• which commands verify a change
• which files are generated and should not be edited
• which services are live
• where secrets should never appear
• when the agent should stop and ask
• what style or architecture rules matter

If you already have a CLAUDE.md, Cursor rules, or other AI project context files, AGENTS.md fills the same general role. The filename is not the important part. The important part is repo-level instructions that travel with the project.

For the broader comparison, read the VibeCodeSource guide to CLAUDE.md, AGENTS.md, and Cursor rules. This post is the hands-on version.

Why AGENTS.md Matters in Vibe Coding

Vibe coding gets messy when the agent has to rediscover the same facts every session.

You ask for a small feature. The agent scans the repo. It guesses the framework. It guesses the test command. It guesses where the component belongs. It edits a generated file. It runs the wrong build command. Then you spend ten minutes steering it back to reality.

Usually, that is not a model problem. It is a context problem.

An AGENTS.md file gives the agent a local map before it starts wandering through your repo with a wrench.

It is especially useful when:

• the project has custom scripts
• tests require a specific command
• generated files sit next to source files
• deploys have rules
• the repo has multiple apps or packages
• you use AI agents across different tools
• you want consistent safety boundaries

The goal is not to control every token the agent writes. It is to stop the boring, preventable mistakes.

Where to Put AGENTS.md

Start with one file at the root of the project:

my-project/
  AGENTS.md
  package.json
  src/
  tests/

If your repo has separate apps, add smaller files inside those folders too:

my-project/
  AGENTS.md
  apps/
    web/
      AGENTS.md
    api/
      AGENTS.md

The root file explains the whole repo. A nested file explains what is different about that folder.

Do not copy the same giant instruction blob everywhere. That creates prompt soup. If a nested file mostly repeats the root file, it probably should not exist.

What to Include in AGENTS.md

A useful AGENTS.md usually covers eight things.

1. Project Purpose

Tell the agent what this thing is.

Bad:

# Project

This is my app.

Better:

# Project

This is a Next.js marketing site for a local remodeling company. The main goal is lead generation through service pages, blog posts, and quote-request CTAs.

That one sentence helps the agent make better decisions about copy, layout, metadata, and risk.

2. Tech Stack

List the boring facts the agent should not have to infer.

## Tech stack

- Next.js 15
- React 19
- TypeScript
- Tailwind CSS
- Content lives in `content/blog/`
- Deployed on Vercel

Keep this factual. Do not write a love letter to your framework.

3. Commands That Matter

This section pays for itself quickly.

## Verification commands

Run these before reporting success:

```bash
npm run typecheck
npm run lint
npm run build
npm test
```

If the project has a slow command, say that.

`npm run e2e` is slow. Run it only for checkout, auth, or routing changes.

If the project has no tests, say that too. Do not make the agent hunt for a test suite that does not exist.

4. File Map

Point the agent at the important folders.

## File map

- `src/app/` — Next.js routes
- `src/components/` — reusable UI components
- `content/blog/` — Markdown blog posts
- `public/images/` — static images
- `scripts/` — one-off maintenance scripts

You are not documenting every file. You are giving the agent enough of a map that it does not have to open every drawer in the kitchen.

5. Style and Architecture Rules

Add the conventions you actually care about.

## Code style

- Use TypeScript for new code.
- Prefer server components unless interactivity is needed.
- Keep components small and boring.
- Do not add a new dependency for one helper function.
- Use existing button/card/layout components before creating new ones.

Good rules are concrete. Bad rules sound like they came from a conference slide.

Bad:

Write clean, scalable, robust code.

That means almost nothing.

Better:

Do not create global state unless the data is shared across at least three routes.

Now the agent has an actual boundary.

6. Safety Boundaries

This is where AGENTS.md earns its keep.

## Safety rules

Ask before:

- deleting files
- changing database schemas
- editing authentication logic
- modifying payment code
- changing deployment settings
- adding public environment variables

Never print secrets, API keys, tokens, or `.env` contents.

Tool-level approvals still matter, but project-level rules reduce dumb proposals before they happen. If your AI workflow touches auth, deployment, credentials, or production data, read the VibeCodeSource guide to vibe coding security risks before you give an agent more access.

7. Generated Files and No-Touch Zones

Agents love editing generated files because, unfortunately, generated files look like code. Warn them off.

## Do not edit directly

- `.next/`
- `dist/`
- `coverage/`
- `node_modules/`
- generated Prisma client files
- files marked `// AUTO-GENERATED`

Also mention important files that should be changed carefully:

Ask before editing:

- `package-lock.json`
- deployment config
- auth middleware
- payment webhook handlers

8. Definition of Done

Define what “finished” means.

## Definition of done

Before saying a task is complete:

1. Run the relevant verification commands.
2. Report which commands passed or failed.
3. Mention any files changed.
4. Call out anything unverified.
5. Do not claim production deployment unless it was actually deployed and checked.

That last line saves real pain. A lot of AI-generated status updates sound like the feature shipped when all that happened was a local file edit. For live apps, pair this with a deployment checklist before you share the link. The VibeCodeSource guide to deploying a vibe-coded app is a good next step.

A Practical AGENTS.md Template

Copy this and trim it down for your project.

# AGENTS.md

This file gives AI coding agents instructions for working in this repo.

## Project purpose

[Explain what the project is, who it is for, and what matters most.]

## Tech stack

- [Framework]
- [Language]
- [Package manager]
- [Database/CMS if any]
- [Deploy target]

## File map

- `src/` — [purpose]
- `components/` — [purpose]
- `tests/` — [purpose]
- `scripts/` — [purpose]

## Verification commands

Run the relevant commands before reporting success:

```bash
[command 1]
[command 2]
[command 3]
```

If a command is slow, flaky, or requires credentials, explain that here.

## Code style

- [Concrete rule]
- [Concrete rule]
- [Concrete rule]

## Safety rules

Ask before:

- deleting files
- changing services or deployments
- modifying credentials or secrets
- changing database schemas
- touching auth, payments, or security-sensitive code

Never print secrets or `.env` contents.

## Do not edit directly

- `node_modules/`
- build output folders
- generated files
- files marked auto-generated

## Definition of done

Before reporting completion:

1. Run the relevant checks.
2. Summarize what changed.
3. List files changed.
4. Report test/build results.
5. Say what is still unverified.

Example AGENTS.md for a Small Next.js Project

Here is a filled-out version for a small content site.

# AGENTS.md

This repo is a Next.js content site. The goal is fast pages, clean SEO metadata, and simple maintenance.

## Tech stack

- Next.js
- React
- TypeScript
- Markdown blog content
- Deployed on Vercel

## File map

- `src/app/` — routes and page files
- `src/components/` — reusable components
- `content/blog/` — Markdown posts
- `public/images/` — static images
- `scripts/` — maintenance scripts

## Verification commands

Run these before reporting success:

```bash
npm run typecheck
npm run lint
npm run build
```

## Code style

- Use TypeScript for new code.
- Prefer existing components before adding new ones.
- Keep pages readable and avoid clever abstractions.
- Do not add dependencies without asking.
- Keep SEO metadata specific to the page.

## Content rules

- Do not invent stats, prices, quotes, or case studies.
- Use plain language.
- Avoid AI-sounding filler like "in today's fast-paced world" or "unlock your potential."
- Include a meta title, meta description, slug, and image alt text for new posts.

## Safety rules

Ask before:

- deleting content
- changing deployment settings
- modifying analytics
- editing environment variables
- publishing live content

Never print secrets or `.env` contents.

## Do not edit directly

- `.next/`
- `node_modules/`
- generated files

## Definition of done

Before reporting completion:

1. Run the relevant checks.
2. List changed files.
3. Report any failed or skipped checks.
4. Say whether the change was only local or actually deployed.

Common AGENTS.md Mistakes

Making It Too Long

The agent does not need your entire company handbook. If the file is so long that no human wants to read it, the agent probably will not use it well either.

Aim for one to three pages. Link out to deeper docs when needed.

Writing Vague Rules

“Write high-quality code” is not a rule. It is a wish.

Write rules with teeth:

• “Do not add dependencies without asking.”
• “Use existing components before creating new ones.”
• “Run npm run build before reporting success.”
• “Do not edit generated files.”

Mixing Permanent Rules With Temporary Tasks

Do not put today’s TODO list in AGENTS.md.

Bad:

Today, fix the homepage hero and update the pricing page.

That belongs in an issue, task file, or chat. AGENTS.md should hold rules that will still be true next week.

Forgetting the Definition of Done

Agents are very good at sounding finished. Make the work prove it.

A good definition of done forces the agent to separate:

• files edited
• checks run
• checks skipped
• local changes
• deployed changes
• assumptions

That separation is the difference between useful automation and a confident mess.

Letting the File Go Stale

A stale AGENTS.md can be worse than no file because it gives bad instructions with authority.

Update it when:

• test commands change
• the framework changes
• folders move
• deploy rules change
• a recurring agent mistake shows up
• you add or remove major services

If the agent keeps making the same mistake, do not just correct it in chat. Put the fix in AGENTS.md.

AGENTS.md vs CLAUDE.md vs Cursor Rules

Use whatever your tool reads best.

• AGENTS.md for agent-readable project instructions
• CLAUDE.md for Claude Code-specific context
• Cursor rules for Cursor-specific behavior
• README for humans using the project

If you use multiple AI coding tools, keep the core rules consistent. Do not let three instruction files drift into three different versions of reality. That is how you get one agent running pnpm, another running npm, and a third confidently editing build output like a raccoon in a fuse box.

This pairs naturally with structured multi-agent work — see how to use AI coding subagents without creating agent chaos, where shared project rules keep a coordinator and its specialists on the same page.

A Simple Way to Start

Do not overbuild this.

Create a root AGENTS.md with four things:

1. What the project is.
2. Where the important files live.
3. Which commands verify the work.
4. What the agent must ask before touching.

That is enough to make most AI coding sessions less chaotic. Clear, specific instructions here are the same skill as writing better AI coding prompts — just saved to a file the agent reads every time.

You can add nested files later if the project grows.

FAQ

What Should Be in an AGENTS.md File?

An AGENTS.md file should include the project purpose, tech stack, file map, verification commands, coding rules, safety boundaries, generated-file warnings, and definition of done.

Where Should AGENTS.md Go?

Start with one AGENTS.md at the root of the repo. Add nested AGENTS.md files only for folders that need different instructions, such as a separate web app, API, or package.

Is AGENTS.md the Same as CLAUDE.md?

Not exactly. CLAUDE.md is commonly used for Claude-specific project context. AGENTS.md is a more general agent-instruction file. In practice, they often contain similar rules. The important part is keeping your project instructions consistent across tools.

How Long Should AGENTS.md Be?

Short enough to stay useful. For most projects, one to three pages is plenty. If it starts turning into a runbook, split deeper details into linked docs and keep AGENTS.md focused on the rules agents need before editing.

Should Every Project Have an AGENTS.md File?

If you use AI coding agents regularly, yes. Even a small file with the project purpose, file map, test commands, and safety rules will prevent repeated mistakes.

Final Checklist

Before you call your AGENTS.md done, check it against this list:

• It explains the project in one or two plain sentences.
• It names the tech stack.
• It lists the real verification commands.
• It says where important files live.
• It warns about generated files.
• It defines risky actions that need approval.
• It tells the agent not to print secrets.
• It defines what “done” means.
• It avoids temporary TODOs.
• It is short enough that you would actually read it.

If your file passes that list, you are already ahead of most vibe-coded projects.

Not because AGENTS.md is magic. It is not. It is just a small guardrail that keeps the robot from driving into a ditch and confidently calling the ditch part of the route.