Set your intended architecture with your coding agent, skip the diagram

SonarQube Cloud now lets you define your project's intended architecture by working directly with your coding agent through the SonarQube CLI or the SonarQube MCP Server. Explore your current architecture through your agent, while it proposes components and the allowed relationships for your intended architecture that you confirm before saving. Deviations then surface as maintainability issues in your existing workflow, catching architectural drift before it compounds.

Architectural debt does not accumulate at the same rate as code-level debt. It compounds 2.8 times faster, because a single misplaced dependency or an improperly exposed component does not stay contained. It ripples through every module that touches it, making the whole system harder to change safely.

AI coding agents make this problem more urgent, not less. An AI agent can generate functioning code at a speed no human team can match, but it does so without knowing about allowable components dependencies, or which boundaries exist to keep your system modular. The result is architectural drift: code that passes tests and does what was asked, while quietly violating the structure your team relies on to keep the codebase maintainable.

Until now, fixing that gap meant building your intended architecture by hand, a process that most teams deprioritized because it competed with the time they needed to ship features. SonarQube Cloud closes that gap by putting the work where development already happens: inside a conversation with your coding agent.

What does it mean to define architecture with a coding agent?

Instead of opening a tool to document your architecture, you ask your coding agent questions about your codebase and let it do the analysis. Your agent reads the current architecture of your project directly from SonarQube Cloud through the SonarQube CLI or the SonarQube MCP Server, the same way it reads any other context about your code.

You can ask it what you would ask a teammate who already knows the system:

• What are the top-level components of this project?
• How does the billing component use the persistence component?
• Which components depend on this component?

Your agent starts with a focused view of the architecture and requests more detail on specific components as the conversation requires it, rather than loading the entire system at once.

How do you turn current architecture into intended architecture?

Exploring the current state is only half the job. You can ask your agent to help define how the project should be built going forward.

Your agent proposes components and the relationships allowed between them, based on what it understands about your codebase from SonarQube. You decide what to keep and what to leave out of your intended architecture that it suggests. Before anything is saved, you can ask your agent to preview the changes, review them with you, and confirm them together.

This matters for a practical reason: your agent works within your own SonarQube permissions. It can only change what you are authorized to change, so architectural authority stays with the people accountable for it, not with the agent itself.

Where does the intended architecture live once it's defined?

The result is stored as the intended architecture in SonarQube Cloud, structured the same way a model built through the web editor is. From that point forward, every analysis checks your code against it.

If a software developer or an agent introduces a relationship that violates the intended architecture, such as an illegal dependency between components, SonarQube Cloud raises it as a maintainability issue in the same workflow your team already uses to triage other findings. You do not need a separate architecture review process. The deviation shows up where your team is already looking.

You can keep refining the architecture with your agent or manually in the UI over time, one level of detail at a time, as the system evolves and new components are added.

Can you automate architecture setup across many projects?

For teams managing more than a handful of projects, manually repeating this process for every repository does not scale. The same capabilities used by your coding agent are available as public Web API endpoints, documented for building your own integrations.

You can read the current architecture of a project or create, read, replace, and delete its intended architecture programmatically. That makes it possible to push a standardized intended architecture to many projects from a single template, or feed architecture data into internal tooling your team already relies on.

Access follows the same governance model as the conversational workflow. Reading architecture data requires "Browse" permission on the project. Writing to it requires the "Administer architecture" permission, keeping that authority with the people responsible for setting the standard.

Get started

1. Install the SonarQube CLI and log in to SonarQube Cloud.
2. If you use Claude Code or Cursor, run Sonar architecture install-skill in your terminal. This teaches your agent how to explore the architecture through a skill and how to confirm changes with you before saving. With other agents, ask them to run Sonar architecture --help to see the available commands.
3. In your project, start a new agent session and ask "Show me the top-level architecture of this project," then "Help me define the intended architecture."

If you use the SonarQube MCP Server instead, update to the latest release with architecture support, add architecture to your existing SONARQUBE_TOOLSETS configuration, and restart the SONARQUBE MCP SERVER connection.

Architecture management with a coding agent is available now in SonarQube Cloud, with support for Java, C#, JavaScript, TypeScript, and Python.