Engineering teams are getting better at building harnesses around agents.

That is a good thing. A useful agent is a model operating inside a system: tools, retrieval, memory, routing, permissions, guardrails, evals, and human checkpoints. The harness gives the agent an environment to act in.

The harder question is whether those agents are operating from context they can trust. The risk is that teams improve the agent environment while leaving the underlying context layer stale, fragmented, and unaudited.

That makes documentation part of quality assurance.

Documentation is one of the ways an engineering organization verifies that work can be understood, changed, operated, and reviewed safely. When documentation drifts, degradation spreads beyond the code into the system of understanding around it.

That context layer needs its own harness, especially the documentation layer.

Coding agents need more than access to code. They need access to the reasoning around the code: why a service exists, why an architectural tradeoff was made, what constraints matter, and which parts of the system are mission critical or high risk.

That reasoning often lives in design docs or Requests for Comment (RFC), architecture decision records (ADR), implementation plans, and READMEs among other documents. The problem is that those documents rarely receive the same maintenance discipline as the code they describe.

The result is documentation drift. The system changes, but the written context does not change with it.

For humans, that creates friction. For agents, it creates bad context at machine speed.

Agent harnesses are downstream of context

When people talk about agent harnesses, they usually mean the system around the model that makes it useful enough to operate: tools, memory, retrieval, routing logic, permission boundaries, evals, approval gates, and checkpoints where a human reviews the plan or output.

That surrounding system matters because models are not reliable contributors by default. They need context, recovery paths, and clear boundaries for when to act or stop.

Agent skills is only one piece. Agent behavior depends on the environment around the agent. But the harness can only orchestrate with the context that exists.

If the relevant design doc is out of date, retrieval can surface it faster, but faster access to wrong context doesn’t help. If an ADR explains the original decision but never records that the decision was reversed, the agent may follow the old path with confidence. If business logic lives only in a few people’s heads, the code may tell the agent what happens, but not why it must happen that way.

A better agent harness can route, constrain, and evaluate. It cannot make missing rationale appear.

Documentation is quality assurance

Most engineering organizations already have enough abandoned docs to make “more documentation” feel like a waste.

The useful goal is documentation integrity.

Documentation integrity means the written context still matches the system: the code, the architecture, the business logic, the constraints, and the decisions that shaped them.

That is a quality standard.

We already accept that tests, code review, type checks, and observability protect quality in different ways. Documentation belongs in that same family. It protects the quality of understanding.

Bad documentation creates operational risk because it gives people and agents a plausible but outdated basis for action.

That standard matters more now because AI has changed the economics of documentation. Before, the first problem was creation cost. Teams did not have enough documentation because writing it manually took time. A useful design doc, migration plan, or service README competed with product work, incidents, planning, and everything else engineering teams are responsible for.

AI changes part of that equation. It can draft a README, summarize code, turn a planning thread into an implementation plan, generate a first pass at an ADR, or suggest documentation updates after a code change.

That lowers the cost of creation.

But cheaper creation doesn’t solve usefulness or trust. In some cases, it creates a lot of text that looks useful and that needs validation.

The bottleneck moves from documentation creation to documentation integrity: whether engineers and agents can trust what the docs say when the system changes.

Why documentation drifts

Documentation drifts because maintaining it competes with visible, rewarded work and consistently loses.

Features have customer needs, incidents have urgency, and customer commitments have names attached to them. Documentation upkeep usually arrives as invisible maintenance work: important, easy to defer, and rarely celebrated when it prevents confusion later.

That is why “make documentation updates part of the definition of done” fails in many organizations. The idea is correct, but the system around it is weak. Under delivery pressure, teams protect the work that is measured, reviewed, and rewarded. Documentation maintenance becomes cleanup someone may remember after the release, the migration, or the incident.

A well-architected documentation harness makes quality cheaper to preserve than to skip.

That means the harness cannot depend on everyone remembering to be virtuous. It has to connect documentation updates to the work already moving through the system: READMEs, code diffs, architecture decisions, and agent failures.

What a documentation harness does

A documentation harness is the operating model that keeps engineering documentation accurate as the system changes. It defines what must be documented, where context lives, who owns it, how updates happen when code, architecture, and business logic change, and how humans and agents know which documents to trust.

A documentation harness is a maintenance system, built to keep context current as the system changes.

It answers practical questions:

  • Which decisions need an ADR, and how do we mark one as superseded?
  • Which changes require an RFC or design doc?
  • Where does business logic live when the code alone is not enough to explain it?
  • What belongs in a service README versus an architecture doc?
  • Who owns the documentation for a service, workflow, or domain?
  • How do we know setup, testing, deployment, and recovery instructions still work?
  • Which documents should a coding agent retrieve before touching this part of the system?
  • When an agent fails because context was missing or wrong, how does that feed the maintenance loop?

It also needs a triage model, because every document cannot receive the same rigor.

I would treat documentation in three tiers.

Tier 1: decision and business-critical context. Business logic, compliance exceptions, irreversible or expensive architectural decisions, security boundaries, data contracts, migration status, and customer-impacting workflows need the strictest treatment. They need owners, review triggers, supersession rules, and links from the code paths or services they explain.

