Coding Agents Favor Instructions Over API Docs

The sharpest takeaway is that agent-friendly documentation is primarily an operational control surface, not polished prose—and agents still treat documentation as context more than as a testable contract.

• –Agent instructions and working notes dominate observed documentation use.
• –Documentation rarely led directly to code edits, challenging linear “read, then code” assumptions.
• –Most consultation was self-initiated, but it correlated with less immediate testing.
• –Code preceded documentation in agent-authored pull requests, making working notes a potential maintenance burden.
• –The observational design identifies priorities such as concise AGENTS.md files and executable checks, but does not prove causality.