Every codebase has a "last good state", a point in the commit history where the architecture was clean, the team shared a mental model of it, and changes were predictable. Every codebase drifts away from that state over time.
Drift is not a failure of engineering discipline. It is the natural consequence of code evolving under deadline pressure, changing requirements, and team turnover. What distinguishes well-managed codebases from unmanageable ones is not the absence of drift but the ability to detect and reverse it before it compounds.
Three kinds of structural drift
Community drift: the Leiden partition of the codebase shifts over commits. Files that previously belonged to one community migrate to another, or form new singleton communities (a sign of isolation, code that belongs to nothing). The migration itself is not always a problem; the direction matters. Community drift toward fewer, larger communities signals consolidation. Drift toward more, smaller communities with increasing cross-community edges signals fragmentation.
Keystone inflation: a file's spikescore increases over time as more things depend on it. A module that started as a utility for one feature has become a cross-team dependency. The file did not change in character; its graph position changed. Keystone inflation is the early warning sign for the god-object anti-pattern, visible in the graph before it becomes visible in the code.
Documentation lag: the delta between the last commit that touched a code node and the last commit that touched its associated documentation nodes. A file that has received 20 commits since its documentation was last updated is a documentation drift candidate. The documentation may still be correct; it also may be actively misleading.
Why drift compounds
Undetected drift compounds because it creates invisible technical debt. A team that does not know their community partition has fragmented does not account for the additional coordination cost in their sprint planning. A team that does not know a utility has become a keystone does not prioritise covering it with tests.
Each undetected drift increment makes the next one more expensive. A codebase with high community fragmentation is harder to reason about, which makes the next refactor harder to plan, which causes more drift per sprint.
Spiderbrain's drift tracking
Spiderbrain builds a brain per commit (or per significant milestone). Each brain carries the community partition, the spikescore rankings, and the documentation edge graph for that commit. Comparing two brains gives you the drift vector: what moved, what inflated, what fell behind.
The practical output of a drift comparison is an ordered list of structural changes, ranked by severity:
- Community membership changes (how many files moved across boundaries)
- Spikescore changes (which files became significantly more or less central)
- Documentation lag (which files have the largest commit delta to their docs)
Using drift detection in practice
Sprint retrospectives: compare the brain from the start of the sprint to the brain at the end. The drift vector tells you whether the sprint increased or decreased structural health. Teams that track this over several sprints start to see patterns, certain features reliably produce community fragmentation; certain refactors reliably reduce keystone inflation.
Pre-release audits: before a major release, run a drift comparison against the last stable tag. High drift means higher regression risk. The specific drift items become the focus of pre-release manual testing.
AI-agent oversight: when an AI agent has been running autonomously on the codebase, a drift comparison is the most efficient way to audit what it changed structurally. The diff tells you the lines changed; the drift tells you how the architecture moved.
The determinism advantage
Drift detection only works reliably if both brains being compared are computed deterministically. If the brain for commit A and the brain for commit B are influenced by any probabilistic element, the "drift" you observe includes model noise, not just structural change.
Spiderbrain's graph is deterministic: same commit, same brain, everywhere, every time. This makes drift comparisons trustworthy. The changes you see are real structural changes, not artefacts of the analysis.