The Complete AGENTS.md Playbook: Build AI Coding Agents That Work Like Your Best Engineer

Most AGENTS.md guides stop at “here’s what the file looks like.” That’s the easy 20%.

The hard part is the content inside each section — and knowing which sections earn their place at all. That’s what decides whether your agent produces code your team would have written anyway, or code that technically works but gets rewritten in review.

This is the long version. What actually belongs in a serious AGENTS.md, what doesn’t, the mistakes that show up again and again, whether you can just let Copilot write it, and a full template at the end you can copy and cut down.

What AGENTS.md is, and why you need it now

AGENTS.md is a plain-text file your AI coding agent reads automatically, before it writes anything. It describes how your project is actually built — the architecture, the conventions, the boundaries, the things a new contributor would otherwise learn the hard way.

It’s not a persona. It’s not something you invoke. It’s context loaded behind the scenes, every session, the same way for every developer touching the repo.

Why it matters now is pretty mechanical. Agents write a real share of new code today, and every generation is a decision — which state pattern, which error style, which folder something belongs in. With no shared file, every one of those decisions gets made independently, by whichever session happens to be running. Multiply that across a team, or across your own sessions six months apart, and inconsistency stops being a risk. It’s the default.

README.md vs. AGENTS.md

People mix these up constantly, so let’s be precise.

An out-of-date README is an annoyance — someone loses ten minutes finding the real install command. An out-of-date AGENTS.md is worse. It silently steers every future AI-generated feature toward the wrong pattern, for as long as it stays wrong.

How agents actually use the file

The file gets loaded into context before generation. It’s not consulted mid-task like a lookup table.

That has one practical consequence: everything in the file competes for the agent’s attention with your actual prompt and the code it’s looking at right now. A ten-line file with five sharp rules gets followed more reliably than a two-hundred-line file where those same five rules are buried in detail the agent has to weigh against everything else.

It’s also why editing the file mid-session fixes nothing. Start a new session so the update is actually part of what gets loaded.

The anatomy of a well-designed AGENTS.md

Here are the sections worth having, roughly in the order they matter. Not every project needs all of them. A solo side project might only want the first four. An enterprise codebase probably wants most of the list.

Project overview

Two or three lines: what it is, the core stack, target platforms. This exists purely to stop the agent from guessing the basics.

Flutter Food Delivery app. Flutter 3.x, Dart 3.x. Android and iOS.
Firebase backend, REST APIs for payment and logistics providers.

Architecture rules

Name the architecture out loud — Clean Architecture, MVVM, Feature-First, whatever’s actually in use. Say it in a way that leaves no room for a “reasonable” alternative.

Feature-First Clean Architecture. Each feature owns its own data,
domain, and presentation layers. Do not introduce a different
architectural pattern for new features, even a well-known one.

Folder structure

Show it. Don’t describe it in prose. A literal tree is faster for both humans and agents to read correctly.

lib/
├── core/            # shared services, network, theme
├── features/        # one folder per feature, self-contained
│   ├── cart/
│   ├── orders/
│   └── payment/
└── main.dart

Coding standards

The small, constant rules a linter won’t give you: prefer const constructors, keep functions short, avoid deeply nested conditionals. Whatever’s specific to how your team actually writes code day to day.

Naming conventions

State the case convention per context — classes, files, variables, constants. “Follow standard conventions” means something different in every language, and it gets read differently every time.

Error handling standards

One approach, stated plainly. This is one of the highest-impact sections in the whole file. If every feature handles failure differently, every feature also gets tested and reviewed differently.

API errors return a Result<T, Error> type. Never throw exceptions
across a repository boundary. Log unexpected errors through the
shared Logger service, never with print() or console.log().

Security guidelines

This is the section most AGENTS.md files skip, and it’s the one that costs the most when it’s missing. Say what must never happen — hardcoded secrets, credentials in client-side code, unsanitized input reaching a query. These feel obvious to you. They aren’t obvious to a model that has no view into your compliance requirements.

Never hardcode API keys or secrets — use environment configuration.
All user input must be validated before reaching the data layer.
Payment data never touches application logs, structured or otherwise.

Performance expectations

Only where it’s genuinely a constraint — image loading strategy, pagination, list virtualization for long lists. Skip this if performance isn’t a distinguishing concern. Padding it with generic advice only weakens the sections that matter more.

Testing requirements

Name which test types apply and what triggers writing one. “Every new repository method needs a unit test” is something an agent can act on. “Write good tests” isn’t.

Git workflow

Branch naming, commit message format, and whether the agent may commit directly or should only propose changes for review.

Pull request checklist

If your team has one, put it here. It gives the agent something concrete to check itself against before handing back a finished feature.

Documentation expectations

Whether new public functions need doc comments, whether a new feature needs an entry in an internal docs folder. Often skipped, rarely enforced unless it’s written somewhere the agent reads.

AI-specific instructions