Tier 2: operating context. Service READMEs, setup instructions, testing guidance, deployment notes, and ownership maps need lighter but consistent maintenance. They should be close to the code, easy to validate, and refreshed when the service changes.

Tier 3: exploratory context. Speculative design docs, early proposals, investigation notes, and abandoned options need a shelf life and an owner. Some should expire. Some should become ADRs. Some should be archived clearly so humans and agents do not mistake exploration for current direction.

That triage matters because maintenance capacity is finite. Agents can now draft and maintain documentation, but humans remain responsible for validating that it’s accurate so we should not ask the organization to keep everything equally current. The work is deciding which context creates enough operational risk, leverage, or reuse to deserve harness-level rigor.

Agents can become drift detectors

AI creates documentation risk, but it also gives teams a new way to notice drift.

The weak version of AI-assisted documentation generates more prose and asks humans to trust it. The stronger version uses agents and checks to detect where documentation has drifted from the system, then routes that drift back into maintenance.

An agent can compare a code diff with nearby docs and flag that a README still names an old setup path or detect when a migration changes a public API contract without touching the corresponding contract doc. A repeated agent failure can route back into documentation maintenance instead of being shrugged off as another hallucination.

Agent failures become useful signals when teams treat them first as context failures worth investigating.

If an agent repeatedly chooses the wrong test path, maybe the testing instructions are hard to find. If it keeps violating an architectural boundary, maybe the boundary lives in review comments but not in a durable decision record. If it misunderstands a business rule, maybe the rule exists in code and Slack history but nowhere a human or agent can reliably retrieve.

This is where the harness adds value. It creates feedback paths so repeated confusion, review friction, incident learnings, failed checks, and agent mistakes improve the context layer over time.

How drift gets expensive

Imagine a team migrating from one authorization model to another. They write a design doc, create an implementation plan, and update a few service READMEs. Halfway through, a requirement forces an exception. The migration continues, but the path changes. Some services use the new model. Some are intentionally deferred.

Without a documentation harness, the original design doc remains the most complete artifact. Six months later, a coding agent is asked to update an authorization flow. It retrieves the design doc, sees the target architecture, and proposes a change that assumes the migration was completed. The code compiles. The plan sounds reasonable, but a regression gets introduced.

The agent didn’t lack effort. It had the wrong map.

With a documentation harness, the migration plan carries status. The ADR records the exception or points to a superseding decision. The service README identifies whether the service is migrated, deferred, or intentionally on the old path. The implementation plan treats documentation updates as part of the work instead of cleanup someone may remember later.

That gives humans and agents a better chance of acting from the current reality. It also turns documentation from a passive reference library into part of the work itself.

Some documentation should move closer to code

There is a fair counterargument here: prose drifts fastest.

Strong teams often reduce drift by moving rationale closer to the systems it describes. They use in-repo ADRs, comments, and repository instructions that live by the service. A documentation harness should not defend a parallel prose layer when the better answer is fewer artifacts closer to the work.

Some context belongs in code-adjacent artifacts because it changes with the code. Some belongs in durable decision records because the rationale spans multiple services or outlives a single implementation.

Each kind of context needs a home where it can stay accurate, discoverable, owned, and useful under delivery pressure.

A good harness should reduce documentation sprawl.

Documentation drift signals

Engineering leaders can listen for where context keeps failing.

Some useful signals include:

  • Setup or onboarding instructions fail on a fresh machine, and everyone has a private list of undocumented steps.
  • A document’s last meaningful update trails the code it describes by several releases.
  • PRs routinely change a service without touching its adjacent README or ADR, which you can measure directly from diff history.
  • A search for a topic returns several docs with no way to tell which one is current.
  • A post-incident review finds the runbook was missing, wrong, or pointed at a decommissioned system.

AI can help with that maintenance, but generated documentation needs the same skepticism as generated code. It can draft, compare, flag, and suggest. Humans still need to decide whether the explanation is accurate enough to trust.

Where to start

The starting point should be small enough to survive contact with delivery pressure. Pick the two highest-risk services or workflows where stale context would create the most review burden, rework, incident risk, or release uncertainty.

Then instrument two measurable drift signals. For example: how often code changes without adjacent README or ADR updates, and how often agents or engineers fail because setup, testing, ownership, or business-logic context is missing or stale.

Finally, assign ownership as a standing responsibility. A platform, enablement, or engineering quality owner can maintain the triggers and checks, while domain teams own the accuracy of the documents their services depend on.

Your documentation integrity is the ceiling

Undocumented systems have always been expensive for humans. AI-assisted engineering makes the cost more visible because agents depend on written context more directly. They can help create and maintain that context, but only if the organization treats documentation integrity as part of quality assurance.

Agent harnesses matter. We need tools, permissions, evals, memory, routing, and checkpoints. Those systems depend on the context they can reach.

The next stage of AI-assisted and agentic engineering will depend on more than better skills, better models, or better harnesses around agents. It will also depend on whether the written context around the system is accurate enough to guide safe action.

If agents are going to contribute to engineering work, the documentation layer needs a harness too.