Notes to a Machine: The Hidden Life of the Agent README

The File Nobody Was Studying

There is a small file sitting in millions of code repositories right now, and almost nobody had ever studied it as a group until last November. It goes by a few names depending on which tool you use. Some call it the agent context file. You might know it as the file you write so a coding assistant understands your project before it starts touching your code. A handful of researchers decided to do something obvious that nobody had done. They went and read two thousand three hundred of these files, pulled from nearly two thousand separate projects, and asked a simple question. What do people actually write when they are leaving instructions for a machine that writes code for them.

What they found is more interesting than it sounds, because these files turn out to behave nothing like documentation. Documentation is written once, politely, and then ignored until it rots. These agent files are alive. They get edited constantly, in tiny additions, the way you would tweak a configuration file that keeps breaking. Someone adds a line because the assistant did something dumb on Tuesday. Someone adds another because it did something different and dumb on Thursday. The file grows like a scar, one small correction at a time, until it is a dense and frankly hard to read record of every way the machine has misbehaved.

What People Actually Write

When the researchers sorted the contents into types, a clear personality emerged. People overwhelmingly write functional instructions. How to build the project. How to run it. The specific commands, the architecture, where things live and how the pieces connect. Roughly two thirds of the files spelled out implementation details. About the same share described the architecture. A solid majority gave the exact build and run commands. In other words, people treat these files as a survival guide. Here is how you not get lost in my code. Here is how you not break the thing that is already working.

And that makes complete sense, because anyone who has used one of these coding assistants knows the failure looks the same every time. The machine is confident, fast, and occasionally completely wrong about how your project is wired together. So you write down the wiring. You write down the commands it keeps guessing wrong. You are not writing documentation for a human who will read it once. You are building a fence around a powerful animal that does not know where your flower beds are.

The Missing Fourteen Percent

Here is the number that should make you sit up. Security instructions appeared in only about fourteen and a half percent of the files. Performance instructions, almost exactly the same. Fourteen and a half percent. So picture what that means in practice. Nearly everyone tells the machine how to build the code and how the code is shaped. Almost nobody tells it to write code that is safe, or code that is fast. We have collectively taught these assistants to be functional and left them almost entirely unsupervised on whether the result is secure.

Think about the asymmetry there. The whole appeal of an agentic coding tool is that you hand it a goal in plain language and it goes off and writes and runs real code with very little babysitting. That is enormous power. And the picture from these two thousand files is that we are pointing that power at speed and correctness while saying almost nothing about safety. Six out of seven projects gave their tireless, fast, confident code-writing machine no standing instruction about security at all. Not because anyone decided security did not matter. Because writing the build command was the thing that hurt today, and the security hole is the thing that hurts six months from now, quietly, to someone else.

Writing Notes to a Thing That Listens

What makes this study land is that it is a mirror, and you are in it. If you have ever written one of these files, you already know the pattern it describes, the small angry additions, the build commands, the architecture notes, the total silence on the boring long-term stuff. The researchers did not discover a flaw in the tools. They discovered a flaw in us, in what we bother to write down when the listener never gets tired and never pushes back.

And there is a deeper thread here about how tools shape behavior. For decades, the instruction file in a project was a courtesy to the next human, who might or might not read it. Now the instruction file is consumed, every single time, by something that will act on every word. That changes the stakes of writing it. A vague human reader fills in the gaps with judgment. A coding agent fills in the gaps with whatever was statistically likely in its training, which is not the same thing as your intent and is occasionally the opposite of it. The gap you leave is not a gap anymore. It is a decision you handed to a machine.

So the practical takeaway is almost embarrassingly simple. The next time you open one of these files to add another build command, scroll up and ask what is not in there. If the whole document tells the machine how to make the code work and nothing tells it how to make the code safe, you have written half a fence. The animal is just as fast as before. You just decided which flower beds to protect. The researchers counted, and most of us are protecting the wrong ones.