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

Start with the simplest layer, because it’s the one that travels. Drop an AGENTS.md at the root of budgetcli, write the two facts that keep walking out of memory, 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. Cursor’s support for nested AGENTS.md files has varied across releases and is not something to assume without checking the current rules documentation. If you need reliable subtree scoping, use a .cursor/rules/*.mdc rule with an explicit file pattern and test it in the installed version.

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 - and that’s the gap Cursor’s own format was built to fill. Next: Project Rules and the four rule types.