A new category of file has appeared in repositories over the last couple of years, and it arrived one convention at a time so nobody named it.
copilot-instructions.md. AGENTS.md. CLAUDE.md. Skill definitions. DESIGN.md, which states your design tokens so an agent stops inventing colours. Prompt files ending in .prompt.md.
All markdown. All committed. All written for a reader that is not a person.
They get discussed one at a time, as if each were its own idea. They are not. They differ in exactly one property, and it is the property that decides what they cost you.
The property is when they load
Three tiers, and everything in this class falls into one of them:
| Tier | Loaded | Cost |
|---|---|---|
| Always | Every request, without asking | Paid on every request, forever |
| On relevance | When the task looks like it needs them | Paid when used |
| On invocation | Only when you name them | Paid when you say so |
Repository instructions are tier one. That is the whole point of them — Copilot reads .github/copilot-instructions.md on every conversation in the repo, without being asked, which is what makes them the right home for conventions that apply to all work.
Prompt files are tier three. They sit in the repo as reusable workflows and do nothing until invoked. Many per repository, each task-specific.
Skills and a file like DESIGN.md sit in the middle: pulled in when the work is design work, ignored when it is not.
The distinction is not stylistic. Tier one is a subscription and tier three is a purchase, and the difference compounds across every request you ever make.
Why the default tier is the expensive one
The natural instinct is to put anything important into the always-loaded file. It feels safer. The agent cannot miss what it always has.
Two things make that wrong, and neither is obvious from inside a single session.
It is charged per request. A thousand words of conventions in tier one is a thousand words in every conversation, including the ones about something else entirely. Prompt caching softens the bill but not the occupancy — the tokens are still there, still in front of the model, still competing.
Competing is the real cost. More context makes performance worse before you hit any limit, and it does so in a way nothing else in software does. The clearest published demonstration is a model that failed a benchmark given all 46 of its tools and passed given 19, with room to spare either way. Nothing was truncated; the signal was diluted. That is context rot, and an always-loaded file is a permanent contribution to it.
So the always tier should hold the smallest thing that is true for all work: how this repository is laid out, what must never happen, the mechanics that fail silently. Everything else belongs lower.
The test for which tier
One question sorts almost every case.
What fraction of tasks in this repo need this?
Nearly all of them — tier one. A fifth of them — tier two, loaded when relevant. Only when I ask — tier three.
Run that honestly and most of what accumulates in an instructions file moves down. Deployment steps are needed by deployment tasks. The design token table is needed by UI work. A release checklist is needed at release.
Two failure signatures tell you the sort went wrong. If the always-file has sections beginning “when working on X”, those sections are tier two wearing tier one’s clothes. And if a rule keeps being ignored, adding it to tier one is usually the wrong fix — a rule in a prompt is a preference, and a preference that already failed once will fail again.
What these files should contain, regardless of tier
The reason DESIGN.md works is worth extracting, because it generalises to all three tiers and is not really about design.
It replaces invention with reference. The agent stops generating plausible colours because the actual tokens are stated: surface, primary, the corner radii, the spacing scale. It is not describing good design. It is stating what already exists.
That is the shape to copy. State what is, not what is good.
- “Use
const, prefer readable names” changes nothing. It is advice a model already agrees with. - “Helpers live in
test/lib, andtest/tests/index.tsmust be updated or the test never runs” changes the output, because it could not have been guessed.
The same reason restraints belong in a repository’s rules: the valuable lines are the ones a competent stranger would get wrong on their first attempt, and the worthless ones are the ones anybody would get right.
The duplication problem nobody has solved
There is a wrinkle the tiering does not fix, and it gets worse as more tools land.
Every assistant wants its own filename. Copilot reads .github/copilot-instructions.md. Cursor reads .cursor/rules/. Others read AGENTS.md or CLAUDE.md. The content that belongs in tier one is usually identical for all of them, and now it lives in three places that drift apart at different speeds.
Copying is the obvious answer and the one that fails. Three copies means the next convention gets added to whichever file the person had open, and six months later they disagree — with no error, no test, and no way to tell which one is current.
Two arrangements survive contact:
One real file, thin pointers to it. Each tool’s expected path holds a few lines saying where the actual content lives. A stub is cheap to keep correct because there is nothing in it to drift.
One real file, generated copies. If a tool genuinely cannot follow a pointer, generate its copy from the source and make the generation part of the build, so a hand edit to the copy gets overwritten and noticed.
What both avoid is the state where two files are equally authoritative. Pick which one is the source, and make every other location visibly secondary.
A layout that holds up
- One always-file, kept short. Conventions, layout, the silent mechanics, the hard prohibitions. Review it for length the way you would review a hot loop.
- Skills and reference documents for domains. Design tokens, deployment, data model. Loaded when the work touches them.
- Prompt files for repeatable jobs. The thing you run rather than explain: cut a release, write a migration, triage a failing run.
And a maintenance rule that matters more than the layout: grow these files from observed failures, not from imagination. A file written up front encodes what you assumed the agent would get wrong. A file grown from ten real pull requests encodes what it actually did. Those are rarely the same list, and only one of them is evidence.
The part worth remembering
These files are not documentation, and treating them as documentation is what makes them bloat. Documentation is written to be findable when someone goes looking. These are written to be loaded, and loading has a price.
Ask what fraction of tasks needs each thing, put it in the cheapest tier that still reaches the work, and keep the tier that is always paid as small as it can be while remaining true.