Catch architecture drift while coding agents write the code
Usually an architect or a tech lead, for every app the agents work in
Every sync checks the boundaries your team agreed against the code, and each week shows which rules broke, the change that broke them and the fix.
Fig. 01What changed, and who it reaches
The problem
Every change passes review, and the architecture still drifts. Coding agents write more code in a week than a team can read. The tests pass and the review looks fine line by line: a page that now reads the database directly, a module ten others suddenly depend on, a call to a provider that was meant to go through one service. The compiler checks types, not boundaries.
Reading every diff harder does not scale. What a team needs is the rules it already agreed, checked against the code on every change, and a record each week of what broke, what was fixed and what went unchecked.
How it goes
The same steps the product’s playbook walks. Each one shows the screen at that moment and opens the video there.
Declare the boundaries
Say which parts of the app must not depend on which, or which part alone may use a store, on the app's Boundaries tab or by asking chat. Each rule is a sentence the team agreed, checked against the code from then on.
Adopt the contracts between apps
The code plugin reads the app's endpoints, API clients, events and tables on your machine. With them a rule sees calls between apps, not only the imports inside one.
Let every sync prove the rules
Each sync checks each rule against the code and marks it Holds or Violated, with the files and imports behind each crossing.
Read what each week changed
Each week records itself: the pieces of work, who did them with which agent, and each rule that broke or holds again. A rule still broken when the week ends is flagged, and the week says how coupled the app became and what it could not check.
Fix what broke
Open the flagged week, see the crossing and the work that made it, and hand a work item to a developer or their coding agent. If the crossing was meant, mark it reviewed and change the rule instead.
- Proven by the code
End proofDone when a rule that broke is fixed, the next sync confirms the fix against the code, and the week records the rule as holding again.
Run this playbookFree account. Opens in ProvenMap as Catch architecture drift, with the steps beside you.
Works with
- Code
- Boards built from your repositories by the code plugin, which runs locally and pushes only derived metadata.
- Rules
- Declared by the team on the app's Boundaries tab, in chat, or from Claude Code through the workspace plugin.
- Contracts
- The endpoints, API clients, events and tables the code plugin adopts, which let a rule see a call between apps.
- Agents
- Claude Code, Codex, Cursor and others, recognised from the names they commit under.
Where it stops
- Rules are proven from imports, adopted contracts and the board's edges. A call made only at runtime, such as config routing or a service mesh, is not read, and each week's record says so.
- A rule says which parts may depend on which. Logic put in the wrong layer without a new dependency breaks no rule.
- The weeks record an app's own rules. Rules declared on the root board are proven without a repository, so no week records them.
- Coupling is a count as the week's last recording found it, not a judgement: how much is too much is the team's call, and it raises no flag.
- It checks structure, not behaviour. A rule that holds shows the structure follows it, not that the code is correct.
Walk through it
- The docs walkthrough of this job is being written.
- In the product this job runs as the playbook Catch architecture drift. The board ticks each step when what it asked for exists, and the guide links back to this page.
The features behind it
Start with one system
Map a real system and see the architecture around it.
Open one repository and run the code plugin. No migration, no rollout, no diagramming.
No credit card · Analysis runs locally in your own session · Self-hosted available
See the four commands to your first board →
Or for writing on architecture that stays connected across systems.