Building AI-Assisted Architecture Gates for Large .NET Repositories

Large .NET repositories become difficult to govern as they grow.

A project may start with a clean architecture, clear dependency rules, and well-defined boundaries. Over time, developers add new features, move classes between projects, introduce shared utilities, and create shortcuts to meet deadlines. Eventually, code that was supposed to stay inside one layer starts appearing somewhere else.

This is where architecture gates can help.

Traditional architecture gates use deterministic rules to detect problems such as forbidden project references, incorrect namespace dependencies, or violations of predefined boundaries. AI can add another layer by helping developers understand code relationships, identify suspicious changes, and explain architectural risks.

The important distinction is that AI should assist architectural governance, not become the source of truth.

A reliable architecture gate should use deterministic rules for enforcement and AI for analysis, explanation, and prioritization.

What Is an Architecture Gate?

An architecture gate is an automated check that evaluates whether a code change follows the architectural rules of a system.

For example, imagine a .NET solution structured like this:

src/
├── Web
├── Application
├── Domain
├── Infrastructure
└── Shared

A common dependency direction might be:

Web
 |
 v
Application
 |
 v
Domain

Infrastructure ---> Application
Infrastructure ---> Domain

The Domain project should not depend on Infrastructure.

A developer could accidentally add:

using MyApp.Infrastructure;

inside the Domain project.

The application might still compile if the project reference is added, but the architecture has changed.

An architecture gate catches this type of problem before it becomes part of the main codebase.

Why Large .NET Repositories Need Architecture Gates

As repositories grow, architecture becomes difficult to enforce through documentation alone.

Common problems include:

Domain code depending on infrastructure
Controllers containing business logic
Application services accessing database implementations directly
Shared projects becoming dependency dumping grounds
Circular dependencies
Feature code bypassing established abstractions
New APIs using inconsistent patterns
Infrastructure details leaking into domain models

Code review can catch some of these issues, but manual review does not scale indefinitely.

An automated gate provides a repeatable mechanism for checking architectural rules.

Where AI Fits Into Architecture Governance

AI can be useful when the problem is difficult to express as a simple rule.

Consider this change:

public async Task<OrderDto> CreateOrder(CreateOrderRequest request)
{
    var customer = await _dbContext.Customers
        .FirstAsync(x => x.Id == request.CustomerId);

    // Business rules...

    await _dbContext.SaveChangesAsync();

    return new OrderDto();
}

A deterministic rule might identify that a controller is directly using DbContext.

AI can go further and explain why the change is suspicious:

Database access has moved into the API layer.
Business logic may now be coupled to persistence.
Existing application services may be bypassed.
Similar operations may become harder to test.

That explanation can make the architecture rule much more useful to developers.

Deterministic Rules Should Remain the Enforcement Layer

AI is probabilistic. Architecture enforcement should be predictable.

For example, if the rule is:

Domain must not reference Infrastructure.

the CI pipeline should not ask an AI model whether the dependency is acceptable.

Use a deterministic test instead.

For example, architecture tests can express dependency rules directly:

[Fact]
public void Domain_Should_Not_Depend_On_Infrastructure()
{
    var result = Types.InAssembly(typeof(DomainMarker).Assembly)
        .Should()
        .NotHaveDependencyOn("MyApp.Infrastructure");

    result.Check();
}

The exact architecture-testing library and syntax can vary, but the principle remains the same.

The rule should produce the same result every time.

AI can then analyze the violation and provide additional context.

A Practical AI-Assisted Architecture Pipeline

A useful pipeline can look like this:

Developer Pull Request
          |
          v
Build + Unit Tests
          |
          v
Deterministic Architecture Tests
          |
          v
Static Analysis
          |
          v
AI Architecture Review
          |
          v
Pull Request Result

Each stage has a different responsibility.

Layer	Responsibility
Build	Compilation correctness
Unit Tests	Functional behavior
Architecture Tests	Enforce explicit architectural rules
Static Analysis	Code-quality patterns
AI Review	Context, explanation, risk analysis
Human Review	Final engineering decision

This separation is important because it prevents AI from becoming an uncontrolled deployment gate.

Define Architecture Rules First

Before introducing AI, document the architecture you want to protect.

For example:

Web
 └── can depend on Application

Application
 └── can depend on Domain

Infrastructure
 ├── can depend on Application
 └── can depend on Domain

Domain
 └── must not depend on Web or Infrastructure

