AGENTS.md: The Open Standard for AI Agent Instructions

1. What AGENTS.md Is and Why It Exists

As AI coding agents arrived, each one shipped with its own way of reading project context. Claude Code reads CLAUDE.md. Cursor reads .cursorrules (now .cursor/rules). GitHub Copilot reads .github/copilot-instructions.md. Every tool solved the same problem — "how does the agent know the rules of this repo?" — with a different, incompatible file.

The result was predictable: teams using more than one tool ended up maintaining the same instructions in two or three places, where they quietly drifted out of sync. AGENTS.md exists to consolidate that sprawl. It's a single, plain markdown file that a growing number of coding agents agree to look for, so you write your project's instructions once and any compatible agent can read them.

There's nothing magic about the format — that's the point. It's just markdown, readable by humans and agents alike, living next to your code. The value is in the convention: a shared filename and a shared expectation of what belongs inside it.

2. What Goes in an AGENTS.md File

There's no rigid schema, but good AGENTS.md files converge on a handful of sections. Each one answers a question an agent would otherwise have to guess at:

A realistic AGENTS.md example

Here's a complete AGENTS.md for a small TypeScript billing service. Notice the commands sit near the top, the rules are concrete, and the whole thing stays short enough that an agent will actually read it:

# AGENTS.md

## Project overview
Billing service for a SaaS product. TypeScript + Node, Postgres via Prisma,
deployed to Fly.io. Handles subscriptions, invoices, and Stripe webhooks.

## Commands
- Install:   pnpm install
- Dev server: pnpm dev           # http://localhost:3000
- Build:     pnpm build
- Test:      pnpm test           # Vitest, run before every commit
- Lint:      pnpm lint           # ESLint + Prettier, must pass in CI
- Migrate:   pnpm prisma migrate dev

## Conventions
- TypeScript strict mode. No `any` — use `unknown` and narrow.
- Prefer named exports. One React component per file.
- Money is stored in integer cents, never floats.
- All dates are UTC ISO-8601 at the boundary.

## Do
- Add a Vitest test for every new branch of logic.
- Keep Stripe keys in environment variables only.
- Update the Prisma schema and generate a migration in the same change.

## Don't
- Don't call the Stripe API from the client bundle.
- Don't edit files in `src/generated/` — they are built artifacts.
- Don't skip the lint step to "fix it later".

## Directory notes
- src/routes/   HTTP handlers, thin — delegate to services.
- src/services/ business logic lives here.
- src/db/       Prisma client + repositories.
- src/generated/ auto-generated, do not touch.

Keep yours in the same spirit: concrete commands, concrete rules, no filler. If a line wouldn't change what the agent does, cut it.

3. How It Relates to CLAUDE.md and .cursorrules

AGENTS.md, CLAUDE.md, and .cursorrules are the same idea wearing different labels. They all give an agent persistent project context; they differ in filename, format, and which tools look for them.

4. Adoption and Portability

AGENTS.md is read by a growing number of coding agents, which is exactly what makes it worth adopting: it is the closest thing to a cross-tool standard right now. If you switch tools, or your teammates use different ones, a single AGENTS.md means nobody has to re-author the project's rules for each agent.

Mechanically it's refreshingly simple. It's a markdown file at the repository root. In a monorepo you can nest an AGENTS.md per package or subproject, and agents use the file closest to the code they're touching — so a shared root file can set org-wide conventions while each package refines the specifics.

5. Best Practices

A good AGENTS.md is short, specific, and maintained. A few rules that hold up in practice:

6. The Enforcement Gap

Here's the uncomfortable truth about every rules file — AGENTS.md included: a rules file is only as good as the agent's adherence to it. The agent reads AGENTS.md at the start of a session and then, as the session runs long, drifts. After context compaction it may not even remember the file existed. Three features in, under pressure to just ship, the "never skip the lint step" rule quietly loses. A file the agent ignores halfway through a build gives you false confidence, which is worse than no file at all.

Keeborg was built around this problem before "spec-driven development" was even the accepted term. It's an opinionated, battle-tested dev system for AI coding agents — and where open, unopinionated scaffolds hand you a blank file and wish you luck, Keeborg adds the layer that makes the rules actually stick:

AGENTS.md is the right place to write your project's rules down — adopt it. Just know that writing them down is step one. If you've watched an agent read your rules and then wander off anyway, the enforcement layer is the piece you were missing. See how it fits the wider methodology in the spec-driven development guide.