DEV Community: Vincent Composieux

Architecture Drift Detection: Keep Your Code Aligned with Design

Vincent Composieux — Mon, 08 Jun 2026 20:35:33 +0000

Somewhere in your organization, there's an architecture diagram that's wrong. Maybe it shows a microservice that was merged into another six months ago. Maybe it lists Redis as the caching layer when the team switched to Memcached during a production incident. Maybe it describes a clean hexagonal architecture in a service that's accumulated enough shortcuts and workarounds to look like spaghetti.

This is architecture drift: the gradual, silent divergence between how your system is documented and how it actually works. Unlike bugs, drift doesn't trigger alerts. Unlike performance regressions, it doesn't show up in monitoring. It sits quietly until someone makes a decision based on outdated documentation -- and that decision turns out to be wrong.

Architecture drift is universal. Every team experiences it. The question isn't whether your documentation will drift, but how quickly you'll detect it and what you'll do about it.

What is Architecture Drift?

Architecture drift occurs when the actual implementation of a software system diverges from its documented or intended architecture. The term was coined in the academic software engineering community, but the concept is painfully familiar to any practicing engineer.

Drift manifests at every level of architectural documentation:

Structural Drift

The documented structure no longer matches the codebase:

A service documented as a standalone container was absorbed into a monolith
A component was renamed but the diagram still shows the old name
A new service was created but never added to the architecture model
A database was migrated from MySQL to PostgreSQL but the container diagram still says MySQL

Behavioral Drift

The documented behavior no longer matches reality:

A synchronous API call was replaced with an async message, but the relationship still says "REST/HTTP"
A data flow was changed to go through an API gateway, but the diagram shows direct service-to-service communication
An authentication step was added that isn't reflected in the system context diagram

Dependency Drift

The documented dependencies no longer match actual integrations:

A third-party API was replaced with an in-house solution
A new external dependency was added (payment provider, monitoring service) but not documented
An integration was decommissioned but still appears in the system context diagram

Decision Drift

The documented architectural decisions are no longer being followed:

An ADR says "use PostgreSQL for all persistent storage" but a team started using MongoDB
The conformance rules say "no direct database access from the frontend" but someone added a client-side Supabase integration
The deployment architecture says "single region" but services were deployed to multiple regions

Why Architecture Drift Happens

Understanding the causes of drift is essential to preventing it. Drift isn't usually malicious or even negligent -- it's a natural consequence of how software is developed.

Speed Over Documentation

When shipping a feature by Friday, updating the architecture diagram is the first thing that gets dropped. The code change is the deliverable. The documentation update is overhead. This is rational behavior in the short term and devastating in the long term.

Many Small Changes

Drift rarely happens in one dramatic moment. It accumulates through hundreds of small changes, each too minor to warrant a documentation update:

Renaming a file
Adding a utility package
Switching a library dependency
Extracting a function into a separate module

No single change is significant enough to trigger a documentation update. Together, they transform the architecture.

Team Turnover

When engineers leave, they take implicit knowledge with them. The new team inherits the codebase but not the understanding of why it's structured the way it is. They make changes based on what they see in the code, not what the documentation says, widening the drift.

Lack of Feedback Loops

If nobody checks whether documentation matches reality, drift is invisible. Without a detection mechanism, the only way to discover drift is during an incident, an audit, or when a new engineer points out that the diagram doesn't match the code. By then, the drift may be extensive.

Emergency Changes

Production incidents often require architectural shortcuts: a direct database connection instead of going through the API layer, a hardcoded configuration instead of using the config service, a temporary cache that becomes permanent. These changes bypass normal review processes and are rarely documented.

The Cost of Architecture Drift

Drift isn't just an aesthetic problem. It has concrete, measurable costs.

Bad Decisions

When architects make decisions based on outdated documentation, those decisions can be wrong. "This service has low traffic, so we can afford a synchronous dependency" -- except the documentation is stale and the service actually handles 10x the documented load.

Slow Onboarding

New engineers rely on architecture documentation to build their mental model. If the documentation is wrong, they build wrong mental models. They write code that doesn't fit the actual architecture. They ask questions that reveal their confusion, consuming senior engineers' time.