You can represent these rules in a simple configuration document:

{
  "rules": [
    {
      "name": "DomainIsolation",
      "from": "MyApp.Domain",
      "forbidden": [
        "MyApp.Infrastructure",
        "MyApp.Web"
      ]
    },
    {
      "name": "ApplicationBoundary",
      "from": "MyApp.Application",
      "forbidden": [
        "MyApp.Web"
      ]
    }
  ]
}

The configuration itself does not enforce anything. It provides a machine-readable representation that can be consumed by architecture tooling.

Detect Project-Level Violations

For many .NET repositories, project references are the easiest place to begin.

You can inspect project dependencies with the .NET CLI:

dotnet list MyApp.sln package

For project-to-project relationships, inspecting the .csproj files or generating a dependency graph can provide more useful information.

For example:

<ItemGroup>
    <ProjectReference Include="..\Infrastructure\Infrastructure.csproj" />
</ItemGroup>

If this appears in the Domain project, a deterministic architecture test should be able to reject it.

This type of rule is ideal for automation because there is little ambiguity.

Detect Namespace and Code-Level Violations

Project references are only part of the problem.

A developer might introduce unwanted dependencies through namespaces:

using MyApp.Infrastructure.Persistence;

Architecture analysis can inspect source files and identify references that cross prohibited boundaries.

For example, a simplified rule might look for:

Domain
  -> Infrastructure

and classify it as a violation.

For large repositories, the analyzer should preferably work from a parsed syntax tree or compiler model rather than relying only on string matching.

Add AI for Architectural Context

Once deterministic checks have identified changed files and dependencies, AI can analyze the relevant context.

A useful AI review input might contain:

Repository architecture:
- Domain must remain independent.
- Application contains use cases.
- Infrastructure implements persistence.
- Web exposes HTTP endpoints.

Changed files:
- OrdersController.cs
- OrderService.cs
- OrderRepository.cs

Detected dependency:
Web -> Infrastructure.Persistence

Architecture rule:
Web should depend on Application, not Infrastructure.

The model can then produce a concise explanation:

Potential architectural violation:

OrdersController now depends directly on Infrastructure.Persistence.
This bypasses the Application layer and couples the API layer to
a persistence implementation.

Recommended review:
Move the operation behind an Application service or abstraction.

The AI is not deciding whether the rule exists. The deterministic system already established that.

The AI is explaining the consequence.

Use AI to Prioritize Findings

Large repositories can produce many static-analysis findings.

Not every finding deserves the same level of attention.

AI can help classify findings into categories such as:

Classification	Meaning
Critical	Architectural boundary may be broken
High	Significant coupling introduced
Medium	Potential design inconsistency
Low	Style or maintainability concern
Informational	Useful context without immediate action

This can make a large pull request easier to review.

However, the classification should remain advisory unless the organization has validated the workflow extensively.

Review Only Relevant Code

Sending an entire large repository to an AI model for every pull request is usually unnecessary.

Instead, build a focused context window.

A practical process is:

Identify changed files.
Determine affected projects.
Detect changed dependencies.
Retrieve relevant architecture rules.
Identify related interfaces or base classes.
Send only relevant context for AI analysis.

For example:

Pull Request
     |
     v
Changed Files
     |
     v
Dependency Analysis
     |
     v
Affected Architecture Boundaries
     |
     v
Relevant Source Context
     |
     v
AI Review

This keeps the analysis focused and easier to audit.

Create an Architecture Review Report

Instead of returning a generic AI comment, produce a structured result.

For example:

{
  "status": "review",
  "findings": [
    {
      "rule": "DomainIsolation",
      "severity": "high",
      "file": "Order.cs",
      "message": "Domain code references Infrastructure.Persistence.",
      "deterministic": true,
      "ai_explanation": "The dependency couples the domain model to a persistence implementation."
    }
  ]
}

The important field here is deterministic.

It makes clear which part of the result came from a hard architecture rule and which part came from AI interpretation.

Add Architecture Gates to CI

A CI pipeline should run architecture checks before merging.

A simplified workflow might look like:

steps:
  - name: Restore
    run: dotnet restore

  - name: Build
    run: dotnet build --no-restore

  - name: Unit Tests
    run: dotnet test --no-build

  - name: Architecture Tests
    run: dotnet test tests/ArchitectureTests

  - name: AI Architecture Review
    run: dotnet run --project tools/ArchitectureReview

The deterministic architecture tests should be capable of failing the build.

