What 'context' actually means in AI coding tools

Every AI coding tool talks about context. The documentation says the model needs context to do good work. The marketing says more context means better output. And then, usually, the explanation stops at "the files it can see", as if context were just a pile of source code you hand to the model and walk away from.

That pile matters, but it is only the first layer. Context is everything the assistant needs to make a decision the way you would make it, and a lot of that is not in your source files at all. It is in your rules, your conventions, your past decisions, and the things you have decided never to do. When an assistant produces slop, the usual cause is not that it saw too little code. It is that it never saw the rules.

Layer one: the code it can see

The most obvious layer is the code itself: the file being edited, the files it imports, the tests that cover it, and the types that constrain it. An assistant that can see the test for a function will write a change that passes the test. One that cannot see the test will write a change that looks right and fails it.

This is why "open the relevant files first" is the most reliable prompt engineering advice there is. It is not a trick. It is just making sure the assistant is working from the same evidence you are. If you would not review a pull request without reading the surrounding code, do not ask an assistant to write one without it either.

But code alone does not tell the assistant what good looks like in your project. Two codebases can have identical files and opposite conventions, and the assistant will happily follow whichever one it has seen most recently, which is usually the generic pattern from its training, not yours.

Layer two: the rules you have written down

This is where context files earn their keep. A short file at the root of the project that says how you build, how you test, what you never touch, and what a finished change looks like, is worth more than a hundred extra files of source code in the model's view. It is the difference between an assistant that guesses your conventions and one that follows them.

The best context files are short and specific. They name the commands, not just the tools: the exact test command, the exact lint command, the exact build step. They name the boundaries: the generated files nobody edits by hand, the legacy module that gets bug fixes only, the API that must stay backward compatible. And they name the definition of done: tests pass, lint passes, no new warnings, no unrelated files changed.

What they do not do is repeat the code. A context file that pastes in your entire architecture diagram, your style guide, and your product roadmap is not more helpful. It is just longer, and length is a cost: every token spent on context you do not need is a token not spent on the actual task, and a longer prompt is a prompt the model is more likely to skim.

Layer three: the decisions you have already made

The hardest layer to supply, and the one most people skip, is decisions. Your project is full of choices that are invisible in the code: why this library and not that one, why this endpoint returns that shape, why this feature was built this way after two failed attempts. An assistant that does not know those decisions will happily reopen them. It will suggest the library you already rejected, or "simplify" the endpoint shape you chose deliberately, and it will do it with total confidence, because from the code alone, its suggestion looks reasonable.

You do not need to document every decision. Document the ones that keep getting reopened. If an assistant, or a new hire, keeps suggesting the same wrong thing, that is a decision that needs writing down, in one paragraph, in the context file or in a comment near the code it affects. "We tried X in March, it failed because Y, we use Z instead" is a complete decision record, and it saves the next conversation from starting over.

What bad context looks like

Bad context has a few recognizable shapes. One is the dump: everything, all at once, in the hope that the model will find what matters. It rarely does, and when it does, it is by luck. Another is the stale file: rules that were true six months ago, describing a build command that no longer exists, or a directory that was renamed. Stale context is worse than no context, because the assistant follows it confidently and you spend the review undoing work that followed instructions you forgot you wrote.

The third shape is the missing negative: a context file full of what to do, with nothing about what not to do. "Use the design system" is a rule. "Never invent a new button style, use the ones in the system" is a rule the assistant can actually obey, because it tells it what to do when it is tempted to improvise. Most slop comes from improvisation in places where the project already has an answer, and the answer was never written down.

A practical check before you prompt

Before you hand a task to an assistant, run through three questions. Can it see the code the task touches, and the tests that cover it? Does it have your rules for this kind of change, in writing, somewhere it will read? And does it know the decisions that would stop it from reopening a settled question?

If the answer to all three is yes, you can write a short prompt and expect a good result, because the context is doing the heavy lifting. If any answer is no, fix the context first. It takes five minutes, and it pays off on every prompt after that, not just this one.

Context is not a pile of files. It is the shared understanding between you and the assistant about how your project works, what good looks like, and what has already been decided. Build that understanding deliberately, keep it short, keep it current, and the assistant stops guessing. That is the whole game.