$ subscribe
← / writing --workflows

your AGENTS.md is the new readme. here's how to write one.

jamie okonkwo · 05-14-2026 · 2 min read

AGENTS.md is the file every coding agent reads before doing anything. mine is 90 lines. here's the structure that's survived three months of daily use.

every coding agent — cursor, claude code, copilot’s agent mode — reads a file in the repo root before doing anything. for cursor it’s .cursor/rules, for claude code it’s AGENTS.md, for copilot it’s .github/copilot-instructions.md. they’re all the same file, structurally. and the structure matters more than the contents.

here’s the layout that’s survived three months of daily use on a 50k-line typescript codebase.

the four sections

# AGENTS.md

## conventions
- typescript strict, no `any` outside of test files
- prefer named exports
- date handling: always UTC, never local
- error handling: throw, don't return `Result<>`. we catch at the boundary.

## testing
- vitest for everything
- one test file per source file, mirrored path
- run with: `pnpm test path/to/file.test.ts`
- coverage is not a goal. test what would break in production.

## commands
- dev:    `pnpm dev`
- build:  `pnpm build`
- test:   `pnpm test`
- typecheck: `pnpm tsc --noEmit`
- always run `pnpm tsc --noEmit && pnpm test` before opening a PR.

## what to ask before doing
- if a name might collide with an existing one — ask, don't disambiguate
- if a migration is destructive — ask
- if a change touches >5 files — outline the plan first

why each section matters

conventions is where agents save you the most time. every “use UTC dates” rule you write here is a 10-minute code review you don’t have to do later.

testing matters because agents will silently skip running tests if you don’t tell them which command to use. the explicit command + the explicit “run before PR” line catches this.

commands lets the agent self-serve. without it, every “how do i run the typecheck” guess wastes a context window.

what doesn’t belong

things i used to put in AGENTS.md and removed:

  • architecture overviews — too long, never read carefully
  • “code style” rules like quote types — prettier handles it
  • onboarding docs — that’s what the readme is for
  • aspirations — only ship what’s true today

one rule for the whole file

every line should be either a constraint or a command. not advice, not context, not history. if you can’t read a line and immediately picture an agent making a different decision because of it, cut the line.