This section does the most actual work, so it’s worth its own explanation. Generic coding standards apply to humans and agents alike. This section is specifically about agent behavior:

- Reuse existing components and services before creating new ones
- Never duplicate business logic already implemented elsewhere
- Do not introduce a new package or dependency without flagging it explicitly
- Do not modify generated code (build_runner, protobuf, etc.)
- When two valid approaches exist, prefer the one already used in this codebase
- Prefer consistency with existing code over a "better" alternative pattern

Approved and forbidden libraries

Name what’s already in use, and explicitly rule out the common alternatives an agent might otherwise reach for. “Use Riverpod” is good. “Use Riverpod, not Provider or Bloc” closes the door the first version leaves open.

Business rules the AI must never violate

Narrow, boundary-only. Not an explanation of your business — a hard constraint the agent respects no matter how a prompt is worded.

- Never mark an order as paid without a confirmed payment gateway response
- Never expose a user's full payment details in logs, responses, or error messages
- Refund logic must always go through the RefundService, never a direct database write

Things that should never go in the file

Worth stating as clearly as what belongs, because the failure mode here is different. This isn’t a weaker file — it’s a liability.

Guidelines for a genuinely good AGENTS.md

If you remember nothing else, remember these. They’re the habits that separate a file that works from one that just exists.

1. Be specific enough that a violation would be obvious in review. If a rule is vague enough that you can’t tell whether code broke it, the agent can’t either.
2. One rule per line, one idea per rule. Long compound sentences hide the actual instruction. Short bullets get followed.
3. Name one approved pattern, not a menu. “Use Riverpod for state” beats “we generally use Riverpod but Bloc is fine too.” The second one is permission to be inconsistent.
4. Write rules as constraints, not preferences. “Never throw across a repository boundary” lands harder than “try to avoid throwing across boundaries.”
5. Keep it short on purpose. Every line competes for attention. If a section isn’t earning its place, cut it.
6. Only write down what you’ve actually decided. Don’t use the file to quietly win an architecture debate the team never had. That surfaces fast in review and it poisons trust in the rest of the file.
7. Test it. Open a fresh agent session, ask it to describe your stack and conventions back to you. If it gets them wrong, the file is wrong.
8. Treat it like code, not docs. Same PR, same review, same git history. More on this below.

Common mistakes teams make writing this file

Treating specificity as optional. “Follow best practices” and “write clean code” show up constantly and mean almost nothing — best practices differ by team, by language, and sometimes by which senior engineer you ask. Every vague line is a line the agent has to interpret, and it’ll interpret it differently in different sessions.

Writing it once and calling it done. A file describing last year’s architecture actively misdirects new code toward decisions that already got reversed.

Scope creep. The file grows to cover onboarding, culture, meeting notes, roadmap context — because once someone’s already editing it, everything nearby feels like it belongs. It doesn’t. If a line isn’t a coding rule or a boundary, it’s probably in the wrong document.

Rules that sound official but were never agreed on. It’s tempting to use the file to settle an architecture debate no one actually settled. That surfaces fast in review, and it undermines the whole file once one section turns out to be somebody’s personal preference dressed up as policy.

Can Copilot generate this file for you?

Yes — partly. And “partly” is the whole answer, so it’s worth being precise about the line.

Type /init in Copilot Chat and it scans the repo and drafts a file from what it finds. It’s genuinely good at the inferable parts: your dependencies, an existing consistent folder structure, a pattern that’s already used uniformly across the code.

What it can’t know:

• Your security policy and any compliance rules specific to your industry
• Which of two competing patterns already in your code is the one you actually want going forward
• Business rules that live only in someone’s head or an old Slack thread
• Which conventions are deliberate versus just what happened to get typed first

So the honest answer to “should I generate it or write it by hand?” is both — generate first, then correct by hand. A blank file wastes the time Copilot would save you on the boring parts. But shipping Copilot’s draft untouched is risky, because it describes what your code looks like today, not what you’ve decided it should look like. The draft is a first pass. The human edit is what makes it correct.

If you let Copilot generate it: the checklist

Run through every one of these before you commit the generated file. This is where the “human edit” actually happens:

• Read every line. Don’t trust it because it’s plausible. Plausible is exactly the failure mode.
• Check which pattern it picked. If your code has both Provider and Riverpod, Copilot may have documented whichever it saw first — not the one you’re standardizing on. Fix it.
• Add the security section. Copilot almost never infers this. Write your real constraints: secrets handling, input validation, what must never be logged.
• Add business rules by hand. These live nowhere in the code, so Copilot cannot invent them. If you don’t add them, they don’t exist.
• Delete the filler. Generated drafts pad with generic “write clean code” advice. Cut anything that isn’t specific enough to catch a violation in review.
• Confirm no secrets or real data got scooped up. If the scan pulled an example key or a real endpoint into the draft, remove it now, before it’s in git history forever.
• Resolve conflicts with your linter and CI. Anything the draft says that fights your existing config becomes a standing argument the agent can’t win. Reconcile them.
• Name owners and off-limits folders. Add who owns the file and which folders (generated code, migrations) the agent must never touch.
• Test it on a fresh session. Ask a clean agent to describe the stack and conventions back. If it’s wrong, the file is wrong — fix it before you rely on it.

