AI Agents Guide

Agent workflows for documentation: three that hold up, one that does not

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

Most attempts to have an agent maintain documentation fail the same way: the workflow depends on the agent noticing something, and agents do not notice things. They respond. The three workflows below are built around events that already exist in a team, so each one has something concrete that starts it, and the fourth is described so you can recognise it before building it.

Try it free
7 min readFor teams wiring an agent into how their documentation actually gets written

See it as a diagram

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

148/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

Workflow one: the onboarding sweep

The event is a repository nobody has documented. One session, one pass: the agent reads the repository, calls the design guide, builds the diagram on a canvas, validates it, and writes the overview around it. The output is explicitly a draft.

The value is not that the agent is right. It is that arguing with a wrong diagram is enormously faster than starting from nothing, and it surfaces disagreement between people who thought they agreed. Ask for the list of things it could not determine; that list is the agenda for the correction session.

Finish by putting the corrected version where people already look, as a live embed in the README rather than an image in a wiki.

Workflow two: the change-triggered edit

The event is a merge with structural impact. The agent applies the delta to the existing diagram and to the one paragraph the change makes wrong, then stops. The instruction has to say edit, not recreate, and has to define structural narrowly, or the workflow generates noise for every merge and everyone stops reading it.

There is a usable definition of structural to borrow rather than invent. Repository sync answers the same question by hashing the parsed structure that feeds the diagram, the Terraform draw plan or the assembled corpus, and doing nothing at all when the hash is unchanged. Written into an instruction file that becomes: a service, datastore, queue, or external dependency added, removed, or rerouted counts; a rename in a comment, a test, a version bump, or a variable default does not.

This is the workflow most worth writing into the repository instruction file, because it needs to be applied by whichever session happens to be running rather than remembered by a person.

## Documentation rules

Architecture diagram: Datadef project ARCH-PLATFORM.

- New or removed service, datastore, queue, or external
  dependency -> edit_diagram on ARCH-PLATFORM with that delta.
- Never create a second diagram for an update.
- Before a design review -> repo_status, and repo_refresh if
  the diagram is behind the branch.
- No structural change -> do nothing.

Workflow three: the review-time check

The event is a meeting. Before a design review, an incident review, or an architecture discussion, the agent checks whether the diagram still reflects the branch and refreshes it if not. repo_status reports the repository, the branch or tag, the commit reflected, the time of the last sync, and whether daily sync is on. repo_refresh regenerates it, which takes one to three minutes.

It works because it is attached to something that already has a time and a person. Policies that exist independently of a meeting tend not to survive the quarter.

The one that does not work: the unattended agent

The tempting design is an agent that watches the repository and updates documentation when things change. It cannot exist over MCP: tools run only when a model calls them inside a live session, and nothing runs between sessions. An agent given that instruction will agree enthusiastically and then do nothing, which is worse than refusing, because the team believes the loop is running.

The unattended half has to come from something that is a service rather than a session. A connected repository regenerates its diagram and architecture document daily from the branch or tag you chose, skipping commits with no structural change and keeping hand-moved node positions. Combine the two and each half does what it is capable of: repository sync for the structure, agent sessions for the judgement and the prose.

The test for any agent workflow

Name the event that starts it. If the answer is the agent will notice, the workflow does not exist yet. See letting an agent update docs after a merge.

FAQ

What is a realistic agent workflow for keeping architecture docs current?

Three that work in practice: a one-off onboarding sweep that drafts the diagram and overview for a repository nobody documented, a change-triggered edit that applies the delta after a structurally significant merge, and a freshness check run before design reviews. Each is started by an event that already exists rather than by the agent noticing anything.

Can an agent maintain documentation without anyone asking?

No. Agent tools execute during a session, in response to a model call, and nothing persists between sessions. Continuous updating has to come from a scheduled service on the product side, such as a repository connection that regenerates daily, rather than from the agent.

Where do the workflow rules belong?

In the instruction file at the root of the repository that the agent loads at the start of every session. It should name the specific diagram to edit, state that updates are edits rather than new diagrams, and define what counts as a structural change. Rules kept anywhere else are not read by the thing that has to follow them.

How do I stop an agent from rewriting documentation that was fine?

State that no change is a valid and expected outcome, and define the trigger narrowly. An agent asked to review documentation will always find phrasing to improve, and a stream of cosmetic changes is how a team learns to ignore documentation changes entirely.

What should the agent do before a design review?

Check whether the diagram still matches the branch it tracks and refresh it if it does not. For a repository-linked diagram that means reading the sync status, comparing the reflected commit to the branch head, and triggering a regeneration, which takes one to three minutes.