Keep Architecture Models and Code Aligned with an Explicit Task

A diagram can be internally consistent while describing yesterday's implementation. Reusing system elements across architecture and sequence views reduces duplicate modeling, but correspondence with code still needs a deliberate update process.

Treat that work as an explicit task with a baseline, an allowed scope, and evidence of completion. An AI assistant can help investigate and propose edits when its access permits. The team still decides which behavior is intended and verifies that the model and implementation agree.

Start with a specific difference

In our fictional release-note agent, publication captures an approved draft revision and tracks a durable operation. In the baseline lost-response scenario, a maintainer requests outcome investigation. The shared teaching model also includes the later background-reconciliation extension examined here.

Now suppose a later implementation change adds a Reconciliation Worker. It periodically claims unresolved operations and queries the Release Host through the existing Publication Gateway. A definitive matching receipt marks the operation published. An inconclusive lookup leaves it unresolved. The worker never submits a fresh publication. Fieldnote's payment reconciliation path offers a concrete comparison: query the saved identity, then finalize only from an authoritative outcome.

This is a concrete model-maintenance task. “Keep diagrams up to date” is too broad: it supplies neither a change to examine nor a condition for being finished. Record the code commit range, current model reference, affected publication scenarios, and the reason the implementation changed.

Classify the mismatch before editing

A difference can mean several things. Decide which kind you found before modifying either side.

Different mismatches need different responses

Observation	Possible interpretation	Next action
Code adds a reconciliation query missing from the model	An accepted implementation change needs documentation	Verify its decision and tests, then update the affected flow
Code republishes after an inconclusive lookup	The implementation may violate the agreed recovery policy	Raise a code issue; do not redraw the policy to hide the difference
Model shows a dedicated service; code has a module in one process	The diagram may imply a deployment boundary that does not exist	Correct the level of abstraction after confirming runtime structure
A helper was renamed without a behavioral change	Only the code-to-model evidence mapping may be stale	Update the mapping rather than adding a new participant

Code is evidence of implementation, not automatic approval of its behavior. A model is evidence of a design decision, not proof that the system follows it. Keep both distinctions visible during the update.

Give the update an explicit contract

Here is a bounded task for the reconciliation change. Replace the baseline descriptions with real references before using it.

Reconcile the release-note agent model with the accepted change that adds background outcome checks. Compare the specified code commit range with the agreed publication model. Inspect the worker registration, claim logic, gateway lookup, store transitions, and their tests.

Update the existing model to show the Reconciliation Worker, its access to publication operations, and its use of the Publication Gateway for lookup. Reuse the existing store, gateway, and host elements. Add a focused recovery sequence: claim an unresolved operation, query the same remote identity, store a definitive matching receipt, or leave the operation unresolved after an inconclusive result.

Preserve the approved-snapshot rule and the rule that reconciliation does not create a new publication. Report any code path that contradicts either rule. This task authorizes investigation and model updates within the agreed workspace; it does not authorize changing code, publishing diagrams, or changing sharing permissions.

Return the inspected code baseline, updated model reference, list of changed elements and scenarios, evidence links, and unresolved differences. Request a separate implementation task if a code defect is found.

The scope matters. Without it, an assistant may “resolve” a contradiction by editing whichever artifact is easiest. Here the task is to reflect an accepted change and expose remaining disagreements, while code fixes retain their own review process.

Check the connected views

After adding the worker, inspect the architecture view. Its connections should make responsibility clear: it reads and updates operation state in the store, and asks the gateway to look up publication outcomes. It does not generate release text or approve drafts.

Then inspect the recovery sequence using those same elements. Show the lookup result that permits transition to published, and the result that leaves the operation unresolved. Include the operation identity and approved revision in your evidence notes so a reviewer can connect the recovery to the original intent.

Finally, revisit the approval and first-delivery sequences. The reconciliation change should not imply that approval moved into the worker or that an unresolved response became a definitive rejection. Shared participants keep the views connected; this semantic review checks what the interactions mean.

A redacted runtime trace can corroborate the observed call path. OpenTelemetry's trace documentation explains how spans represent work within a request. A recorded execution is still a sample, so combine it with code and tests when checking alternative outcomes.

Preserve the reason for the change

Keep a short decision record when the recovery policy changes. For this example, the reason might be that manual checks delay resolution, while automatic republishing would risk duplicate releases. The chosen worker performs outcome lookup only. Its cost is a scheduler, claim handling, provider query load, and operations that can remain unresolved.

Michael Nygard's architecture decision record proposal provides a useful structure: context, decision, status, and consequences. Use a small record linked from your normal repository or task workflow. An entire chat transcript is a poor substitute for the accepted decision.

Choose update triggers proportional to risk. A new external dependency, durable state, policy guard, or recovery path usually warrants a model check. A local refactor with identical responsibilities may require only refreshed code references. Requiring a diagram edit for every rename creates maintenance work without improving understanding.

Try it in Unograph

In the shared read-only model, select R - Reconcile the original outcome in background. Follow the existing Reconciliation Worker's connections and verify that none gives it a publication call. To practice the update in Unograph, use your own editable model and reuse the worker across its architecture and recovery sequence. Record the reviewed model reference and inspected code commit in the task before closing it.

The update is complete when the affected responsibilities and scenarios match the accepted change, contradictions are resolved or assigned explicitly, and a reviewer can follow the evidence. Implement and Verify an AI-Assisted Change Against a Model covers the preceding implementation review. Return to Understand an AI Agent's Code with Architecture and Sequence Diagrams when another unfamiliar path needs investigation, or use the release-note agent learning path to revisit the full workflow.