Incident Response

During a production incident, architecture diagrams should help teams understand blast radius and dependencies. If those diagrams are wrong, teams waste precious minutes tracing the wrong dependency chains or missing critical upstream systems.

Compliance and Audit Failures

In regulated industries, architecture documentation is often required for compliance (SOC 2, ISO 27001, HIPAA). If auditors find that documentation doesn't match reality, it's a finding -- potentially a serious one.

AI Agent Confusion

As AI coding agents become more prevalent, they increasingly rely on architecture documentation for context. An agent that reads a stale C4 model will generate code that fits the documented architecture, not the actual one. This amplifies drift rather than fixing it.

How to Detect Architecture Drift

Manual Review (Traditional Approach)

The simplest approach is periodic manual review: gather the team, walk through the architecture diagrams, and check whether they still match reality.

When this works: Small teams, simple architectures, quarterly cadence.

When this fails: Large systems, fast-moving teams, or when the people who know the code best don't have time for review meetings. Manual review also suffers from confirmation bias -- people tend to see what they expect to see.

Architecture Fitness Functions

Fitness functions, popularized by Neal Ford and the "Building Evolutionary Architectures" book, are automated tests that validate architectural properties:

// Example: Ensure no direct database imports in handler packages
func TestNoDatabaseImportsInHandlers(t *testing.T) {
    packages := analyzeImports("./internal/handler/...")
    for _, pkg := range packages {
        for _, imp := range pkg.Imports {
            assert.NotContains(t, imp, "database/sql",
                "Handler %s imports database/sql directly", pkg.Name)
            assert.NotContains(t, imp, "gorm.io",
                "Handler %s imports GORM directly", pkg.Name)
        }
    }
}

Fitness functions are powerful for enforcing specific rules, but they require upfront effort to write and maintain. They check constraints, not the full model.

Static Analysis Tools

Tools like ArchUnit (Java), Deptrac (PHP), and go-arch-lint (Go) analyze code structure and enforce dependency rules:

// go-arch-lint configuration
components:
  handler:
    in: ./internal/handler/
  service:
    in: ./internal/service/
  repository:
    in: ./internal/repository/

rules:
  handler:
    can_depend_on: [service]
  service:
    can_depend_on: [repository]
  repository:
    can_depend_on: []

These tools are excellent for enforcing layered architecture within a single codebase. They don't address cross-service drift or validate that the architecture model matches the code.

Automated Drift Scoring

This is the approach Archyl takes. Instead of checking specific rules, it validates the entire architecture model against the codebase:

Does each documented system match a repository?
Does each documented container match a directory in the codebase?
Does each documented code element reference a file that still exists?
Are both endpoints of each documented relationship still valid?

The result is a drift score (0-100) and a detailed breakdown showing exactly what drifted. This is the most comprehensive approach because it validates the full model, not just specific constraints.

The key design decisions in Archyl's drift detection:

Lightweight. No AI tokens consumed, no file content read. Just file path existence checks against the Git provider API. This means drift scoring takes seconds, not minutes.

Deterministic. Same codebase, same model, same score. No variability from LLM temperature or prompt engineering.

Cheap. Run it on every push without cost concerns. A hundred computations a day is fine.

Actionable. The breakdown shows exactly which elements drifted, so you know what to fix.

How to Prevent Architecture Drift

Detection is necessary but not sufficient. The goal is to prevent drift from accumulating in the first place.

Make Documentation Updates Part of the Definition of Done

If a code change modifies the architecture, the PR should include a documentation update. Add a checkbox to your PR template:

## Checklist
- [ ] Tests pass
- [ ] Code reviewed
- [ ] Architecture documentation updated (if applicable)

This doesn't catch everything, but it establishes the expectation that documentation is a first-class deliverable.

Automate Drift Detection in CI

The single most effective prevention mechanism is a CI gate that fails when drift exceeds a threshold:

on:
  push:
    branches: [main]

jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: archyl-com/actions/drift-score@v1
        with:
          api-key: ${{ secrets.ARCHYL_API_KEY }}
          organization-id: ${{ secrets.ARCHYL_ORG_ID }}
          project-id: 'your-project-uuid'
          threshold: '70'

When the build fails because the drift score dropped, someone has to fix it before merging. Documentation accuracy becomes as non-negotiable as passing tests.

Start with a low threshold (50-60%) and increase it gradually as the team builds the habit.

Use Architecture-as-Code

When your architecture model is defined in a text-based format (Structurizr DSL, Archyl YAML), it can be version-controlled alongside your code. This means:

Architecture changes appear in pull requests
Changes are reviewed by the team
The history of architectural evolution is captured in Git

This is significantly better than architecture defined in a GUI tool where changes are invisible and un-reviewable.

Set Up Drift Alerts

Archyl supports webhook alerts for drift events:

drift.score_computed: Fires on every drift computation. Post to a Slack channel for visibility.
drift.score_degraded: Fires when the score drops by 10+ points. This is your early warning system.

Configure these alerts to a channel your team monitors. Awareness is the first step toward action.

Run Architecture Reviews

Monthly or quarterly architecture reviews serve multiple purposes:

Validate that the documented architecture still matches reality
Identify drift that automated tools missed (behavioral drift, for example)
Discuss whether drifted components should be updated in code or in documentation
Review and update ADRs for decisions that may need revisiting

Adopt Conformance Rules

Conformance rules define architectural constraints that should always be true:

"The frontend container must not depend on the database container"
"All public APIs must go through the API gateway"
"Each service must own its own database (no shared databases)"

In Archyl, conformance rules are defined in the platform and enforced via the conformance check feature. AI agents can read these rules via MCP and respect them when generating code.

Conformance rules are complementary to drift detection. Drift detection checks whether your model matches reality. Conformance checks whether reality follows your rules.

Architecture Drift vs. Architecture Erosion

These terms are related but distinct:

Architecture drift is divergence between documentation and implementation. The code might be perfectly fine -- the documentation is just wrong.

Architecture erosion is degradation of the architecture itself. The code violates architectural principles, accumulates tech debt, and becomes harder to maintain. Erosion is a code quality problem. Drift is a documentation accuracy problem.

They often co-occur. When documentation drifts, teams lose awareness of the intended architecture. Without that awareness, they make changes that erode the architecture. Drift enables erosion.

This is why drift detection matters beyond just documentation accuracy. Accurate documentation serves as a reference that prevents erosion. When everyone can see the intended architecture, they're more likely to maintain it.

Measuring and Tracking Drift Over Time

A single drift score is useful. A trend is powerful.

Establish a Baseline

Run your first drift computation to establish where you stand. Don't panic if the score is low -- most teams that haven't been actively maintaining architecture documentation will see scores between 40-70%.

Set Targets

Establish realistic targets for improvement:

Month 1: Improve from baseline to 60% by fixing the most obvious drift
Month 3: Reach 75% by incorporating documentation updates into the workflow
Month 6: Maintain 80%+ through CI gates and regular reviews

Track the Trend

Archyl stores every drift computation with its full breakdown. The drift history view shows a timeline of scores, so you can see:

Is drift getting better or worse over time?
Did a specific sprint or release cause a significant drop?
Is the CI threshold preventing degradation?

Celebrate Improvements

When the team improves the drift score, acknowledge it. Architecture documentation is thankless work. Making progress visible and recognized reinforces the behavior.

The Role of Drift Detection in AI-Assisted Development

The rise of AI coding agents makes drift detection more important than ever.

AI agents increasingly rely on architecture documentation for context. Through protocols like MCP, agents can read your C4 model, ADRs, and conformance rules before generating code. This makes them more effective -- they generate code that fits your architecture instead of guessing.

But this only works if the documentation is accurate. An agent that reads a stale C4 model and generates code based on it will produce code that fits the wrong architecture. The agent amplifies drift instead of preventing it.

Drift detection creates the feedback loop that keeps AI agents honest:

