Coding agents fail on unfamiliar frameworks for a boring and fixable reason: they are reasoning from training data that predates your version, and they do not know it. The model writes plausible code against an API that changed eighteen months ago, the code fails, and the agent then debugs a problem it created by guessing.
A context.md file fixes this. It is a short, dense briefing on the specific things an agent would otherwise get wrong in your repository — not documentation, but corrections.
What is a context.md file?
A context.md is a file placed where a coding agent will read it (the repository root, or the location your tool conventionally loads) that tells the agent the truth about the stack it is working in: which APIs your version actually exposes, which patterns this codebase rejects, and which plausible-looking approach will fail here.
The framing that matters is delta, not description. The model already knows what React is. It does not know that this project is on a version where a hook it will reach for was removed, that your team bans a pattern it will default to, or that the build fails silently if a file lands in the wrong directory. Everything that is already in the model's head is wasted space; the value is entirely in the difference between what it believes and what is true.
What goes in it?
| Include | Why |
|---|---|
| Versions that matter | Exact versions of the frameworks whose APIs have changed recently — with the specific changes named |
| API corrections | "X was removed in v5; use Y." These are the highest-value lines in the file |
| Project conventions | Where files go, how modules are named, which patterns are banned and why |
| Commands | How to build, test, lint and run — exactly, including flags |
| Traps | Things that fail silently, or fail in a way whose error message points somewhere else |
| A worked example | One small, complete, idiomatic change in this codebase. Worth more than a page of rules |
And what to leave out: an architecture essay, a history of the project, general best practices for the language, and anything the agent can discover by reading one file. Context that restates the obvious dilutes the context that does not.
How is it different from a README?
A README explains a project to a human arriving for the first time — what it is, how to install it, how to run it. A context.md corrects a model that already believes it knows the technology.
The two overlap far less than people expect, which is why pointing an agent at
a README rarely fixes the failures a context file does. A README will not tell
you that useFormState was renamed, because a human would hit the
deprecation warning and look it up. An agent will confidently write the old call,
get a runtime error, and start investigating the wrong thing.
Writing rules that work
- Be specific and falsifiable. "Use the new router API" is
useless. "Route files must export
loader, notgetServerSideProps; the latter is silently ignored" is a correction the agent can act on. - Lead with the correction. Put the change first and the reasoning second, so a truncated read still carries the useful part.
- Say what fails, not only what to do. Agents recover much better from "if you see error E, you have made mistake M" than from a rule in the abstract.
- Keep it under roughly 400 lines. A context file long enough to crowd out the actual task has become part of the problem. If it is growing past that, split by area and load the relevant one.
- Date it. Context rots exactly as fast as the framework moves. A line saying when it was last verified tells the next person whether to trust it.
The test for a good context file: delete a line and ask whether the agent would now get something wrong. If not, the line was decoration.
What is llms.txt?
llms.txt is a proposed convention for a markdown file at the
root of a website that gives large language models a curated, machine-readable
index of the site's most useful content — roughly what robots.txt
does for crawler directives, but for comprehension rather than permission.
A typical file has a heading with the project name, a blockquote summarising what it is in a few sentences, and then sections of annotated links pointing at the canonical, clean versions of key documentation.
# Acme Router
> A file-based router for server-rendered applications.
> Version 5 changed the data-loading API; see the migration note below.
## Docs
- [Getting started](https://example.com/docs/start.md): install and first route
- [Data loading](https://example.com/docs/data.md): the v5 loader API
- [Migrating from v4](https://example.com/docs/migrate.md): every breaking change
## Optional
- [Changelog](https://example.com/changelog.md)Two honest caveats. It is not a standard any AI vendor is obliged to honour, and adoption varies. But it costs almost nothing to publish, it is increasingly read by documentation-aware tooling, and the act of writing one forces you to decide which twelve pages actually matter — which is useful regardless of who reads the file.
Which one do you need?
- You maintain a codebase and agents keep getting your stack wrong → write a context.md in the repository.
- You publish a library, API or product with documentation and want AI tools to represent it correctly → publish an llms.txt at your domain root.
- Both, if you ship a developer tool. They serve different readers: one helps agents working in your code, the other helps agents answering questions about it.
Keeping it true
A context file that has drifted is worse than none, because the agent will follow it confidently into a wall. Three habits keep it honest:
- Update it when you hit the failure. The best time to add a correction is the moment an agent gets something wrong — you have the exact error and the exact fix in front of you.
- Review it on dependency upgrades. A major version bump invalidates the lines that were most valuable, which is precisely why they were there.
- Delete aggressively. If a correction has been true for two years and the model now gets it right unprompted, remove it. The file's value is density, and density only survives pruning.
Done well, this is one of the highest-leverage documents in a repository: a few hundred lines that turn an agent from something you supervise into something you delegate to. Done badly — long, generic, stale — it is a file everyone stops reading, humans included.
Frequently asked questions
What is llms.txt?
llms.txt is a proposed convention: a markdown file at the root of a website that gives large language models a curated, machine-readable index of the site's most useful content, in the way robots.txt gives crawlers directives. It is not a standard any AI vendor is obliged to honour, but it costs almost nothing to publish and is increasingly read by documentation-aware tools.
How is context.md different from a README?
A README explains a project to a human arriving for the first time — what it is, how to install it, how to run it. A context.md corrects a model that already believes it knows the technology: which APIs changed in the version you actually use, which patterns your codebase rejects, which plausible-looking approach will fail here. The two overlap very little, which is why pointing an agent at a README rarely fixes the failures a context file does.