Every session starts from zero

Open a fresh session with Claude Code, Cursor, or Codex and watch the first thing it does. It greps around. It opens your package.json. It guesses your test command, runs the wrong one, reads the error, then tries again. A few minutes and a few thousand tokens later it finally works out what your linter wants. Close the session. Open a new one tomorrow. It does the whole dance again.

That rediscovery tax is the cost nobody puts on the invoice. With agentic tools now running $200 to $2,000+ per engineer per month in token spend, you are paying real money for an agent to relearn facts that have not changed since the last commit.

The fix is boring and it works

It is a plain markdown file at the root of your repo called AGENTS.md. Think of it as a README written for the agent instead of the new hire. Build commands with the exact flags. How to run the tests. The code style rules that differ from the defaults. Architectural constraints. And the files the agent should never touch.

This stopped being a niche trick. GitHub Copilot added native AGENTS.md support in August 2025, and it now sits alongside Codex, Cursor, Aider, Google's Jules, JetBrains Junie, Zed, Warp, and Windsurf. Most of these tools read AGENTS.md plus their own native file, so your shared rules live in one place instead of being copied across .cursorrules, CLAUDE.md, and a half-dozen other configs. Recent research on these files found that explicit repository-level instructions outperform looser, ad hoc skill systems in practical coding tasks. The agent skips the discovery phase, and the code it writes matches your standards on the first pass instead of the third.

What actually belongs in it

Resist the urge to dump your entire wiki in there. Long context is cheaper than it used to be, but a bloated instructions file still competes for the agent's attention with the actual task. Keep it tight and specific:

The real commands. pnpm test --filter web, not "run the tests."
Conventions a smart engineer would not guess. You use Drizzle, not Prisma. You return early instead of nesting. Errors go through one wrapper.
Hard boundaries. Generated files, migration folders, anything that breaks if hand-edited.
A one-paragraph map of the repo so the agent knows where things live.

If a rule only matters inside one package, put a scoped AGENTS.md in that folder. The agents read the nearest one.

Why this is leverage, not paperwork

Most teams reach for a better model when their agent produces mediocre code. The model is rarely the problem. The agent is working blind, reconstructing context you already have in your head and never wrote down. An afternoon spent writing a sharp AGENTS.md does more for output quality than swapping to whatever launched this week, and it pays off on every run after, across every tool your team uses.

We have watched this play out across client codebases. The teams getting real velocity from coding agents are not the ones with the fanciest setup. They are the ones who treat the agent like a capable new engineer who needs a good onboarding doc, then actually write it.

We are here to help founders and teams design and build digital products that are built to scale with you, not slow you down. If you are looking to build something, get in contact with us today!