The AI review can initially operate in advisory mode.

Once the organization has confidence in the workflow, carefully selected AI findings may be incorporated into additional review policies.

Avoid AI-Only Architecture Gates

An AI-only gate might look attractive:

Pull Request
     |
     v
AI
     |
     v
Approve / Reject

This is difficult to govern.

The same code could potentially receive different evaluations because model output is probabilistic.

Instead, prefer:

Pull Request
     |
     +----> Deterministic Rules ----> Pass/Fail
     |
     +----> AI Analysis ------------> Explanation/Review

This architecture gives the organization a stable enforcement mechanism while still benefiting from AI-assisted reasoning.

Common Mistakes

Treating AI as the Architecture Authority

Architecture rules should be explicitly defined by the engineering organization.

AI can interpret and explain them, but it should not silently redefine them.

Sending the Entire Repository to the Model

Large repositories contain enormous amounts of irrelevant information.

Analyze the changed code and the architectural context affected by the change.

Blocking Every AI Finding

An AI-generated warning should not automatically fail CI.

Start with advisory feedback and measure whether the findings are useful.

Ignoring False Positives

Any automated review system will produce incorrect findings.

Create a feedback process that lets developers identify false positives and improve the deterministic rules and AI prompts.

Having Rules Without Ownership

Every important architecture rule should have an owner or responsible engineering group.

Otherwise, rules become outdated as the system evolves.

Troubleshooting Architecture Gate Failures

The Rule Is Triggering on Valid Code

Check whether the architecture rule is too broad.

For example, a shared abstraction may legitimately be referenced by multiple layers.

Instead of weakening the entire rule, consider creating an explicit exception.

AI Says the Code Is Wrong but the Architecture Test Passes

Treat this as an advisory finding.

Review the change manually and determine whether a new deterministic rule is required.

This can be a useful signal that your architecture definition is incomplete.

CI Takes Too Long

Reduce the AI context and run analysis only for changed projects or affected architecture boundaries.

Avoid reanalyzing the entire repository for every small change unless there is a specific reason.

Developers Ignore the Findings

The output may be too verbose.

Architecture feedback should explain:

What changed
Which rule is affected
Why it matters
What should be reviewed

Avoid generating large blocks of generic architectural advice.

Best Practices

Define architecture explicitly. AI cannot reliably enforce rules that the organization has never clearly defined.
Use deterministic checks for enforcement. Project dependencies, namespaces, and known architectural boundaries are excellent candidates.
Use AI for explanation and context. Let it help developers understand why a change may be problematic.
Start with advisory AI reviews. Measure usefulness before making AI findings blocking.
Analyze changed code first. Avoid unnecessary repository-wide analysis.
Keep an audit trail. Store the architecture rule, detected violation, and AI explanation separately.
Create explicit exceptions. Not every dependency that looks unusual is incorrect.
Review rules periodically. Architecture evolves with the system.
Keep humans in the loop. Architecture decisions often require business and technical context that automated tools cannot fully understand.
Separate enforcement from interpretation. This is the most important design principle for an AI-assisted architecture gate.

Frequently Asked Questions

Can AI replace architecture testing?

No. AI can complement architecture testing, but deterministic rules are better suited to enforcing known dependency boundaries.

Should AI architecture reviews block pull requests?

Not initially. A safer approach is to begin with advisory findings, measure accuracy, address false positives, and introduce blocking policies only where the organization has sufficient confidence.

What should be checked deterministically?

Good candidates include project references, forbidden dependencies, namespace relationships, circular dependencies, and other rules that can be expressed precisely.

What should AI analyze?

AI is particularly useful for explaining architectural implications, summarizing complex dependency changes, identifying suspicious patterns, and providing contextual recommendations.

Does this approach work for large monorepos?

Yes, but the analysis should be scoped carefully. Changed projects, dependency graphs, and affected architecture boundaries can be used to reduce unnecessary analysis.

Conclusion

AI can make architecture governance more useful, but it should not replace deterministic engineering controls. The strongest approach is to combine the two.

Use architecture tests and static analysis to enforce rules that can be expressed precisely. Then use AI to explain violations, connect changes to architectural intent, prioritize findings, and help developers understand the consequences of their decisions.

For large .NET repositories, this creates a practical architecture gate that is both predictable and developer-friendly. The system knows exactly which rules must never be broken, while AI helps developers understand the reasoning behind those rules and identify architectural risks that deserve human review.