AI Agents Guide

Letting an agent update documentation after a merge

By the engineer who builds Datadef, from client work on data platforms · Reviewed August 21, 2026

The merge is the moment documentation becomes wrong, and the moment the context for fixing it is cheapest: the diff is right there and somebody just spent a week understanding it. A merge-triggered agent turns that into a small, boring task instead of a quarterly audit that discovers drift months late. Here is the pattern, including the part it cannot cover.

Try it free
7 min readFor teams whose architecture pages are already three merges behind

See it as a diagram

Everything below, as a diagram you can edit. Describe yours and see it in seconds.

159/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Why the merge is the right trigger

Documentation goes stale in increments, and every increment has a timestamp: the commit that made the previous version wrong. Reviewing docs on a calendar means the reviewer is reconstructing months of those increments from memory. Reviewing at merge means one diff, one decision, no archaeology.

It also puts the work where the knowledge is. The person merging knows whether the new consumer is architecturally significant or an implementation detail. That judgement is expensive to recover later and free right now.

Most merges change nothing structural, and the correct output for those is nothing. An agent that opens a documentation change for every merge trains everyone to ignore documentation changes.

Edit, do not redraw

The failure mode of an enthusiastic agent is regeneration. Asked to update the diagram, it creates a new one from scratch, which reshuffles positions, drops the hand-added notes, and produces a review nobody can read because everything moved. The instruction has to be explicit: apply the delta to the existing project.

edit_diagram takes a plain-language instruction and applies it to a diagram that already exists. The canvas tools go finer when the change is precise: add one node, connect it, move it into the right zone. For a diagram linked to a connected repository, repo_refresh is the correct move instead.

A refresh is not a fresh drawing. The canvas as it stands is handed back to the generator as a listing of node ids, labels, types and zones, up to sixty of them, under a rule that anything still present in the source keeps all four, that a new id may be emitted only for something genuinely new, and that a node may be dropped only when the source no longer contains it. Nodes a person dragged more than twelve pixels from where the last sync left them keep those coordinates through the regeneration, and nodes added by hand on the canvas are carried over untouched. That is edit-do-not-redraw implemented rather than requested, and it is why a refresh produces a diff somebody can review.

Write the rule where the agent will read it, not in a wiki page it never opens. An instruction file at the root of the repository, naming the project id and the edit policy, is read at the start of every session.

## Architecture docs

The architecture diagram is Datadef project ARCH-PLATFORM.

After a merge that adds, removes, or reroutes a service, queue,
or datastore:
1. edit_diagram on ARCH-PLATFORM with the specific delta.
   Never create a new diagram for an update.
2. Update the paragraph in docs/architecture.md that the change
   makes wrong. Leave the rest.
3. If the merge changed nothing structural, do nothing.

The part an agent cannot own

An MCP tool call happens inside a session, in response to a model deciding to call it. Nothing runs between sessions. That means a merge-triggered agent needs something to start the session: a person, or a CI job that invokes an agent as a step. There is no configuration in which the diagram tool notices the merge by itself.

For structure that comes from declared source, the unattended lane already exists and does not need an agent. A connected repository regenerates the diagram and its architecture doc daily from the chosen branch or tag, skips commits that change nothing structural, and keeps hand-moved nodes where they were put. See how repository sync works.

A division of labour that works

Give the sync the structure: what exists, how it wires, how many of each per environment. It is deterministic, it runs daily, and it cannot invent a service.

Give the agent the prose and the judgement: the paragraph that explains why, the annotation on the deprecated path, the decision to promote a component into its own zone. Those are the parts a parser has no opinion about.

Then make sure both are visible in one place. A live embed in the README means the picture people see is the current one, rather than a screenshot that froze on the day someone exported it.

Measure the loop, not the intent

Track the gap between the commit the diagram reflects and the head of the branch. If it drifts past a week, the trigger is not firing. More on that in documentation drift metrics.

FAQ

Can an AI agent update documentation automatically after a pull request merges?

It can do the work, but something has to start it. Agent tools run inside a session, so a merge-triggered flow means a CI step or a person invoking the agent with the diff. The agent then reads the change, edits the affected doc and diagram, and stops. Nothing about the protocol lets a tool wake up on a merge by itself.

Should the agent regenerate the diagram or edit it?

Edit it. Regeneration reshuffles positions, discards hand-added annotations, and produces an unreviewable change. Applying the specific delta to the existing diagram keeps the review small and keeps everything a human added. The exception is a diagram generated from connected source, where a refresh rebuilds it deterministically and node positions survive.

How do I stop the agent from opening a documentation change for every merge?

Say explicitly that no change is the expected outcome for merges without structural impact, and define structural narrowly: a service, datastore, queue, or external dependency added, removed, or rerouted. Without that instruction, an agent asked to check documentation will always find something to say.

Where should the instructions for the agent live?

In an instruction file at the root of the repository, the one the agent loads at the start of every session. It should name the specific diagram to edit, the edit-do-not-recreate rule, and the definition of a structural change. A wiki page describing the policy is not read by anything.

What updates without any agent involvement?

Diagrams generated from a connected repository. They regenerate daily and on demand from the branch or tag you chose, along with an architecture document, and syncs on commits with no structural change are skipped so the history stays quiet when the code does.