Do that, and you’ve kept the time Copilot saved you without inheriting the risk of trusting a draft blind.

Keeping it in sync with the actual project

The practical version: treat AGENTS.md edits like code changes, not documentation edits. Same PR, same review. Ideally a lightweight rule — any PR that changes a core pattern (swapping a library, moving folders) updates the file in the same PR, not later. “Later” is where these files go stale.

Enterprise governance for AI coding agents

At team scale, a few extra habits matter beyond writing the file well:

• Ownership. Someone specific owns the root file — usually whoever owns architecture decisions. Nested, squad-specific files can be owned by that squad, with the root file as the shared baseline.
• Review, not unilateral edits. Changes go through the same review as code, precisely because a quiet edit here changes behavior for every developer’s agent sessions at once, not just the editor’s.
• Version history. It’s just a file in the repo, so git blame already gives you an audit trail. Use it. When a rule changes, the commit message should say why.
• Pair it with human onboarding. AGENTS.md complements onboarding, it doesn’t replace it. It answers “how do I write code that fits,” not “why do we do things this way.” Pair it with whatever your team already does for the second question.

A complete AGENTS.md template

Everything above, assembled into one file. Delete whatever doesn’t apply — most projects won’t need all of it.

# AGENTS.md

## Project Overview
[App name]. [Core stack]. [Platforms]. [Backend].

## Architecture
[Named pattern]. [One line on how features are organized.]
Do not introduce a different architectural pattern for new features.

## Folder Structure
[Literal tree of your actual structure]

## Coding Standards
- [Rule]
- [Rule]

## Naming Conventions
- Classes: [convention]
- Files: [convention]
- Constants: [convention]

## Error Handling
[One approach, stated as a rule, not a suggestion.]

## Security Guidelines
- Never hardcode secrets or credentials
- [Project-specific security rule]
- [Project-specific security rule]

## Performance Expectations
[Only if genuinely a constraint for this project]

## Testing Requirements
- [Test type]: [when it's required]

## Git Workflow
- Branch naming: [convention]
- Commit format: [convention]

## Pull Request Checklist
- [ ] [Item]
- [ ] [Item]

## Documentation Expectations
[What needs doc comments, what needs a docs entry]

## AI-Specific Instructions
- Reuse existing components before creating new ones
- Never duplicate business logic
- Do not introduce new dependencies without flagging it
- Do not modify generated code
- Prefer consistency with existing code over a "better" alternative

## Approved Libraries
- [Library]: use for [purpose]
Do not use: [explicitly ruled-out alternatives]

## Business Rules (Hard Constraints)
- [Rule the AI must never violate]
- [Rule the AI must never violate]

## Off-Limits
- [Folder/file the AI should never modify]

A worked example: Flutter food delivery

To make this concrete, here’s how a chunk of that template might get filled in for a food delivery app. It’s illustrative, not a real production file, but realistic enough to show the shape:

## Architecture
Feature-First Clean Architecture. features/cart, features/orders,
features/payment each own their data/domain/presentation layers.

## Error Handling
Result<T, Error> from repositories. Never throw across a repository
boundary. UI layer shows user-facing messages via the shared
ErrorPresenter — never a raw exception message.

## Security Guidelines
- Payment tokens are never logged, in any environment
- No card data is stored client-side, ever — tokenization only

## Business Rules (Hard Constraints)
- Never mark an order "confirmed" without a successful payment gateway response
- Refunds only go through RefundService — no direct database writes
- Delivery address changes are blocked once an order enters "preparing" status

Notice how specific these are. None of them say “write secure code.” Every line is something an agent can actually check itself against.

Do’s and don’ts, condensed

A quick checklist before you commit it

• Every rule is specific enough that a violation would be obvious in review
• The security section exists and names actual constraints, not generalities
• Exactly one approved pattern is named for state and data, not several options
• No secrets, credentials, or real customer data anywhere in the file
• Off-limits folders (generated code, migrations) are listed explicitly
• Someone specific owns updates, and changes go through review
• You tested it — a fresh agent session asked to describe the stack back gets it right

Key takeaways

• The difference between a useless AGENTS.md and a genuinely effective one is specificity, not length — a dozen sharp rules beat a hundred vague ones.
• Security, business-rule boundaries, and AI-specific instructions are the sections most guides skip and most projects actually need.
• Never put secrets, real customer data, or long strategic reasoning in the file. Keep it to rules and boundaries.
• Copilot’s /init drafts the inferable parts well, but only a human can pick which existing pattern is right and write down the business rules that live nowhere else — so generate first, then edit by hand against the checklist.
• Treat it as living, reviewed code — update it in the same PR that changes the pattern it describes, not later.