The friction isn't the editor
I switched between Cursor, Cline, and Claude Code in the same week recently. The learning curve on each tool was fine. What actually ate my time was re-explaining the project to each one.
Same repo layout. Same test command. Same "don't touch that file." Same "the auth flow lives here, not there." I'd paste it into Cursor, watch it build the right thing, switch to Cline for a different task, and start from zero again. The tool remembered nothing about the project. I was the clipboard.
That's the tax nobody budgets for: not the tool's learning curve, but the per-tool re-explanation.
Each tool wants its own file
Cursor reads .cursorrules. Claude Code reads CLAUDE.md. Cline reads its own instructions. A bunch of other tools read AGENTS.md because it's the closest thing to a cross-vendor convention anyone has.
If you maintain three near-identical files, you will drift. The one that says "use pnpm" falls out of date when the repo moves to bun. The one that lists the test command goes stale when the Makefile target renames. Six months later, your Cursor agent is running a command that no longer exists and your Claude Code agent is reading a deprecated directory.
The fix isn't to be more disciplined about syncing three files. The fix is to have one short file that all of them read, and make the tool-specific wrappers thin pointers to it.
What actually belongs in the shared file
The instinct is to dump everything. Resist it. The file is for the things that are true regardless of what tool you're using and that the agent will get wrong if you don't say them.
Concretely:
- How to run the tests. The exact command, not "the test suite." If it needs an env var or a database, say so.
- Where things live. The one or two directories an agent is most likely to wander into and the one or two directories it must not touch.
- How to verify a change. What a green run looks like, what command proves the fix worked.
- The gotchas. "We don't use lodash here," "the migration runner is offline-only," "this package is ESM-only." Things that are obvious to you and invisible to the agent.
- What done means for this repo. Not the org-wide mission, the local definition: tests pass, lint passes, the build produces X.
What doesn't belong: architecture essays, the product roadmap, every convention from the contributing guide, your preferences about commit message style. The agent can read those when it needs them. The shared file is the fifty lines that save you from repeating yourself every session.
What doesn't belong in prose at all
Here's the part that changed my mind about this. Most of the things people try to write into an instructions file are facts the tool should be able to read directly instead of being told about.
If your build pipeline exists, the agent can read the Makefile. If your test setup exists, it can read the config. If your directory structure exists, it can ls. You don't need to narrate it. The more you describe the repo in prose, the more it rots — because the prose isn't the source of truth, the files are.
The exception is the stuff that isn't represented anywhere machine-readable: "don't touch that file," "we deliberately pinned this dependency," "the staging deploy is manual on Fridays." That belongs in the shared file because nothing else will tell the agent.
And this is where the API contract sits oddly. People write paragraphs in their instructions file about how the API works — "the auth endpoint returns a user object," "errors are shaped like this," "versioning is in the header." But the repo already has an OpenAPI spec that says all of that, more precisely, in a format every tool can parse. The prose version will drift; the spec won't, if you treat it as the source of truth.
We ended up keeping the OpenAPI spec as the one machine-readable artifact that every AI coding tool reads directly instead of re-explaining it in Markdown. When the agent needs to know what the endpoint returns, it reads the spec. When the spec changes, the agent gets the new behavior automatically. No instructions file to keep in sync. That's the same principle as the shared AGENTS.md, just applied to the part of the repo that already has a canonical format.
A litmus test
Before you add a line to your instructions file, ask: will the agent get this wrong if I don't write it?
If the answer is no — the tool can discover it, the file exists, the test command is obvious from the Makefile — don't write it. You're just adding noise that will rot.
If the answer is yes — "the agent keeps editing the generated file," "the agent keeps trying to start the docker-compose that doesn't exist locally," "the agent assumes we use a framework we deprecated" — write it. Once. In the shared file. Keep it short enough that you'll actually update it when it's wrong.
The point
You're going to switch tools. Probably next quarter. The tool you picked today won't be the best one in six months, and you'll move.
When you do, the cost of that switch is proportional to how much tribal knowledge you baked into tool-specific prompts. A fifty-line AGENTS.md that every tool reads is a few minutes of setup. A prompt library you've been curating in Cursor for a year is a rewrite.
The instructions file isn't documentation. It's the shortest possible translation between your head and whatever tool you're using next. Write it like it's going to be read by an agent you've never met, because that's exactly who opens it first.
Top comments (0)