What is AGENTS.md?

A plain markdown file at the root of a repository that tells an AI coding agent how to work in it. The README is written for a person deciding whether to use your project. AGENTS.md is written for whoever has to change it.

What belongs in it

The test that matters is whether a capable stranger could make a small change and verify it using only this file. Commands first, conventions second, none of the persuasion a README carries.

# AGENTS.md

## Setup
pnpm install

## Commands
pnpm dev          # local server on :3000
pnpm test         # full suite, must pass before any commit
pnpm typecheck    # tsc --noEmit

## Conventions
- Server code in src/server, client in src/app.
  Never import across that line.
- Database changes go through a migration
  in db/migrations.
- Tests sit next to the file they cover.

## Gotchas
- The dev server needs Postgres.
  Run docker compose up -d db first.
- Anything under src/generated is built from
  the schema. Edit the schema.

What makes one bad

Too short. Three lines saying "this is a TypeScript project, write clean code" changes nothing about what an agent does.

Too long. Twenty thousand characters of philosophy loads on every turn and crowds out the code the agent needs to read.

No commands. The most common failure by a wide margin. If the file never says how to run the tests, the agent guesses, guesses wrong, and reports success anyway.

The wrong filename. AGENTS.md is vendor-neutral and the most widely read. CLAUDE.md, .cursorrules, and .github/copilot-instructions.md are tool-specific. Keeping one alongside is fine, but AGENTS.md is the one that works everywhere.

See how yours scores.

Instructions are worth 27 of the 100 marks, and the median repository gets 39% of them.