How to write AGENTS.md so AI doesn't break your repo

The first thing your AI reads when it touches your repo isn't your code. It's a file you may not have written yet.

AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules — same idea, different filename. It's the standing instruction set the AI follows on every turn. Without it, the AI falls back to its training data, which doesn't know your codebase. With a good one, you skip 80% of the recurring "why did the AI do that?" frustrations.

This post is what to put in the file, what to leave out, and how to have Claude draft one without ending up with 400 lines of corporate-flavored filler.

Why this matters more than people think

Every time you prompt the AI, this file is part of the context. So a single line in it is functionally a permanent rule across all future sessions. That's enormous leverage — and most people either skip it entirely or paste a generic template they found on GitHub.

The cost of skipping it:

• The AI uses the wrong framework version. (Next.js 14 patterns in a Next.js 16 codebase, React 18 idioms in React 19, etc.)
• The AI re-invents conventions you already have. New utility file when one exists. New error handler when there's a shared one.
• The AI does "demo quality" work in a production repo. Wrong defaults, wrong assumptions about what's acceptable.
• The AI refactors aggressively when you wanted a one-line fix.

Each of these is preventable in one sentence in this file.

The minimum viable version (one line)

The simplest AGENTS.md that earns its keep:

This is NOT the [framework] you know. Read the relevant guide in [path] before writing any code.

That alone prevents the majority of "AI confidently uses wrong API" failures. If you write nothing else in the file, write that. Then keep going.

The seven sections that earn their keep

In order of impact:

1. Don't trust your training data

Frameworks/libraries that have changed since the model's cutoff. Where the current docs are. Example: "Next.js 16 deprecated pages/. App Router is the only API. If you're about to write getServerSideProps, stop and read node_modules/next/dist/docs/."

2. What this repo is and isn't (one paragraph)

"This is a B2B SaaS dashboard with authenticated users, role-based access, and audit logging. Code that bypasses any of those is wrong by definition." That paragraph anchors every later decision.

3. The conventions you actually enforce

Not "we use TypeScript." That's obvious from the file extensions. The non-obvious ones:

• "API routes return JSON only, never redirects."
• "All dates are ISO strings end-to-end. Never Date objects in API contracts."
• "User input goes through validateInput() before reaching the DB layer."

These are the rules that, when broken, lead to subtle bugs across multiple PRs.

4. Anti-patterns specific to this repo

The "do not" list. This is where you encode hard-won pain:

• "Don't add new packages without asking — every dependency is a maintenance burden."
• "Don't refactor unrelated code while fixing a bug."
• "Don't write new files in /lib unless extending an existing pattern."

The why for each is what makes it stick. "Don't add new packages" without context gets ignored. "Don't add new packages — we had a 3-week supply chain incident with a 200-line lodash competitor" gets followed.

5. Path map (where to find things)

Three or four lines, max. "Database queries: lib/db.ts. API routes: app/api/. Components: components/. Tests: __tests__/ next to the source." This stops the AI from re-creating files in the wrong place.

6. Test/build commands (exact strings)

"Run all tests: pnpm test. Run one: pnpm test -- <pattern>. Build: pnpm build. Lint: pnpm lint." Saves dozens of "what's the test command?" round-trips.

7. Deploy gates

What must be true before merging: tests pass, types check, no console.log in source, no TODO without a ticket, schema migrations have rollbacks. The AI will run these without being prompted if the rule lives in the file.

What goes wrong without each section

• No section 1: AI hallucinates outdated framework patterns into your modern codebase.
• No section 2: AI writes "demo quality" code with wrong defaults.
• No section 3: New PRs invent new conventions; the codebase drifts.
• No section 4: Same expensive mistake every two weeks.
• No section 5: Duplicate files, broken imports, refactor PRs nobody asked for.
• No section 6: AI runs the wrong commands, misreads the output, gets stuck.
• No section 7: Things merge that shouldn't.

How to ask Claude (or any AI) to draft it for you

The trap: ask "write AGENTS.md for my repo" and you get 400 lines of generic best-practices filler. Half of it doesn't apply. None of it has teeth. Here's how to get something useful instead.

Step 1: Have it scan the repo first

"Don't write anything yet. Walk through /app, /components, /lib. Tell me five conventions you can infer, and three things that look ambiguous or inconsistent. Bullet points only."

This forces the AI to look at the actual code instead of writing from priors. Read the response carefully — if it spotted real conventions, the rest of the conversation will be useful. If it gave vague generic answers, your repo isn't standardized enough yet, and the AGENTS.md file is premature.

Step 2: Make it ask you questions

"Now ask me 5–10 questions about decisions that aren't visible in the code: stack reasoning, things to avoid, deploy process, what kind of code is 'wrong' here. Don't write the file yet."

The questions are the file. Whatever the AI asks you about is what should be in section 4 (anti-patterns) and section 3 (conventions). The questions you struggle to answer are the rules you don't yet have — write them now.

Step 3: Iterate, don't one-shot

"Now draft sections 1 through 3 only. Keep each under 10 lines. We'll do the rest in a follow-up."

Long files get ignored. Both by humans and by the AI itself, eventually — long context degrades attention. Aim for under 100 total lines in the final file.

Step 4: Verify each rule against a real failure

For every line in the draft, ask yourself: "Have I seen the AI break this before?" If the answer is no, the rule is decoration. Cut it.

This is the step most people skip. The result is a file full of plausible-sounding rules nobody enforces and the AI ignores.

Step 5: Test it

Open a fresh AI session. Give it a small task ("add a new API route for X"). Watch what it does. Did it follow the file? If not, the rule was missing or the wording was unclear. Fix it.

A 7-point checklist for the final file

1. Total length under 100 lines. Long files dilute every rule.
2. Every rule has either a why or a one-line example.
3. No restating what's already in package.json, tsconfig.json, eslintrc.
4. No "be helpful and accurate" filler.
5. The first section is the hardest and most repo-specific rule, not the most generic.
6. Every "do not" has a "do this instead."
7. The file is in version control. It's part of the codebase, not a private note.

What changes after you have one

The AI stops asking what your conventions are because they're in its context. The same mistake stops happening every two weeks. New contributors (human and AI) get up to speed faster. Code review catches more, because the rules are explicit and you can point to them.

A good AGENTS.md is the cheapest leverage point on an AI-built project. Write it once; everything after that is cheaper.

---

The plain-English definition of .cursorrules and repo instruction files is at /glossary/cursorrules. If you're inheriting a codebase rather than building one from scratch, Working with AI on a codebase you didn't write covers the context-window and repo-conventions side of the same problem.