Living documentation: agents that keep the CMDB and diagrams current

Few things breed as much distrust in an IT organization as an outdated CMDB. During an incident, someone checks what a service depends on, finds a server that was decommissioned a year ago and stops trusting the tool. From then on, every team keeps its own spreadsheet and the CMDB becomes an audit requirement nobody uses to make decisions.

Architecture diagrams suffer a similar fate. They are drawn carefully for a committee or an audit and start aging the next day. This article explains why that happens, which sources let you rebuild reality automatically and how to use AI agents to keep documentation current without losing control over what gets published.

Why documentation goes stale

The root cause is not a lack of discipline. It is that documentation is maintained through a different channel from the one that produces changes. Changes happen in pipelines, cloud consoles, repositories and tickets; documentation is updated by hand, when someone remembers. Some concrete causes:

• Ephemeral infrastructure. Containers, functions and autoscaling groups create and destroy resources at a pace no manual process can follow.
• Out-of-process changes. An emergency fix in the console resolves the incident and never makes it back to the repository or the CMDB.
• Implicit dependencies. A service starts calling another one for a new feature. Nobody records it because nobody considers it an architecture change.
• Unclear ownership. If a configuration item has no owner, keeping it current is everyone's job, and therefore no one's.
• Diagrams as images. A diagram stored as an image or in a drawing tool cannot be compared automatically with reality.

The ITIL 4 service configuration management practice stresses that configuration information should be reliable and useful for decisions, not exhaustive. That is a good starting point: the aim is not to record everything, but to make sure what is recorded is true.

Discovery sources

The good news is that much of reality is already recorded in some system. The work is to bring those sources together and reconcile them.

Source	What it provides	Limitation
Cloud inventory APIs (for example AWS Config, Azure Resource Graph, Google Cloud Asset Inventory)	Existing resources, their configuration and, depending on the service, their change history	They don't tell you which business service each resource supports if tagging is poor
Distributed traces and service maps (OpenTelemetry, APM platforms)	Real dependencies between services, observed in production traffic	They only see what is instrumented and what had traffic in the analyzed window
Infrastructure as code repositories (Terraform, Ansible, Kubernetes manifests)	Intent: how each component should be configured and who changed it	They don't reflect changes made outside the repository
Network discovery tools and the CMDB's own discovery	On-premises equipment, legacy systems, network relationships	They need credentials and ongoing maintenance of discovery patterns
Change and incident management	Context: why something changed, who approved it, what failed	Free-text information of variable quality

No single source is enough. The most useful combination is usually intent (the code), actual state (the cloud APIs) and observed behavior (the traces). When all three agree, the data is reliable. When they don't, there is drift worth reviewing. This is why software should be written to be observable: without trace context propagation, the dependency map stays incomplete.

Detect drift and propose, don't write

The agent's role is not to replace the CMDB or write to it unchecked. It is to compare sources, detect differences and prepare update proposals for a person to review. A reasonable cycle works like this:

1. Collection. The agent queries the sources with read-only permissions and normalizes the data into a common model: component, type, owner, service, relationships.
2. Reconciliation. It compares that model with what is recorded in the CMDB and the diagrams, and classifies each difference: new component, retired component, new relationship, different attribute.
3. Explanation. For each difference it looks for context in recent changes, commits and tickets. A new relationship that comes with an approved deployment is expected; one with no trace deserves attention, because it may point to an unauthorized change.
4. Proposal. It prepares the update in the target's format: a suggested CMDB record, a pull request against the diagrams repository or a comment to the service owner.
5. Human review. The item's owner approves, corrects or rejects it. Rejections feed back into the rules so the same false positive doesn't keep coming back.

For infrastructure managed with Terraform, basic drift detection already exists in the tool. An agent can run it periodically and use the result as one more signal:

#!/usr/bin/env bash
# Detects drift between Terraform state and real infrastructure.
# Requires an initialized working directory (terraform init).
# -detailed-exitcode: 0 = no changes, 1 = error, 2 = differences found.
terraform plan -refresh-only -detailed-exitcode -no-color > drift.txt
rc=$?
if [ "$rc" -eq 2 ]; then
  echo "Drift detected: review drift.txt"
elif [ "$rc" -eq 1 ]; then
  echo "terraform plan failed" >&2
  exit 1
fi

What the agent adds on top of this output is not the detection itself, but the interpretation: which service is affected, whether the change has an associated ticket and what should be updated in the documentation.

Architecture notes and runbook drafts

Once the component and dependency model is reliable, the agent can generate derived documentation. Two cases work well:

Diagrams as code

If diagrams are maintained as text (for example using the C4 model and tools such as Structurizr, Mermaid or PlantUML), the agent can propose specific changes to the source file, reviewable line by line in a pull request. That is far more verifiable than regenerating a whole image. We recommend keeping levels separate: context and container views change little and are best curated by a person; detailed views can be generated more freely.

Architecture notes and runbooks

With the inventory, the dependencies and the incident history, the agent can write a first draft of an architecture note per service (purpose, components, dependencies, data handled, owner) or of a runbook (symptoms, checks, actions, escalation). It is a draft, not a final document. Its value lies in the specialist correcting rather than writing from scratch, and in the factual sections (dependencies, endpoints, resource names) coming from verifiable sources.

A common mistake is letting the agent fill with assumptions whatever it cannot find in the sources. Require it to flag gaps explicitly ("owner not identified", "no traces in the last 30 days") instead of filling them in. A document with flagged gaps is more useful than a complete but inaccurate one. Once reviewed, these runbooks can also feed agents for incident triage.

Governance: what the agent may write

The key question is not technical but one of governance: what the agent may change without review, what requires approval and what it must not touch. This checklist helps define it before you start:

• Read permissions separate from write permissions. Access to sources is read-only. Writing to the CMDB or repositories uses a different identity with limited scope.
• Attributes it may update on its own. For example, a component's last-seen date or a technical attribute that matches across all sources.
• Changes that require approval. Adding or retiring items, new relationships, changes of owner or criticality, any modification to published diagrams.
• Data it must never write. Secrets, credentials, personal data or classified information that shows up in configurations or tickets.
• Traceability. Every proposed or applied change records the source, the evidence and who approved it.
• Periodic review. Track the rate of accepted and rejected proposals; if the agent generates too much noise, adjust the rules before expanding its scope.

These rules are a concrete application of a broader principle: give each agent only the autonomy that its track record and the impact of its actions justify. Documentation is a good place to start with agents because an error is visible and easy to revert, but it is still information others rely on to make decisions.

Where to start

You don't need to tackle the whole CMDB at once. We recommend choosing a bounded domain, for example the critical services of one business line, and moving in three steps: first, have the agent only report differences for a few weeks, to measure how much drift exists and how much noise it generates; next, have it propose updates to owners; finally, let it apply on its own the low-risk changes that have proven correct.

The indicator that matters in the end is not how many items the CMDB holds, but whether teams start using it again during an incident. That is the proof that the documentation is alive.