Docs & Code Guide

Keep architecture docs in sync with code: decisions stay, views regenerate

Documentation stays in sync with code when every page is one of two things: a dated record of a decision, which cannot drift because it describes a moment, or a current-state view that a machine can regenerate from the code itself. Pages that are neither, hand-drawn diagrams and prose descriptions of how the system works today, are the ones that rot. The whole practice is sorting your docs into those two piles and wiring a trigger to the second one.

Try it free
8 min readFor teams whose architecture pages describe the system of eighteen months ago

See it as a diagram

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

206/2000• 3 credits left
Try:

No account needed · Editable canvas, not a picture

The split that makes sync possible

A decision record says "in March we chose Postgres over DynamoDB, because". It is true forever, needs no maintenance beyond a status field, and is covered in depth in keeping ADRs up to date. A current-state view says "these services exist and talk to each other like this". It is false the week after the next big merge unless something regenerates it.

Most architecture wikis fail because their pages are secretly both at once: a diagram drawn during a decision, kept as if it were documentation of the present. Split them. Decisions go into an append-only log. Current state goes into artifacts chosen specifically because they can be rebuilt from the repo: a diagram generated from the code and infra definitions, a dependency list derived from manifests, a schema doc pulled from the database. What cannot be regenerated should not claim to describe the present.

C4 levels age at different rates

If you use the C4 model, the levels give you a maintenance budget. The context diagram, your system among its neighbors, changes on the timescale of partnerships and product strategy, often yearly; keeping it hand-curated is fine. The container diagram, deployable units and data stores, changes every quarter or two and is the sweet spot for regeneration. Component diagrams inside a service change with normal feature work, monthly or faster, and are only worth keeping if generated. Code-level diagrams should never be stored at all; an IDE produces them on demand.

The practical rule: the deeper the level, the shorter its half-life, and the stronger the case for generating rather than drawing. Teams usually get this backwards, lavishing manual care on component diagrams that will be wrong in six weeks.

Wire the trigger: path filters and PR labels

Drift happens at merge time, so merge time is when to catch it. A path filter on the directories that define your architecture, services, infra, proto or schema definitions, marks exactly the pull requests that can invalidate the container view. The cheap version adds a label or a checklist comment: this PR touches architecture, confirm the diagram still holds. The strong version regenerates the view as a CI step on merge.

Datadef's half of that loop is an MCP server, registry name io.datadef/mcp. An agent connected to it, Claude Code or Cursor in a CI job or during review, reads the repository and updates the diagram to match. To be exact about the boundary: Datadef does not watch the repo and nothing detects the merge by itself. The workflow below is what makes it fire, which keeps the trigger in your CI where you can see it. Connecting an agent requires an API key, available on paid plans; the setup is documented in the MCP diagram server guide.

# .github/workflows/regen-architecture.yml
name: regen-architecture
on:
  push:
    branches: [main]
    paths:
      - "services/**"
      - "infra/**"
      - "proto/**"
jobs:
  regenerate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      # An agent CLI connected to the Datadef MCP server, with its
      # API key in the job secrets. The agent reads the repo and
      # updates the named diagram to match this commit.
      - name: Redraw the container view
        run: |
          claude -p "Read services/, infra/ and proto/. Update the
          'platform-containers' diagram via the Datadef MCP server so
          it matches what this commit deploys. List what changed."

Publish the view where people already read

Regeneration only pays off if every copy of the diagram follows. A Datadef project shared public serves the diagram at a permanent image URL and an interactive embed page, so the wiki, the README, and the onboarding doc all reference the same source. After the agent updates the diagram, the embeds show the new version within minutes; nobody re-exports or re-pastes anything. That property, one source and many live references, is the point of a single source of truth for architecture.

Where the split model bends

Three boundaries keep this claim honest. First, the loop is invoked, not ambient: a CI job or an agent call regenerates the view, and if nobody wires the trigger, nothing happens. Second, live embeds require the project to be shared public; a confidential architecture keeps the regeneration loop but publishes by re-export instead. Third, Datadef regenerates diagrams, not prose. The paragraph explaining why the queue exists still needs a human, and the decision half of your docs is exactly where that prose belongs.

What drift costs when this is not done, and how to recognize it in your own wiki, is covered in documentation drift.

The sorting test

For every architecture page ask one question: could a machine rebuild this from the repo? If yes, generate it and wire a merge trigger. If no, date it, mark it a decision record, and stop pretending it describes today.

FAQ

How do I keep documentation in sync with code?

Split every page into one of two kinds. Decision records are dated and immutable, so they cannot drift. Current-state views must be regenerable from the code: diagrams generated from the repo and infra definitions, schema docs pulled from the database, dependency lists from manifests. Then wire a trigger, such as a CI path filter on architecture-defining directories, that regenerates the views on merge. Prose that describes the present but cannot be regenerated is the part that rots.

Which architecture diagrams go stale fastest?

The deeper the zoom, the faster the decay. In C4 terms, a context diagram changes roughly yearly, a container diagram every quarter or two, and component diagrams change with ordinary feature work, monthly or faster. Code-level diagrams are stale almost immediately and should be produced on demand rather than stored. Maintenance effort should follow the same order: generate the deep levels, hand-curate only the slow-moving top.

Can a diagram update automatically when code changes?

Not by magic, but by one wired trigger. Datadef ships an MCP server that lets an AI agent create and update diagrams from what it reads in a repository. Run that agent as a CI step on merges that touch architecture-defining paths and the diagram is redrawn within the same pipeline. Nothing watches the repo by itself; the regeneration is one command in CI or one agent call during review.

Should architecture decision records be kept in sync too?

Their content should not change at all: an ADR is a dated record of a choice and stays true as a record even after the choice is superseded. What needs syncing is the metadata, the status field and the index that says which decisions are current. Pair the immutable decision log with a regenerated current-state diagram so readers can see the history and the present separately.

What is the best trigger for reviewing architecture docs?

The merge that can invalidate them. A CI path filter on directories like services, infra, and schema definitions identifies exactly those pull requests. The lightweight response is an automatic label or checklist item asking the author to confirm the diagram still holds; the stronger response is a regeneration job that redraws the current-state view on merge.