Why every AI-built codebase needs an AGENTS.md

The problem: your AI has amnesia

Every time you open a new chat with Cursor, Claude, Copilot, or any other AI coding tool, it starts from zero. It doesn't know your package manager is pnpm, not npm. It doesn't know your API routes run on the edge runtime and can't touch Node built-ins. It doesn't know you use named exports for components, or that a single CSS file is the source of truth for your color tokens.

So it guesses. Sometimes it guesses right. Often it doesn't — and you end up reverting a config file that shouldn't exist, or untangling a component that reached for the wrong version of a library.

This isn't a model-quality problem. It's a context problem. And it has a cheap, boring fix.

What AGENTS.md actually is

AGENTS.md is an emerging convention — read and written by Claude Code, GitHub Copilot, Cursor, Gemini, and most other coding agents — for a single markdown file at the root of a repo that documents what a new contributor, human or AI, needs to know before making a change. Think of it as the onboarding doc you'd hand a new hire on day one, except written specifically so an LLM can load it into context and actually follow it.

The trick that makes it work across tools is symlinks. CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md can all point at the same AGENTS.md file, so the rules get written once and every agent picks them up under the filename it expects.

What to put in it

A good AGENTS.md isn't a style guide restating what a linter already enforces. It's the stuff a linter can't catch:

• Stack and tooling — package manager, Node version, deployment target, the handful of libraries that actually matter.
• Boundaries — which files are stable and shouldn't be touched casually, like a payment integration, an auth flow, or a validated environment-variable contract.
• Conventions with no mechanical rule — "Server Components by default, client components only when needed," or "derive types from schemas instead of hand-writing parallel ones."
• Known gotchas — the CLI that hangs in this environment, the warning that's safe to ignore, the pager that blocks non-interactive shells.
• The verification gate — the exact command sequence to run before calling something done.

Skip anything derivable from the code itself. If a linter enforces it, or git log already explains it, it doesn't belong here — it'll just rot.

AGENTS.md in practice

This site's own AGENTS.md is a live example we use every day. It states the stack up front, draws an explicit boundary around the contact-form backend so UI work doesn't accidentally touch it, and ends with a copy-pasteable verification gate — one shell command that runs formatting, secret scanning, linting, type checking, and a production build.

That single block does more to keep AI-generated changes safe than any amount of prompting. An agent that reads it doesn't need to be told twice not to read environment variables directly, or to remember to scan for secrets before committing — it's just there, every session, in the first file it loads.

It's part of launch-readiness

We see the absence of an AGENTS.md constantly in the Launch-Readiness Scans we run: prototypes with unrunnable install steps, inconsistent environment-variable handling, half-migrated styling systems where some sections use a config file that no longer exists. Almost none of it is because the AI tool that built the app was incapable — it's because nothing ever told it the rules, so every session reinvented them slightly differently.

If you're building with AI tools and don't have an AGENTS.md yet, it's a twenty-minute investment with a long payoff: write down your stack, your boundaries, your gotchas, and your verification command. Every future session, yours or the agent's, starts smarter than the last.