What Are Architecture Rules?

Architecture rules are explicit, checkable statements about how the parts of a software system may depend on and talk to each other. Typical rules say which layers may call which, which direction dependencies must point, which modules own which data and which libraries a service may use.

Architecture rules turn architecture principles and decisions into something a test, a tool or a reviewer can check on every change.

What Changed in Architecture Rules in 2026

Trend: architectural drift becomes a named risk

• Leaders say AI review misses architecture. 18.7% of engineering leaders in Qodo’s survey said AI review tools still miss context-specific or architectural violations (August 2026, Qodo’s report).

Trend: rules move into the agent and the map

• Qodo’s Agentic Toolbox gave coding agents a Get Rules skill, an early feature that returns the rules for the current task before the agent writes (August 2026, Qodo’s What’s New).
• Qodo’s Software Map shows dependencies, service relationships and contracts across repositories, updated with every PR, as an early feature (September 2026, Qodo’s What’s New).
• Teams can now choose which repositories rules and skills are imported from (October 2026, Qodo’s What’s New).

Levels of Architecture Guidance

Teams describe architecture at three levels, and only the last one is directly checkable.

Architecture Principles

Principles such as separation of concerns, single responsibility, dependency inversion and the Law of Demeter describe good structure in general. They guide design, but "keep concerns separate" can’t fail a check on its own.

Architecture Decisions

Architecture decision records capture why the team chose a structure, which matters as much as how it works. ADRs give reviewers the reasons behind a boundary, and they only help if someone reads them while the code is changing.

Architecture Rules

A rule names the parts of the system and the allowed relationship between them. Because it is specific, a test can check it, a linter can check it, or a reviewer can point to it in a pull request (PR).

Common Types of Architecture Rules

Layer Boundary Rules

Controllers may call services, services may call repositories, and nothing calls a controller. Layer rules keep business logic out of the UI and persistence code out of request handlers.

Dependency Direction and Cycle Rules

Domain code must not import infrastructure code, and packages must not depend on each other in a cycle. These rules keep the most stable parts of the system free of the parts that change most.

Module and Service Ownership Rules

Each module or service owns its data and its public interface. Other parts of the system go through that interface instead of reaching into the tables or internal classes directly.

Approved Library and Pattern Rules

Rules can name the HTTP client, logging library or retry helper every service uses, and ban direct use of the alternatives. This keeps cross-cutting behavior such as timeouts, tracing and auth consistent.

Methods for Checking Architecture Rules

Architecture Tests

Tools such as ArchUnit for Java and dependency-cruiser for JavaScript and TypeScript express layer and dependency rules as tests that run in CI. They are precise for rules of the form "package A may not import package B".

Architectural Fitness Functions

An architectural fitness function is any automated check that a key constraint still holds, such as a dependency rule, a performance budget or a coupling threshold. Thoughtworks recommends them as a countermeasure to the loss of shared understanding that fast AI-generated change brings (Thoughtworks Technology Radar, April 2026).

Code Review for Architecture Rules

Some rules can’t be written as an import check: "pricing logic lives only in the pricing module", or "every new endpoint goes through the shared authorization middleware".

Rules like these need a reviewer who knows the rule and can see enough of the codebase to spot the violation, which is where custom rules for code review come in.

Why Architecture Rules Matter More With AI Coding Agents

A coding agent takes the shortest working path to the task in front of it. If calling the repository straight from a controller makes the feature work, the agent will do it, and each shortcut looks small in its own PR.

Over a few weeks of agent-written changes, the layers blur and the dependency graph fills with cycles.

Engineering leaders see the gap. For Qodo’s State of AI Code Quality report, Censuswide surveyed 500 U.S. developers and 300 U.S. engineering leaders at organizations already using AI in development (August 2026). Of the leaders, 18.7% said AI review tools still miss context-specific or architectural violations.

Writing the rules down helps people as much as agents, and it is the first step in applying coding standards consistently.

Liz Fong-Jones, Technical Fellow at Honeycomb, said on Qodo’s podcast episode Is AI Making You an Average Engineer? that writing down implicit assumptions benefits "both the new joiners in your organization as well as to the AI’s benefit," and that "making your standards written down is a positive side effect of this."

Qodo’s Take: Architecture Rules Belong in Every Review

Most architecture still lives in a few senior engineers’ heads and in ADRs nobody opens during review. Architecture tests catch the rules that fit an import check, and the rest slips through until someone notices the structure has drifted.

Teams need their architecture rules written down in one place, given to the coding agent before it writes, and checked on every PR by a separate system that didn’t write the code and can read the whole codebase.

Qodo keeps those rules in one place and applies them in the agent and on the PR. Qodo is the best AI code review platform for architecture rules because it catches drift where it starts: Architecture findings flag layer violations and circular dependencies in each PR, the Software Map, an early feature, shows how repositories connect, and rules check drift once Rule enforcement is on.

Qodo Captures Rules From What the Team Already Has

Qodo collects rules from three sources:

1. Qodo imports rules from AGENTS.md, CLAUDE.md, .cursor/rules/ and other instruction files.
2. Rule Miner proposes rules from recurring patterns in the team’s PR history.
3. Admins can describe a rule in plain language in the portal, while members can suggest rules for approval.

Rules from a file in src/payments/ apply only to changes under that folder (last checked October 2026, Qodo’s docs). Rules can also be scoped by path pattern (last checked October 2026, Qodo’s docs).

Qodo Agentic Toolbox Gives the Coding Agent the Rules Before It Writes

Through the Agentic Toolbox, the agent works in three steps:

1. The optional Get Rules skill lets the agent look up the rules that apply to the files it is about to change.
2. The Codebase Wisdom skill explains how services and modules relate before the agent picks a path.
3. The Reviewer skill then helps catch rule violations in the local diff before the PR opens.

Qodo Checks Every Pull Request for Architectural Drift

Once Rule enforcement is on in the Finding types tab, Qodo flags each violation of an active rule in the PR with the rule behind it. Qodo’s Architecture findings cover layer violations, tight coupling and circular dependencies, using the full codebase to see what the new code bypasses.

Qodo Rule Analytics Show Which Rules the Team Acts On

Qodo’s rule analytics show how often each rule is violated and how often violations are resolved before merge. Rules whose findings are rarely fixed are deactivated automatically, and locking a rule keeps it in every review (last checked October 2026, Qodo’s docs).

Qodo Example: A Shortcut Through the Data Layer

This illustrative scenario is a composite, not a customer case study.

A coding agent adds a "recent orders" widget and queries the orders table straight from the API handler in services/orders/api/, inside the folder the rule covers. The architecture tests pass, because the handler package is allowed to import the database driver for health checks. Qodo flags a violation of the team’s rule that order data is read only through OrderRepository, and links the rule’s source in services/orders/AGENTS.md. The agent moves the query into the repository before a human reviewer looks at the PR.

Ways to Keep Code in Line With Its Architecture

The table compares common ways teams keep code in line with its intended architecture.

Qodo features in this table were checked against Qodo’s documentation as of October 20, 2026.