A migration gets scoped at six weeks. Eleven months later it is still running.
Nobody was incompetent. The plan was sound when it was written, because it was written against the architecture on the diagram. The architecture in the repository turned out to be a different system: four services reading each other's tables, three competing HTTP clients, and a retry policy that varies by whoever wrote the file.
None of that was hidden. Every one of those decisions arrived in a pull request that passed CI, got two approvals, and merged. The build was green every single time.
That is what architectural drift actually looks like. Not a breach of the rules, but the steady accumulation of changes nobody flagged, because nothing in the pipeline was built to flag them.
The question was never whether your architecture is documented. It is whether anything in your workflow can tell you, today, how far the code has already moved from it.
TL;DR: Architectural drift is the gap between the architecture you designed and the code you merged. Tests, linters, and scanners never check for it, so drift stays invisible until an incident, a migration, or an audit forces the count. Architectural drift detection closes that gap by scanning entire codebases for existing drift and enforcing architecture rules on every pull request. Pandorian runs both.
Nobody Notices Drift. They Notice the Incident.
Architectural drift is the widening gap between the architecture an organization designed and the code it actually merged.
Academic work on architecture erosion has been describing this pattern for decades, and the systematic mapping research on the subject frames it consistently: the implemented system diverges from the intended one through violations that are individually small and collectively structural. Nothing about that is new. What is new is the rate.
The trouble with drift is that it never presents as drift. It presents as a six-week migration that takes eleven months. As an incident postmortem where the root cause is a service that should never have had that database credential. As a new hire asking which of the three HTTP clients is the real one, and getting three different answers.
By the time drift is visible, it is expensive. Research on architecture erosion symptoms in code review makes the same point from the other direction: erosion tends to get considered late, after it has already degraded the system, which is exactly when it is hardest to reverse.
The cost curve is the whole argument for detection. A boundary violation caught in a pull request costs one conversation. The same violation caught after three services depend on it costs a quarter.
Your Pipeline Is Green and Your Architecture Is Wrong
Architectural drift detection fails in most pipelines because nothing running in CI is actually checking the code against the organization's own architecture.
Look at what a typical GitHub pipeline verifies on a pull request. Tests confirm the code does what the test says it does. Linters confirm formatting and a fixed list of language-level patterns. SAST tools confirm the absence of known vulnerability classes from a vendor-maintained library. Build steps confirm it compiles.
Every one of those checks is generic. Every one of them ships with rules the vendor wrote, not rules your architecture review board approved. None of them has ever read your ADRs.
So the check that would actually matter — the one that asks whether this change respects the boundaries, the dependency direction, and the contracts your organization decided on — has no stage. It was assigned to code review, which means it was assigned to whoever happened to be reviewing that day, and to whether they happened to remember the decision.
A green pipeline is a statement about correctness and syntax. It has never been a statement about architecture.
Five Signals That Tell You Drift Already Landed
Effective architectural drift detection starts with knowing which patterns in code actually signal that drift has landed. These five cover most of what matters in practice.
- Boundary crossings that shortcut the contract. A service reads another service's tables directly instead of calling its API. The change is small, the deadline was real, and the temporary label never came off. This is rule one of the Microservice Boundary Discipline package: a service boundary is defined by who reads and writes the data, not by which repository the code sits in.
- Dependency direction reversals. A lower layer starts importing from a higher one. A shared library picks up a dependency on a feature module. The graph inverts one edge at a time, and no single edge looks wrong.
- Reimplementation instead of reuse. Two teams solve the same problem two different ways because neither found the shared client. This is the signal that has moved fastest: GitClear's 2026 maintainability research, drawn from hundreds of millions of analyzed commits, tracks a sharp rise in duplicated code blocks alongside a decline in the reuse and consolidation habits that hold a codebase together.
- Contract and versioning divergence. Endpoints that ignore the organization's versioning convention. Error envelopes that vary by service. Pagination that works one way in one API and another way in the next. The API Design Best Practices package covers exactly this surface, down to fields removed or reinterpreted inside an already-published version.
- Resilience and configuration divergence. Retries without backoff, calls without timeouts, circuit breakers that exist in the standard and nowhere in the code, secrets read from config files instead of the secret manager, Terraform modules that skip the required tagging.
Notice what these have in common. Not one of them is a syntax error. Every one of them is a decision your organization already made, written down somewhere, and unenforced everywhere.
AI Doesn't Read Your ADRs. It Reads the File Next to It.
Architectural drift accelerates when AI coding assistants generate code that matches nearby patterns instead of documented architecture.
An assistant is exceptional at inferring intent from context. That is the entire mechanism. It looks at the surrounding files, infers the convention, and produces something consistent with what it sees.
Which is precisely the problem. If the file it is looking at contains the one exception your team agreed to tolerate in 2024, the assistant will reproduce that exception faithfully, at volume, across every service it touches. It has no way to know that the pattern it just copied was the compromise and not the standard.
Drift used to propagate at the speed of human typing and human onboarding. It now propagates at the speed of generation. The documentation gap that was survivable when a senior engineer could catch most of it in review is not survivable when the code volume triples and the reviewer pool does not.
This is why detection has to be continuous rather than periodic. A quarterly architecture audit was already arriving late. Against generated code, it is arriving into a codebase that has been rewritten since the last one.
Fix the Past, Guard the Future
Architecture enforcement in CI/CD works in two phases: codebase scanning to measure the drift that already exists, and pull request enforcement to stop new drift from landing.
Phase one is the baseline. Pandorian's Full Repo Scan analyzes an entire repository against selected guidelines and returns a count: which architecture rules are violated, where, and how many times. Every violation includes the file path, the line range, and an explanation of why that code breaks that rule.
The point of the baseline is not to fix everything. It is to stop guessing. Most organizations have never had a number for how far their codebase has drifted, which is why the conversation about it stays anecdotal.
Phase two is the guardrail. A PR Scan runs on every pull request and every push to an existing one, analyzing only the modified files. Violations post as inline comments on the specific lines and surface as a status check in CI.
On GitHub, that status check is the whole enforcement mechanism. Configure it as a required status check through branch protection or a repository ruleset, and the merge button stays disabled until the architecture rule passes, the same way it does for a failing test. Rulesets apply at the organization level, so one architecture policy covers every repository instead of being reconfigured repo by repo.
Roll it out without stopping the org. Every guideline runs in one of two modes. Monitor surfaces violations without interrupting anything. Block fails the pipeline and prevents the merge. Start new architecture rules in Monitor, work the baseline down, then flip to Block once the number is manageable.
Scope it to reality. Policy as Code lives in a .Pandorian/.policy file in the repository. Exclusions skip vendor directories, generated protobuf files, and anything else that should not be measured. Inclusions scope a guideline to a specific path, so a data-ownership rule applies to the services that own data and not to an internal tooling repo.
The rules themselves come from documentation you already have. Pandorian extracts the source material, compiles it into enforceable guidelines, scores each guideline for focus, clarity, and enforceability, and then makes it ready to enforce across the codebase. An ADR that has been sitting in Confluence since 2023 becomes a check that runs on the next pull request that tries to break it.
You do not have to start from a blank catalog either. Two architecture packages in the Pandorian Standards Hub ship with the rules already written, already scored, and already mapped to the surfaces above:
- Microservice Boundary Discipline — Seven rules for service boundaries: data ownership, published contracts, additive-only changes, saga and outbox failure paths, call cost, workload identity, and shared libraries that quietly carry business logic. Checks include ARC_10247, which flags a live connection, foreign key, or cross-schema query into another service's tables, on both PR and full scans.
- API Design Best Practices — Seven contract rules for public APIs: explicit versioning, declared response types, validated request types, honest methods and status codes, one error shape, bounded pagination and rate limits, and a spec verified against the deployed routes. Checks include ARC_67381, which flags a field removed, renamed, or reinterpreted inside an already-published version, on PR and scheduled scans.
Both are downloadable as guideline Markdown files if you want to hand them to your own agent or CI setup, or enforceable directly through Pandorian for Architecture Leaders with live PR checks and scans on your repositories.
Drift Is a Metric, Not a Feeling
Technical debt monitoring turns architectural drift from an anecdote into a number leadership can track over time.
This is the part most architecture programs skip, and it is the part that determines whether the program survives. A one-time audit produces a slide. A continuous measurement produces a trend, and a trend is what lets you tell whether the last two quarters of effort actually moved anything.
Once every architecture rule is enforced rather than documented, the reporting comes free. Violations per guideline. Violations per repository. Violations per team. The direction of that line over the last six months. Whether the boundary rule you introduced in March is being respected in the services written since.
Findings turn into work through the Jira integration, which generates a ticket containing the open violations for a given guideline in bulk, so remediation lands in the backlog instead of a dashboard nobody opens.
That is the difference between knowing your architecture has drifted and knowing by how much, where, and in which direction it is moving.
One Place to Detect, Enforce, and Govern Architectural Drift
Every failure mode above — the invisible boundary crossing, the green pipeline, the assistant copying the wrong pattern, the audit that arrives a quarter late — is a symptom of the same root cause: architecture standards that exist as text instead of as enforced logic.
- Single source of truth: Import architecture standards from ADRs, Confluence, or Markdown, or write them in plain language, once, into one governed catalog.
- Detection across the whole codebase: Full Repo Scans establish the baseline and surface drift that already exists, not just drift arriving today.
- Enforcement at the merge point: PR Scans post inline on the pull request and gate the merge through a required status check in GitHub.
- Scoped by system: Policy as Code and per-repository scoping mean a payments service and an internal tool do not have to share one generic rule set.
- Leadership visibility: Compliance posture across every repository, team, and business unit, tracked over time rather than sampled once a quarter.
See Pandorian for Architecture Leaders →
Your Architecture Isn't What You Designed. It's What You Merged.
The diagram was approved. The ADR was written. The boundaries were agreed on by people who understood the tradeoffs and made the right call.
None of that was ever the problem. The problem is that approval and enforcement were treated as one event, when the first happens once in a meeting and the second has to happen on every pull request forever.
Architectural drift is not a discipline failure. It is a detection failure. Every organization running without drift detection is not choosing to tolerate drift, it is choosing not to know about it, which is a different and more expensive decision.
Point something at the codebase that can count. Then put it in the way of the merge. The diagram stays accurate because the code stops being free to disagree with it.
Written by Amit Kochman, GTM Operations Director at Pandorian.
Book a demo with Pandorian if you want to see architectural drift detection running against your own repositories.
Top comments (0)