We have a dog. He's been with us for more than eight years, has long been a full member of the family and, like any self-respecting family member, regards our bed as his. Every evening A. and I have a playful argument about whose side he'll sleep on: “He's my dog!” “No, he's mine!” But I have an unbeatable argument: the veterinary passport lists me as his owner. You can't argue with a document.
Unfortunately for my argument, the dog doesn't read passports and sleeps wherever he likes.
In the previous article, we prepared the project documents and even checked whether a new agent could use them to pick up the work. Surely now it should be enough to say “read the docs”. If it were, I wouldn't have to repeat that phrase so often.
Where does an agent even start?
Let me recap the route we began building in article six. In my setup, a new session starts with a short instruction in the agent's own configuration folder: a global AGENTS.md for Codex, CLAUDE.md for Claude. These files tell the agent not to keep project knowledge in its private notebook and point it towards the documents of the project it is working in now. They're a sign on the door, not a second copy of the project library.
Through that door, the agent finds the project's AGENTS.md, its concise project memory and a map of its documents. Those lead further: to the intention, the current task, an accepted decision or the release procedure, depending on the job. So the chain runs from the agent's own entry instruction to the current project, then to the document for this task and a check of the current state. Afterwards, the result goes back into the project. None of those steps requires me to retell the whole story in chat.
But getting the agent to the right file is only half the route. A large document needs its own entry instructions: what it's for, how its sections are organised, where the current record lives, where to add a new one and what belongs in neighbouring documents. In article seven, I talked about this as a way to maintain the files. There is a more troublesome reason for it: without that heading, the agent may never reach the part it needs.
It is unlikely to read even a hundred lines straight through. Usually it searches for a word with grep or rg, looks at the first N lines and a few matches. Those are perfectly good tools if it then opens the matching section and understands where that section sits in the document. But without an instruction in the heading to do exactly that, the agent may grab the first plausible line. It finds “release folder” in a year-old entry and decides it knows the current path. Further down, in the section for the current release, the answer is different.
That is why I don't want a ceremonial “important information is stored here” at the top of a working document. I want a short map inside the file. For example: current paths are in the current-release section; older entries below are kept as history; when searching by keyword, read the heading and the whole section, and check its date and status; add a new result here, together with what was checked and what remains open. That instruction has to be in the document's own heading, not hidden somewhere in the general AGENTS.md. The agent shouldn't have to guess what lies beyond the first few lines, and I shouldn't have to explain it in every new session.
Without this internal route, a file can be full of correct answers and still be nearly useless to the agent. The project map brought it to the right document, but the document didn't say how to go further. The search tool isn't the problem. Treating a matching line as if it were the whole context is. A heading can't guarantee that the agent will follow the instruction, but at least the next step is right there in the fragment it is most likely to open.
To me, the short command “read the docs” means following this route. First work out which directory you're in, then take the rules from that project instead of the first familiar note about a similar one. During a long session, it helps to do this again when the area of work changes. The route to an editorial draft and the route to a website release overlap, but they lead to different decisions.
The scheme isn't magic. None of its arrows clicks itself. An agent can stay with an old private note, skip the project instructions, or open the right file and misunderstand which part of the request it applies to. Here are two examples.
The answer was written down
Once, I asked an agent to look into a finished app build. It searched an old folder, found nothing and rather confidently reported that the file wasn't there. The current path was already in the project documentation. There was no need to guess where I had hidden the build: it needed to open the current document and check the location it named.
When I pointed this out, the agent didn't immediately return to the document. First it tried to defend its conclusion. That bothers me more than the original mistake. Couldn't find the file? It happens. But “I looked in the wrong place” and “the file doesn't exist” are entirely different claims.
We could write another rule in capital letters. It would land in the same folder the agent had already skipped. The problem wasn't that there was nowhere to store the answer. The problem was that the agent had replaced a check with a confident assumption.
As we examined the mistake, an awkward detail emerged: the agent had got the old path from somewhere. It hadn't invented it. It had relied on a secondary note that was once useful and had since gone stale. So it had read something. It had simply chosen the wrong source and failed to check it against the project's current rules.
And there's another possibility: the agent reads the rule and still manages to apply it in exactly the wrong place.
It read the rule — and stopped in the wrong place
This happened while we were preparing this very article. After I had raised a problem, we added a boundary to the shared rules: without a direct instruction, an agent must not enter other projects' folders or access their servers. The intention was specific. If we're working on a website, don't wander into the live app's repository or diagnose its server out of curiosity just because the names are similar and access happens to be available.
I asked for the eighth article to be prepared. The agent opened the shared workspace for our sites and editorial work. It saw that the text was in the editorial subproject and the website in another subproject of that same workspace, and stopped. It called both of them “other projects” and asked me for separate permission to move between them. I had to ask: which folder are you working in?
This is the reverse of the build story. In that case, the agent never got to the current rule. Here it found the rule, pulled one word out of it and applied the restriction to the assignment itself. The task already defined the working area: prepare an article for this website. Opening the editorial text and the site's source was necessary for that work. The rule about other projects was meant to stop unrequested trips beyond it.
A lovely paradox, but it saved no time. The agent interrupted me to request permission for work I had just assigned. Adding three more explanatory paragraphs to the rule might only give the next model three more ways to get confused. Sometimes a document does need fixing. Sometimes we have to admit that the document was clear and the person following it drew the boundary around the wrong task.
When to return to the document
I have more than a hundred thousand lines of Mango documentation. At that scale, “read everything” is less useful than a precise question: where is the release build now? Which version of the text has been approved? Who is working on this change? What condition is still open?
I don't want an agent bringing me a report that says “I read 137 files”. I'd rather hear: “For this task I opened the current release procedure. I checked the indicated folder; the file is there, but installation on a device has not been checked yet.” Or: “The editorial version exists, but its status is draft. I prepared the page locally; it cannot be published yet.” Then the necessary next step is visible.
Of course, an agent can write a handsome lie. A link to a file doesn't prove it understood the file, and a list of checks doesn't replace the checks themselves. But at least that kind of answer can be examined. “Everything is ready, don't worry” is harder to challenge because it doesn't say what was done or why I should relax.
Finding the answer once isn't enough, either. Before concluding “there is no build”, check the current path. Before publishing an article, check its status and version, not just whether a Markdown file exists. Before handing work to another agent, establish what has been done and what remains open. The cost of a mistaken conclusion changes at those points, which is why I want to know which specific record the agent relied on.
Another tricky word is “now”. An old report that says website access failed a month ago is a useful piece of history, but a poor basis for claiming it still fails today. An open task in a work log is a reason to check its present state, not to redo somebody else's work automatically. Documents help you find things, but some facts keep moving: branches change, builds move, articles are approved, servers restart. Before asserting the current state, the agent needs to look at the current state.
This matters particularly in long tasks. You start with one question, find a related problem, open two more files, and by evening it's easy to forget which was the source and which was an old hint. At that point I'd rather hear a brief “I found a discrepancy; I'm checking the current record” than a confident story built on the first note that turned up. There is no need to stop at every step. Slow down where a wrong conclusion would lead to another wrong action.
Nor do I want to approve every move within my own project folder. If an agent reads a rule too broadly, stops in the middle of ordinary work and asks permission to open a file it needs, it has applied the document without understanding the task. Reading instructions should help it move, not turn me into a “Continue” button. In such a case, though, it can help to tell the agent to “read the docs again” and name the specific document. That means I still need to remember where things are.
What to fix after a mistake
After stories like these, it is tempting to make the rules stricter. One agent opened an old folder: add five warnings. Another was afraid to enter the subproject it needed: list every permissible directory for every possible task. Then somebody renames a project, the new rule quietly goes stale and, six months later, an agent reads it and is very convincingly wrong again.
I work backwards from the cause. Was the answer missing from the docs? Then it really should be written down, along with when it applies. Was it only in my head? Put it in the project instead of explaining it again in chat. Do two records disagree? Find out which is current and mark the older one as history. Did the agent fail to open the right file? Send it back through the route and check the result before editing any rules. Did it open the file but apply it incorrectly? Show the boundary in this task and decide whether the text needs clarification or the agent's conclusion needs correcting.
This isn't an attempt to absolve the agent and blame every mistake on the documentation. Quite the opposite: if I change a file every time an agent fails to do its part, the reason for the mistake stays put. Only the pile of instructions it can walk past next time gets bigger.
My own review doesn't mean sitting beside it and pressing “yes” after every paragraph, either. I watch the important transitions: did the agent base its conclusion on a current source or on a memory? Did it perform the check or merely say it did? Did it meet a real boundary of authority, or invent one after forgetting where it was working? The clearer those answers are, the less often I have to reconstruct the work from scraps of conversation.
And my answer to “how do you make an agent read the docs every time?” is still short: you can't. I can make the route to the right decision clear, ask it to name a source before an important conclusion and notice when it repeats a guess instead of checking. But if it confidently walks past a written instruction, the existence of the file won't stop it.
We won't be revising the veterinary passport. It says I'm the owner, A. can argue with me, and the dog will pick his own spot again tonight. He's allowed to. An agent about to declare that a build is missing because it checked an obsolete folder, or publish text that hasn't been approved, will have to read the docs first.