Agent reads architecture via MCP
Agent generates code that fits the documented architecture
Code is merged, potentially changing the actual architecture
Drift detection runs and catches any divergence
CI gate fails if drift exceeds threshold
Team updates documentation to reflect reality
Agent reads updated architecture -- loop closes

Without step 4, the loop is open. Documentation becomes increasingly fictional. Agents increasingly generate code that fits a fantasy architecture. The gap widens with every commit.

Drift detection is the mechanism that closes this loop.

Getting Started With Drift Detection

If You Have No Architecture Documentation

Start with AI discovery. Connect your repository to Archyl, run discovery, and review the generated C4 model. This gives you a baseline model that's roughly 70-80% accurate. Then set up drift detection to maintain that accuracy.

If You Have Existing Documentation

Import or recreate your architecture model in a tool that supports drift detection. Run the first drift computation. The score will tell you exactly how accurate your current documentation is -- and the breakdown will show you what to fix first.

If You're Already Tracking Drift

Integrate drift detection into CI. Set a threshold. Configure alerts. Start tracking trends. Make drift a team metric, not a one-time audit.

Regardless of Where You Start

The most important thing is to start. Architecture drift is like tech debt -- it compounds over time. The longer you wait to address it, the more work it takes to catch up. But unlike tech debt, drift detection can be set up in minutes and provides immediate value.

Your architecture documentation is either reflecting reality or it isn't. Now you can measure which one it is.

Learn more about maintaining architecture documentation: Architecture Drift Score: How It Works | What is the C4 Model? | AI-Powered Architecture Documentation. Or try Archyl free and compute your first drift score in minutes.

Originally published on the Archyl blog.

MCP Server: Talk to Your Architecture from Your Favorite AI Tools

Vincent Composieux — Tue, 27 Jan 2026 15:09:41 +0000

I've been using AI coding assistants daily for over a year now.

Claude Code for complex refactoring, Cursor for quick edits, GitHub Copilot for autocomplete. But there was always a frustrating gap: these tools couldn't see my architecture documentation.

Every time I asked Claude to "add a new endpoint to the payment service," it would guess. It didn't know that our payment service talks to Stripe, uses Redis for caching, and has specific security requirements documented in our ADRs. I'd spend more time correcting the AI than writing code myself.

Today, we're closing that gap. Archyl now exposes a full MCP (Model Context Protocol) server with 56 tools that give AI assistants complete visibility into your architecture.

What is MCP?

Model Context Protocol is Anthropic's open standard for connecting AI assistants to external tools and data sources. Think of it as a universal adapter between LLMs and the systems they need to interact with.

Instead of copy-pasting context into prompts, MCP lets AI assistants directly query your tools. They can read data, take actions, and stay synchronized with your actual systems.

And Archyl's MCP server means your architecture documentation becomes a first-class data source for any AI assistant.

What Can You Do With It?

Here's where it gets exciting. With the Archyl MCP server, your AI assistant can:

Query Your Architecture

Ask natural questions and get real answers:

"Which elements are linked to the Payment Processor system?"
"What containers does the User Service depend on?"
"Show me all systems that interact with our PostgreSQL database"
"What ADRs affect the authentication flow?"
The AI doesn't guess. It queries your actual documented architecture and returns precise, structured information.

Claude Code querying architecture via MCP

Navigate the C4 Model

Your AI understands the full hierarchy:

List all projects in your organization

Drill down from systems to containers to components
Explore relationships and dependencies
Understand the technology stack at each level
When you ask "what technologies does the Order Service use?", the AI returns the actual documented stack, not a hallucinated guess.

Modify Documentation

This is the killer feature. The MCP server supports write operations:

Create new systems, containers, and components

Add relationships between elements
Create and update ADRs
Write project documentation
Define user flows
Ask Claude to "document the new notification service we just built" and it can create the C4 elements, link them to existing systems, and even draft an ADR explaining the design decision.

Stay in Sync

The AI always sees the latest state. No stale context, no outdated documentation. When your teammate updates the architecture, your AI assistant sees it immediately.

56 Tools, One Integration
We didn't build a minimal proof-of-concept. The MCP server exposes comprehensive functionality:

Projects & Settings: List, get, and manage projects. Configure AI providers and discovery settings.

