A piece in heise's Continuous Architecture column makes an argument that is easy to dismiss and hard to refute: AI coding agents are forcing teams to clean up documentation they stopped trusting years ago.
The mechanism is not mysterious. An agent working in a repository reads what it can find — README files, architecture decision records, API docs, comments, diagrams, onboarding notes — and treats all of it as context. A senior developer reading an outdated document applies a lifetime of suspicion: she notices the deprecated client library, remembers that the endpoint moved, asks a colleague. An agent has none of that tacit knowledge. It retrieves, believes, and writes code against it.
That turns a familiar irritation into a correctness problem. A stale README used to cost a new hire an afternoon of confusion. Now it can produce a pull request that compiles, passes its tests, and ships an integration against an API that no longer exists. Missing documentation is not safer either: where the agent finds nothing, it fills the gap with something plausible — and plausible is exactly what a reviewer skims past.
The remedies are unglamorous and mostly cheap. Keep documentation in the repository next to the code and version it with it. Delete what is wrong instead of leaving it, because an absent document prompts a question while a wrong one prompts confident nonsense. Give decision records a status and a date so that 'accepted' means something. Generate API references and diagrams from the source rather than maintaining them by hand. Put the commands from the docs into CI, so a broken example fails the build instead of misleading a reader. And assign an owner, because unowned documentation rots by default.
The honest framing is that documentation debt predates AI by decades; every organisation already knows it has too much of it and no time to fix it. What has changed is the cost of the failure mode. A wrong document used to waste human time — expensive, but self-correcting, because people notice. A wrong document consumed by an agent produces work product that looks finished, which is the more dangerous failure.
Caveat: this is an argument piece, not a news report. The concrete practices above are ours; the article's specific claims should be checked at the heise source.
