The Wiki Has a Second Tenant: Why Docs for AI Agents Are Different from Docs for Humans

A senior engineer at a mid-sized SaaS company spent two days last quarter chasing a deployment bug that turned out to be the agent's fault. The agent had read a runbook last updated in 2023, faithfully followed step three, and ran a command that no longer existed in the deploy tooling. The runbook still rendered fine in the wiki — the screenshots were even still legible — but it had silently become hostile to a reader who couldn't tell that the surrounding context was stale. The human authors had no idea the doc was now a load-bearing input for every new hire's AI assistant.

This is the quiet shift that has happened in most engineering orgs over the past eighteen months: the internal wiki has accumulated a second audience. The same Confluence pages, the same architecture diagrams, the same "how we deploy" gists are now being read by two distinct consumers — the engineers themselves and the AI assistants their engineers use. The two readers consume the same words under entirely different constraints and produce systematically different failure modes when the docs were written with only the first one in mind.

The problem isn't theoretical. AI bots now drive roughly 2% of all web traffic, up from about 0.5% in early 2025, and that ratio is dramatically higher for internal corpora that get aggressively crawled by every engineer's coding assistant. Many orgs report that their wiki is read more by agents than by humans on a typical weekday. Yet almost none of them have asked the basic question: what does it mean to be a good document for that second reader?

The Two Readers Have Opposite Tolerances

A human and a coding agent fail on different parts of the same page.

A human reading a runbook can tell within five seconds that something is off. The screenshot shows last year's UI. The Slack handle in the "ping if broken" line belongs to someone who left. The version pin in the example command is three majors behind. None of this is in the text — it's in the surround. The human reader integrates a hundred small signals about freshness and authority before they even reach the steps. The doc could literally lie to them and they would notice.

An agent reads the same page with none of that scaffolding. It cannot see that the screenshot is stale because it does not look at screenshots. It does not know which Slack handles are still active. It has no model of which docs in the wiki are "the canonical one everyone uses" versus "the half-finished draft someone left behind in 2022." It reads the steps and follows them with the same confidence whether the doc is the team's gospel or an experimental brainstorm that should have been deleted. The asymmetry is what bites: humans tolerate ambiguity that agents resolve wrong, and agents tolerate density that humans bounce off.

The mirror failure is just as common. Engineers write a wiki page tuned for human skim — a punchy header, a diagram, a couple of bullets, lots of implicit "you know what I mean" context. The agent reads it and synthesizes confidently in the gaps the diagram was supposed to cover, because the agent does not know that the diagram is the load-bearing part. Or the team writes a dense reference doc with explicit scope statements, version pins, and inline caveats — beautiful for an agent, exhausting for a human. The org ends up writing one doc and shipping the other broken.

Failure Modes That Only Show Up in Production

The clearest evidence that internal docs have become a second product surface is the new class of bugs they create.

The most common is the stale-doc-as-confident-source failure. A deprecated runbook, last touched two years ago when the deploy system was rewritten, sits unowned in a corner of the wiki. Every agent integrated with the corpus retrieves it, treats it as authoritative, and confidently teaches new engineers a procedure that no longer works. The doc ages quietly because no human is reading it anymore — the humans long ago learned to ignore it — but the agent has no such tribal knowledge. Roughly 80% of internal knowledge bases go stale within months of launch, and the staleness is invisible in the per-page metadata until someone goes looking for it.

The second is the synthesis-across-tiers failure. The agent retrieves a canonical architecture doc and an exploratory design proposal that contradict each other on a key detail. To the human, the difference is obvious — one lives under /docs/architecture/ with a "blessed" tag and the other in /scratch/proposals/ with a draft label. To the agent, both are markdown files in the same RAG corpus. It splits the difference and produces a hybrid that doesn't match either source, and the engineer reading the answer gets a plausible-looking architecture description that no team actually built.

The third is silent corpus poisoning — adversarial or otherwise. Recent academic work has shown that injecting just five malicious texts into a knowledge base of millions of documents can hit a 90% attack success rate against retrieval. The internal-docs version is more banal but no less damaging: a single page added by a junior engineer who misunderstood the system, never reviewed because nobody owns "the corpus," now permanently shapes how every developer's agent answers questions about that subsystem. The supply chain for what your agent learns runs through your wiki, and most teams have no review process on it.

