Drift Guard

Drift Guard turns every merge request into a lightweight architecture review, detecting structural drift before it becomes technical debt.

Comment

Inspiration

Most codebases don’t break all at once. They slowly drift.

A frontend file reaches into backend logic. Production code starts depending on test utilities. A few deep relative imports tightly couple directories.

Each change looks harmless in a pull request, so it slips through review. But over time these small decisions gradually bend the architecture of the system.

I wanted a lightweight tool that could notice those early signals of architectural drift and surface them during code review, when the team can still fix them easily.

That idea became Drift Guard.

What it does

Drift Guard watches merge requests and flags the early signs of architectural drift.

When a merge request is opened, Drift Guard scans the newly added imports in the diff and evaluates them against architectural rules defined in a repository policy file:

.drift-guard.yml

It detects patterns such as:

  • frontend code importing backend modules
  • deep relative imports that tightly couple directories
  • production code importing test utilities

If Drift Guard detects a violation, it posts a structured comment directly in the merge request, showing:

  • the file where the violation occurs
  • the exact import line
  • an explanation of the problem
  • a suggested fix

This brings architectural awareness into the pull request review process before structural issues quietly accumulate.

How we built it

Drift Guard is built using GitLab Duo Flows, which allow AI agents to automate workflows inside GitLab.

The flow works roughly like this:

  1. When triggered on a merge request, the agent retrieves the MR metadata and diffs using GitLab tools.
  2. It scans only newly added lines in the diff.
  3. Import statements are evaluated against architectural policies defined in .drift-guard.yml.
  4. If violations are detected, the agent generates a structured report and posts it as a merge request comment.

The project uses the following key components:

  • GitLab Duo Flow agents
  • GitLab tools such as get_merge_request, list_merge_request_diffs, and create_merge_request_note
  • A repository-defined policy file .drift-guard.yml
  • LLM reasoning to interpret diffs and identify architectural violations

This design keeps policy and enforcement separate:

  • .drift-guard.yml defines architectural boundaries for the repository
  • the Duo Flow acts as the enforcement engine during code review

Challenges we ran into

One challenge was understanding the capabilities of the GitLab Duo Flow tool environment.

Initially, policies were hardcoded into the system prompt because it wasn’t clear whether agents could read files from the repository.

After experimenting with the toolset, we discovered the correct way to access repository files using the read_file tool. This allowed Drift Guard to load .drift-guard.yml dynamically and make the tool configurable per repository.

Another challenge was designing a prompt that reliably analyzes diffs and produces structured, consistent reports inside merge requests.

Accomplishments that we're proud of

  • Turning GitLab Duo Flows into an architectural guardrail for pull requests
  • Creating a repository-defined architecture policy using .drift-guard.yml
  • Producing clear, developer-friendly MR comments that explain violations and fixes
  • Demonstrating how AI agents can enforce structural codebase health, not just syntax or style

Most code review tools focus on linting or formatting. Drift Guard focuses on architecture.

What we learned

This project showed how AI agents can be used to enforce higher-level engineering practices, not just code correctness.

Using GitLab Duo Flows, an agent can:

  • interpret repository structure
  • reason about architectural boundaries
  • provide actionable feedback during code review

We also learned that separating policy (configuration) from execution (flow logic) makes the tool far more flexible and reusable.

What's next for Drift Guard

There are several directions we’d like to explore next:

Richer architectural policies

Support additional rules such as:

  • restricted module dependencies
  • layer ownership
  • domain boundaries

Custom rule definitions

Allow teams to define new architectural rules directly in .drift-guard.yml.

Better visualization

Show architectural drift trends across merge requests over time.

IDE and CI integration

Surface architectural warnings earlier in the developer workflow.

Ultimately, the goal is to make Drift Guard a lightweight way for teams to protect the architecture of their codebase as it evolves.

Built With

Share this project:

Updates