Documentation has always decayed. Now, for the first time, that decay has operational consequences.
Teams everywhere are checking in claude.md files, writing AGENTS.md, crafting elaborate system prompts, and building context documents that teach AI agents how to navigate their codebases, their data, their processes. It makes sense since context is the new code. The quality of what you feed a model directly determines the quality of what comes out. So everyone is investing in writing better context.
But we’re celebrating the writing while ignoring a much harder problem: the maintenance.
Here’s an uncomfortable truth every engineer knows but rarely says out loud: documentation is stale the moment you write it.
This isn’t a people problem. It’s a physics problem. The world a document describes is changing continuously. Schemas evolve, ownership transfers, SLAs get renegotiated, columns get deprecated, new tables appear, business logic shifts. A document is a snapshot. Reality is a movie.
We’ve lived with this forever. When docs were for humans, staleness was tolerable. A senior engineer would read a stale architecture doc, pattern-match against their experience, and fill in the gaps. Humans are remarkably good at compensating for bad information. AI agents are not.
When an agent reads a context document that says user_id is in the accounts table, and it was actually migrated to identity.profiles three weeks ago, the agent doesn’t “figure it out.” It confidently operates on wrong information. The same failure happens with semantic drift. If the finance team quietly redefined “active customer” to exclude trials, every agent generating revenue reports from the old definition is producing numbers that are technically correct but business-wrong. No schema changed. No pipeline broke. But the context was lying. In an agentic world where systems are making decisions, generating pipelines, and modifying data, confidently wrong is worse than ignorant.
The current advice is some version of: “Just tell the agent to update the docs” or “Make it part of your workflow — after every PR, update the context files.”
This is the equivalent of telling engineers to write unit tests through discipline alone, before CI/CD existed. We know how that ends. Manual processes don’t survive contact with competing priorities, deadlines, and team turnover.
Even more sophisticated approaches like git hooks, PR checks, and linting for doc freshness only cover what happens in code repositories. They miss the majority of context that matters: metadata changes, pipeline behavior, data quality shifts, access control updates, business logic encoded in BI tools, and changes in upstream systems you don’t control.
The deeper problem is that a huge share of the context an AI agent needs isn’t authored, it’s derived. It’s a summary of fast-changing, distributed state. There are three types of context to consider:
- Declared context is what humans know and write down: business rules, domain definitions, organizational conventions. “We soft-delete customer data, never hard-delete.” “When we say revenue, we mean only annual recurring revenue.” This changes slowly, but it does change, and when it does, nobody updates the doc. The challenge here isn’t speed, it’s awareness. Think of it less like a materialized view and more like a contract that needs periodic renewal.
- Derived context is summarized from fast-changing technical state: schemas, lineage, freshness, quality scores, access patterns, incident histories. The management challenge is computational. Detect changes in underlying signals, re-derive the summary, serve the updated version. Humans shouldn’t be in this loop at all.
- Observed context is what nobody wrote down but the system can infer: which tables are actually queried together, which columns are joined despite no documented relationship, which dashboards break when a specific pipeline is late. This emerges from usage patterns and is often the most practically useful for agents navigating unfamiliar territory.
All three types need to coexist in the same system, with different management cadences. A system that only handles derived context will miss the institutional knowledge that makes agents genuinely useful. One that only handles declared context is just a wiki with a reminder system.
The mental model shift: stop thinking of documentation as something you write once and start thinking of it as something you manage continuously, through computation, curation, and inference.
For declared context, treat docs as living contracts. Human-authored truths the system actively monitors for staleness. When a table described as “our core customer record” starts diverging from that description, the system should flag it for review, not silently let the gap widen.
For derived context, treat docs as materialized views over live signals: schema registries, quality monitors, pipeline metadata, access policies, usage patterns, lineage graphs. The “doc” is the rendered, agent-readable surface of underlying state that refreshes itself.
For observed context, treat docs as learned summaries: patterns the system discovers from actual behavior and codifies into context agents can use.
What this requires in practice: a context graph rather than a document store, change detection across the full stack, intelligent summarization that understands what matters per consumer, staleness detection for human-authored content, freshness SLAs per context type, and agent-native interfaces that return structured, current, trustworthy responses blending all three.
We’re entering a world where AI agents are autonomous participants in data operations, discovering datasets, building pipelines, resolving incidents, and enforcing compliance. The quality of their work is bounded by the quality of their context.
The companies that figure this out first will have a compounding advantage. Good context makes agents smarter, smarter agents generate better metadata, better metadata produces better context. It’s a flywheel, but only if the context stays fresh.
Context isn’t a document. It’s a living system. And it’s time we built the infrastructure to treat it that way.