The fourth is the scope-collapse failure. An agent retrieves a doc that says, in the human-context-laden way humans write, "we use Postgres for everything." The doc was written by the platform team about platform-team systems and the implicit "we" was their team. The agent generalizes the statement to the whole company, including the analytics platform that runs on Snowflake and the realtime service on Cassandra. Nothing in the doc told the agent its scope was narrower than the words suggested, and the human writer never thought to make it explicit because no human reader would have made that mistake.

What "Writing for Both Audiences" Actually Means

The instinct on hearing this is to publish a separate AI corpus — llms.txt, AGENTS.md, a parallel set of agent-only docs — and call it solved. That's a partial answer at best. The internal wiki is not going away, agents are going to keep reading it whether you bless it or not, and a parallel corpus that drifts from the human one introduces its own failure mode where the two diverge silently. The harder discipline is to write the primary docs so they serve both readers.

A few patterns are landing in the orgs that have started taking this seriously.

The first is explicit scope and freshness metadata on every doc that matters. Not as a stylistic flourish — as a structured block at the top of the page that pins what the doc covers, what it does not, when it was last verified against reality, and who owns it. Humans skim past this header. Agents condition on it. The cost to the human reader is one line of visual noise. The cost to the agent of not having it is the synthesis-across-tiers failure above.

The second is a two-tier classification that distinguishes canonical docs from exploratory ones. Canonical docs are the ones the team will defend in an incident review — the deploy runbook, the on-call procedure, the architecture-of-record. Exploratory docs are everything else — design proposals, brainstorms, the half-finished post-mortem someone never finished. Both are useful to humans. Only the first should be in the agent's high-trust retrieval path. Some teams enforce this with separate corpora; others with a canonical: true flag in frontmatter that the retrieval layer respects. Either works. What doesn't work is letting the agent treat both as equal.

The third is machine-parseable canonical statements for the load-bearing claims a doc makes. Where the human version says "we mostly use Postgres but the realtime path is Cassandra and the warehouse is Snowflake," the agent-readable version pins those mappings explicitly, ideally near the top, ideally in a format the retrieval layer can index on. This is the section the agent will quote back to the engineer who asks "what database does service X use," and the format should make it hard to misread.

The fourth is a maintenance cadence that flags stale docs rather than letting them rot. Some teams now run a weekly job that compares doc metadata against active code paths and flags docs older than 90 days in modules that have shipped recent changes. The flag does not auto-delete — it surfaces a candidate list to the doc owner. The discipline is the same one mature teams apply to flaky tests: stale docs are tombstones, not infrastructure, and treating them as the latter is the failure mode.

The fifth, and the one most teams underweight, is explicit tombstoning. When a doc is deprecated, it does not just get a "DEPRECATED" banner that humans skim past. It gets a structured marker that the agent's retrieval layer knows to deboost or exclude entirely, plus a forward pointer to the replacement. The cost of leaving an old runbook discoverable to the agent is the agent will follow it. Forever. Until you delete it or starve it of retrieval signal.

Internal Docs Are Now a Multi-Tenant Product Surface

The reframe that helps most engineering teams is to stop thinking of internal documentation as "a place we write things down" and start thinking of it as a multi-tenant product surface with two consumers — engineers and their agents — and editorial standards that account for both.

That sounds grand for a Confluence site. It isn't. The shift is mostly procedural: someone has to own the corpus the way someone owns a public API, with a stated bar for inclusion, a deprecation path, and a review cadence. The bar doesn't have to be high. It has to exist. The orgs that have one are catching the stale-runbook class of incidents before they hit production. The orgs that don't are funding their AI assistants to teach every new hire the wrong thing, slowly, with high confidence, and no obvious feedback loop.

The cost frame that finally moves leadership is the realization that un-curated docs become a liability that compounds with every new agent integration. Each new tool — the coding assistant, the on-call summarizer, the customer-support agent that mines internal Slack — multiplies the surface area of the bad doc. A page that wasted one engineer's afternoon in 2023 wastes hundreds of agent-mediated minutes per week now, distributed across so many small misroutes that nobody traces the cost back to the page.

The teams that come out ahead in the next year will treat the internal wiki the way mature teams treat a public API: with stated owners, an inclusion bar, a deprecation path, and an explicit sense of who is downstream of every page. The second tenant has shown up whether the team named it or not. The teams that named it are writing better docs for both audiences. The teams that haven't are quietly shipping a worse experience to both.