Preventing architectural drift: keeping a codebase coherent when agents write most of it

A human engineer carries a model of the system in their head — they know logic lives in services, that components don't talk to the database, that this is how errors propagate — and they (usually) write the new code to fit. An agent doesn't carry that model across a session; it works from the context it's given and the most direct path to a working result. Asked to fetch some data, it writes a fetch wherever it's standing, not necessarily through the layer your architecture routes everything through. The result runs perfectly and quietly violates the shape of the system.

Speed makes it worse. The same productivity that makes agents valuable means more changes per week, and every change is another chance to deviate. Drift that used to accrue over a year of human commits can accrue over a month of agent-assisted ones — and because each individual deviation is small and the code works, none of it trips the alarms that catch outright bugs. It just makes the codebase a little less coherent, a little harder to reason about, a little more expensive to change, every single PR.

Tests pass on architecturally-drifted code, because the code is correct — it does the right thing, just in the wrong place. Linters pass, because a misplaced data call breaks no syntactic rule. Type checkers pass, because the types line up. Every automated gate you have for catching mistakes is blind to drift, because drift isn't a mistake in the local sense; it's a mismatch with a system-level intent that none of those tools were given.

That leaves human review as the only line of defense, and human review is exactly where drift slips through — a reviewer reading a 30-file PR to check that it works has neither the time nor the held-in-memory map to notice that one new file ignores the layering the other 29 respect. The deviation looks like normal code because it is normal code, locally. Catching it requires comparing the change against the codebase's established patterns, deliberately, which is more than a tired reviewer at the bottom of a queue reliably does.

The defense has two halves. First, make your intended architecture legible: document the layers, the boundaries, the conventions, and put them where both your agents and your reviewers can see them — drift thrives in the absence of a stated structure to drift from. Second, check for deviations at the moment they enter, on the diff, while the fix is still one file. That's the half quality·vibes automates: basic structural and architectural deviations are one of the slop patterns it reads each PR's diff for, flagged in place alongside the duplication, naming drift, and non-idiomatic usage that tend to travel with them.

Two honest boundaries keep this useful rather than overclaiming. quality·vibes catches basic structural deviations — a change that visibly cuts against the repo's established patterns — not deep architectural-fit judgments about whether your overall design is the right one; that conversation stays human. And like everything it does, it suggests rather than enforces: it flags the deviation with an accept/dismiss control and lets a person decide, never auto-applying a fix or auto-merging. The value is timing. Caught on the diff, drift is a quick correction; caught six months later, it's a refactor nobody has budget for.