AGENTS.md: the portable path, the same file Codex reads

Start with the simplest layer of Cursor’s standing instructions, because it’s the one that travels. Drop an AGENTS.md at the root of budgetcli - the course’s illustrative TypeScript finance API - write down the conventions that otherwise live only in your head, and you’re covered on every tool that reads the standard:

AGENTS.md

# budgetcli

A budgeting / personal-finance API (TypeScript). You're working on live
transaction data - be precise about money and time.

## Conventions

- All timestamps are stored and compared in **UTC**. Parse incoming dates to
  UTC at ingest; never store server-local time.
- Every API handler validates its request body with a **Zod schema** before
  touching business logic. Do not hand-roll validation with `if` checks.
- Money is **integer cents**, never a float. Format to a currency string only
  at the response boundary, never in storage or maths.

There’s no special syntax to learn - Cursor reads AGENTS.md the way the model reads any prose: headings, terse imperative bullets, the things that bite. Every line earns its place because it’s something Cursor got wrong, not something it could read off the source. Nothing in there says “write clean code” or transcribes the directory layout; that just burns context. Write it the way you’d brief a sharp new engineer on day one.

That “earns its place” test is arithmetic you can run, not a vibe. Seven candidate lines from another project - toggle each into the file and watch the ledger decide:

Seven candidate lines for your rules file. Toggle each one in and see whether it earns its slot over a week of sessions.

• Tests run with npm test -- --runInBand - parallel runs deadlock the test DB.earns its slotWithout it, the agent runs plain npm test, hits the deadlock, and you explain - most sessions. One line ends that forever.
• Use pnpm, never npm - the lockfile is pnpm’s and npm install corrupts it.30 tok
• Route handlers never throw - return Result<T, AppError> from src/lib/result.ts.36 tok
• The bug we’re fixing today is in src/billing/charge.ts.18 tok
• Current sprint: migrate the users table to UUID keys.16 tok
• Write clean, readable code with good variable names.the model already knowsThe model does this by default. The line buys nothing - it just competes with your real rules for attention.
• Think step by step and be careful about edge cases.14 tok

always-loaded cost480 tok/weekre-teaching avoided5.6k tok/weeknet+5.1k tok/week

Net positive - but 1 line is paying rent with the durable facts’ savings. Cut the amber ones; the ledger only improves.

Numbers are illustrative - the ratios are the point: a re-teach cycle (wrong attempt, correction, redo) dwarfs the line that prevents it. Assumes 10 sessions a week, the file loaded at the start of each.

The payoff is portability. Because this is the agents.md open standard - whose adopter list names Cursor alongside Codex, OpenCode, and others - the same file is in force whether your teammate clones budgetcli into Cursor, Codex, or OpenCode. One file, every tool, no per-tool translation.

Keep the portable guarantee simple: put shared project guidance in a root-level AGENTS.md. Nesting is supported too - Cursor’s docs state that “You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children” (as of October 2026; rules documentation), with nested instructions combined with the parent’s and “more specific instructions taking precedence” (as of October 2026). The root file remains the default; reach for a nested one only when a subsystem genuinely needs its own scoped instructions.

Try it

Write three rules in AGENTS.md for budgetcli: one about money (integer cents), one about test commands (npx vitest), one about import style. Start a new chat and ask for a feature. Check whether the rules held.

Portability is what AGENTS.md buys you. What it can’t buy you is conditionality beyond directory nesting - rules that attach by file pattern, when the model judges them relevant, or on demand - and that’s the gap Cursor’s own format was built to fill. Next: Project Rules and the four rule types.