I Gave Five AI Coding Agents a way to Fact-Check the Docs They Were handed. They Refused to Use it.

2026-06-19 · Source: Towards AI - Medium · Field: Technology & Digital — Artificial Intelligence & Machine Learning, Software Development & Engineering · Depth: Advanced, long

Summary

The study investigated how AI coding agents handle documentation drift, specifically when given stale, fresh, or no documentation, and whether they use available fact-checking tools. Conducted with \$120 of API credits, the pre-registered benchmark involved 3250 graded trials across five models (including GPT-5.4, Claude Haiku, Sonnet, Opus, and Gemini 3.5 Flash) from three providers. A key finding was that stale documentation led to catastrophic failure, with GPT-5.4 getting tasks wrong 100% of the time and ceasing verification. Crucially, any authoritative documentation, even fresh, suppressed agents' natural inclination to verify underlying code, which they did nearly 100% of the time without documentation. The study also found that fresh documentation was the most accurate and cheapest option, outperforming "no docs" by 36–46% lower total cost on four of five models due to reduced token usage from verification loops. The author's tool, Surface, which detects documentation drift, was also tested, showing that its drift report improved accuracy but did not fully prevent errors, highlighting that preventing drift is superior to correcting it.

Key takeaway

For AI Engineers deploying coding agents that interact with documentation, you must ensure the documentation is rigorously accurate. Your agents will implicitly trust provided docs and cease independent verification, even if tools are available. Prioritize maintaining fresh documentation, as it is both more accurate and significantly cheaper than relying on agents to rediscover facts or providing no documentation at all. Implement automated drift detection to prevent stale docs from misleading your models.

Key insights

AI coding agents prioritize provided documentation over independent verification, even when it's wrong.

Principles

• Any authoritative doc suppresses agent skepticism.
• Agent capability does not prevent doc-induced failures.
• Fresh documentation is both more accurate and cheaper.

Method

The study used a controlled variable design, varying only the documentation block in the prompt across five conditions (no doc, stale, fresh, stale with drift report, stale with generic warning) for 3250 graded completions.

In practice

• Implement documentation drift detection tools.
• Prioritize maintaining fresh, accurate documentation.
• Do not assume agents will self-correct with tools.

Topics

• AI Coding Agents
• Documentation Drift
• LLM Verification
• Model Behavior
• Cost Optimization
• Surface Tool

Code references

• Connorrmcd6/surface
• Connorrmcd6/surface-bench

Best for: AI Architect, Machine Learning Engineer, Research Scientist, AI Scientist, AI Engineer, Director of AI/ML

Related on AIssential

• .agent folder is making claude code 10x better... — Optimizing LLM context through structured documentation and sub-agents dramatically improves coding agent performance.
• Trust Me. I’m Artificial Intelligence. — AI models are becoming more convincing in their reasoning, but this does not equate to increased truthfulness or correctness.
• Code Is Not Cheap: How to Multiply Your AI’s Output With Software Fundamentals — AI-assisted coding, while prevalent, demands human engineering expertise to mitigate quality issues from "jagged" model outputs.
• Week Ending 6.7.2026 — AI systems, especially LLMs and agents, show advanced capabilities but often lack genuine reasoning and require careful design for reliable deployment.
• Agent Skills — AI coding agents require explicit workflow-based "skills" to enforce senior engineering practices and prevent shortcuts.
• Faster Code, Slower Understanding: A Survival Note from a Year of Agent-First Engineering — AI shifts the engineering bottleneck from code production to comprehension and maintenance, demanding new optimization strategies.

Open in AIssential →

Editorial summary, takeaway, and curation by AIssential. Original article published by Towards AI - Medium.