Ukrainian development manager Kyrylo Sulimovskyi analyzed research on how AI agents like Claude Code, Codex, Gemini CLI, and Cursor actually work with documentation. It turned out that they actively read CLAUDE.md and AGENTS.md specially written for them, but the read instruction does not always turn into a specific action.
Ukrainian development manager Kyrylo Sulimovskyi analyzed research on how AI agents like Claude Code, Codex, Gemini CLI, and Cursor actually work with documentation. It turned out that they actively read CLAUDE.md and AGENTS.md specially written for them, but the read instruction does not always turn into a specific action.
Sulimovsky posted a video about this on YouTube.
Based on the research, the developer formulated several rules: it is better not to "hide" critical requirements behind chains of links, important instructions should be made as specific as possible, and where possible, they should be supported by automatic verification.
Sulimovsky cites a study by Peking University researchers Zhijun Gao and Jing Chen, published on arXiv in August. They analyzed 557 real-world sessions with coding agents and over 33,000 pull requests created by the agents.
It turned out that AI agents very often "look" at CLAUDE.md and similar files with instructions. When they needed to find information, they turned to such files in 33% of cases. Therefore, it is important what is written there. If the instruction is outdated, contradictory or can be understood in different ways, the agent can pick it up and act accordingly.
That's why Sulimovsky advises treating changes to CLAUDE.md almost like changes to code. After all, one bad line can affect subsequent agent sessions.
The researchers also recorded 1,328 document readings. And in only three cases was the next action code editing. Usually, after the document, the agent continued to read other files or moved on to reasoning. However, the authors of the study warn that their analysis does not see all the inner workings of the model. Therefore, they call the connection between reading documentation and subsequent code editing still uncertain.
So, one line “be sure to run tests after changes” may not be enough to be sure that the agent will actually do it. Therefore, for critical requirements, Sulimovsky advises not to limit yourself to text. If the rule can be turned into a test, linter, hook, runnable example, or CI check, it is better to do just that. For example, instead of the instruction “the data must match this schema,” you can give a formal schema and a validator that will automatically show whether everything is really okay.
The developer also suggests not looking at the agent's phrase "everything checked," but looking at the logs. Did the test run? Was it successful? If the run failed—did the agent fix the problem and run it again?
Another common mistake among developers is scattering instructions between files. For example, some of them may write a short instruction in Claude.md, and “hide” the details in links to other files. But in the logs, the researchers did not find cases where the agent followed a link from one document to another or compared two documents with each other.
So Sulimovsky advises making the path for the agent as direct as possible. For example, write something like: “before changing the API, open testing.md, find the Integration Tests section and execute it.” If the agent needs certain information in almost every task, it can be loaded into the context immediately, rather than forcing the model to search for the required file each time.
A separate problem arises when troubleshooting. After failures, reading the documentation was the agent's first reaction only in about 5% of cases. More often, he went to read the code, repeated the previous action, or immediately tried to fix something.
Therefore, the developer recommends including the main steps directly in the agent instructions: what command to run for diagnostics, how to safely roll back changes, and what to check afterwards. Even better, format it as a ready-made command or script.
In addition, AI agents not only read documentation, but also actively edit it. Among the more than 33,000 pull requests analyzed, 41.5% of the files that were most frequently modified by agents were AGENTS.md, CLAUDE.md, and copilot-instructions.md.
So the agent can change the rules file and in the next session receive their own edit as part of the input context. Because of this, Sulimovskyi advises separating the agent's temporary plans and drafts from permanent rules. And check changes in CLAUDE.md and AGENTS.md separately, because they can affect how the agent will behave further.
Previously, dev.ua wrote about another study of the CLAUDE.md and AGENTS.md files. Then, researchers analyzed about 532,000 such files and found that they often contain redundant, contradictory, or outdated instructions that can impair the operation of the AI agent.
А ще краще почитати офіційні гайди по промптінгу і не вигадувати велосипед