TL;DR overview
- Architecture management in SonarQube Cloud identifies relationships and dependencies, illustrates project structure, and enables users to design interfaces.
- Context Augmentation extends the SonarQube MCP Server with additional tools that provide AI agents with the current and intended architectures before code generation.
- SonarQube Cloud reverse-engineers the current component hierarchy on every analysis, compares it against the intended architecture, and surfaces deviations as maintainability issues within existing workflows.
- Proactive architectural awareness reduces architectural debt by giving AI agents visibility into the intended architecture's allow-list of permitted dependencies before code is generated.
Consider the following scenario: an AI coding agent adds a feature to your project, thereby writing a service class, importing what it needs, and compiling the code without issue. Tests proceed to pass and the PR is merged, but one generated import reaches into a module that was never meant to be accessed from that layer. This raises an important concern: neither the compiler, nor the tests, nor your linter, nor code-level static analysis caught this issue, because none of these tools properly account for the project’s code-level architecture.
AI coding agents often operate at the function and file level of a given project, and in doing so generate code that satisfies the immediate request: the functionality works, the unit test passes, the type checks resolve, etc. With this in mind, agents possess a limited view of the project’s broader system and how that code sits therein, and snippets that work in isolation but deviate from architectural boundaries accumulate as architectural debt that's expensive to untangle later.
The architectural blind spot
Code-level static analysis can identify bugs, vulnerabilities, and code smells, but won’t catch a dependency that deviates from your intended architecture. This evokes an altogether different dimension of code health: form vs. function.
Without the necessary context, an agent won't consider questions such as: which modules are allowed to depend on which? Or, should one layer of the application reach directly into another, ignoring important abstractions? It may instead duplicate a utility function rather than locate the correct import path across a module boundary, or create a circular dependency if doing so resolves a compilation error. In such examples, the code may be locally correct every time but introduce crippling architectural debt. This differs from code-level issues in that it accumulates through decisions regarding where code lives and upon what it depends, not through how individual functions are implemented. The increasing use of AI coding agents compounds these effects and can accelerate architectural debt.
In the past, this erosion of a project’s architecture accumulated gradually, and by the time it became readily apparent, the architectural debt was already expensive to remediate. AI agents accelerate that timeline as the increased rate of code generation introduces further opportunities for architectural deviations that pass existing checks.
How SonarQube detects architectural drift
Architecture management in SonarQube Cloud addresses this challenge by operating on the following concepts:
Current architecture is reverse-engineered from your source code at every analysis. It produces an interactive map which depicts the actual component hierarchy and dependencies: a live view of what exists today, always up to date, with no required configuration.
Intended architecture is an allow-list wherein you specify which components you want to control, where they sit in the overall structure, authorize dependencies between them, and define their interface. The model is unambiguous by nature.
Deviations constitute the gaps between your current and intended architectures. They surface as standard SonarQube maintainability issues that count toward the project’s maintainability rating and can even fail your quality gate, requiring remediation to pass. They flow through your existing workflow: dashboards, issue lists, PR decoration, etc. in the same way that other surfaced issues do. A single architectural deviation (e.g., module A should not depend on module B) can generate numerous code-level issues: one for each import statement, method call, or type reference that creates the forbidden dependency.
From detection to prevention
Detecting deviations after the code is generated is important, but Sonar Context Augmentation adds a proactive layer by providing the current architectural model and intended architecture to AI agents before they generate code.
Through the SonarQube MCP Server, an AI coding agent can, for example, query the following architecture endpoints:
get_current_architecturereturns the actual component hierarchy and relationships.get_intended_architecturereturns the allow-list of permitted dependencies.
With both pieces of context, an agent can check whether a proposed dependency is permitted before writing it. Instead of generating an import that crosses a module boundary (and hoping that someone catches the deviation), the agent can recognize that the relationship isn't a part of the allow-list and therefore choose a different approach. The current architecture as context assists the agent by improving the accuracy of the code it generates. By providing the current and intended architectures to agents, they can produce code that is compliant with your architectural decisions.
The full list of currently available architecture tools can be found here.
What to know
- Context Augmentation provides context, not enforcement. The agent receives the current architectural model and intended architecture, but SonarQube analysis remains the verification layer. If the agent ignores the context, deviations are still caught on the next scan.
- Full architecture MCP tool support (call flow tracing, type hierarchy, signature search) is currently Java-only. C#, JavaScript, Python, and TypeScript are currently limited to
get_current_architectureandget_intended_architecture. - Context Augmentation requires a SonarQube Cloud Team or Enterprise plan and is currently in open beta.
Putting the pieces together
Define the intended architecture by creating the allow-list of permitted dependencies in the SonarQube Cloud UI and then:
- Guide AI agents with architectural context. Context Augmentation provides both the current and intended architectures to the agent through the MCP Server before code is generated.
- Generate code with architectural awareness. The agent writes code that respects the architectural boundaries it received as context.
- Verify on every analysis. SonarQube Cloud compares the actual code against the intended architecture and surfaces any deviations that slip through.
- Solve the code-level issues that arise. The current architecture model evolves incrementally as the codebase changes.
It’s important to understand that AI coding agents are productive but oftentimes architecturally unaware, and that traditional checks rarely provide the necessary context. This is where architecture management in SonarQube Cloud comes in: the current architecture map shows the actual component structure and relationships of your codebase, and the intended architecture formalizes what's allowed. Context Augmentation closes the loop by placing the architectural model in the agent's hands before code is generated, so that deviation is prevented rather than caught after the fact, and re-prompting cycles are reduced, making token consumption more predictable. This is the architectural dimension of the Agent Centric Development Cycle: architectural integrity enforced at every step, for developers and AI agents alike.
