Whispering to AI agents in docs doesn't help, experiments show
Does whispering to agents in docs help?
A developer tested whether addressing AI agents directly in documentation improves their performance. Using fictional scenarios and multiple variations—headings, labels, HTML vs. Markdown, compression—he found that once an explicit recommendation is present, models follow it regardless of formatting. Crucially, labeling a conflicting section "For agents" had no more authority than a generic heading; both equally interfered with decisions. The conclusion: write clear, complete docs for everyone, and skip the agent-specific callouts.
If you write succinct, explicit, up-to-date instructions and provide complete examples, you may already be giving agents what they need.
- psygn89
Not sure, but if shared in the same docs as what we would read, it also allows us to skip over it with the assumption that it's a special set of instructions for AI.
- heymaikol
I’ve noticed something similar with coding agents. Specific rules seem to work better than simply saying “this is for AI.” I wonder if files like AGENTS.md work differently because the tools are designed to read from them first.
- croemer
The experiment in TFA is saturated so there's no signal there, unfortunately.