C4 Model (All 4 Levels): Full CRUD for systems, containers, components, and code elements. Create relationships, manage overlays, handle the complete model hierarchy.

Documentation: Create and update architecture documentation. Link docs to specific C4 elements.

ADRs: Full Architecture Decision Record management. Create, update, list, and link ADRs to the elements they affect.

User Flows: Define and visualize user journeys through your system.

Discovery: Trigger AI-powered architecture discovery on your connected repositories.

Teams: Query team structure and project access.

Every tool returns structured data that AI assistants can reason about. No parsing HTML, no scraping UIs, no brittle integrations.

Getting Started in 2 Minutes

Here's how to connect Claude Code (or any MCP-compatible tool):

Step 1: Create an API Key

Go to your Archyl profile, click on "API Keys", and create a new key. Give it a descriptive name like "Claude Code" and select the scopes you need (read-only or full access).

Copy the key immediately — you won't see it again.

Step 2: Configure Your MCP Client

Add Archyl to your MCP configuration. For Claude Code, add this to your settings:

{ "mcpServers": { "archyl": { "url": "https://api.archyl.com/mcp", "transport": "http", "headers": { "X-API-Key": "your_api_key_here" } } } }

Step 3: Start Talking to Your Architecture

That's it. Ask your AI assistant about your architecture and watch it fetch real data from Archyl.

Try these prompts:

"List all my Archyl projects"
"What systems exist in the E-commerce Platform project?"
"Show me the relationships for the Payment Gateway"
"Create a new ADR explaining why we chose PostgreSQL"
Why This Matters
Architecture documentation has always had a discoverability problem. You write it, it lives in a wiki or a diagram somewhere, and then nobody reads it. Engineers ask questions in Slack instead of checking the docs.

MCP changes the interaction model. Documentation isn't something you go read — it's something your AI assistant knows. When you ask "how does payment processing work?", the answer comes from your actual architecture, not the AI's training data.

This has profound implications:

Onboarding becomes instant. New engineers ask their AI about system architecture and get accurate answers from day one.

Context is always available. When writing code, the AI knows exactly what services exist, how they connect, and what decisions shaped them.

Documentation stays current. Because it's actively used, inaccuracies get noticed and fixed. Dead documentation is documentation nobody reads.

AI suggestions are grounded. When Claude suggests a design, it's informed by your actual architecture, not generic patterns.

The Bigger Picture

We're entering an era where AI assistants are genuine collaborators in software development. But they're only as good as the context they have access to.

Most AI interactions today are context-poor. You paste some code, add a brief description, and hope the AI figures out the rest. The results are mediocre because the AI is working blind.

MCP-powered integrations flip this model. Your AI has persistent, queryable access to everything it needs: your code (via repository integration), your architecture (via Archyl), your issues (via Jira/Linear integrations), your documentation (via Notion/Confluence integrations).

The AI becomes a true team member with access to team knowledge.

Archyl's MCP server is our contribution to this vision. Your architecture shouldn't be locked in a diagram tool. It should be accessible to every tool your team uses, including your AI assistants.

What's Next

This is version 1. Here's what we're building next:

Proactive suggestions: The MCP server could watch for architecture changes and suggest documentation updates.

Cross-reference linking: Connect ADRs to specific commits, link documentation to CI/CD events, create a web of interconnected knowledge.

Custom queries: Define organization-specific queries like "show me all services owned by the payments team."

Audit logging: Track every MCP interaction for compliance and debugging.

Try It Now

The MCP server is available today on all Archyl plans. If you're already using Claude Code, Cursor, or another MCP-compatible tool, you can connect in minutes.

Create an API key, add the configuration, and start talking to your architecture.

And if you're not using Archyl yet, sign up for free and see how AI-powered architecture documentation works. Connect a repository, run discovery, and then connect your favorite AI assistant.

Your architecture is too important to be locked in static diagrams. Let your AI assistants explore it.

Want to learn more about Archyl's AI capabilities? Check out our post on AI-Powered Architecture Discovery, or start with the basics in our Introduction to the C4 Model.