Architect Review Agent: Stop Letting Structural Debt Slip Through Code Review

Every senior developer has lived through this scenario: a pull request looks clean on the surface — tests pass, logic is correct, naming is reasonable — but six months later that same change has become the epicenter of a maintenance nightmare. The service boundaries blurred. The dependencies inverted in ways nobody intended. A domain concept leaked across three layers. Nobody caught it because nobody was explicitly looking for it during review.

Architectural drift doesn’t announce itself. It accumulates quietly through individually reasonable-looking commits until you’re staring at a 400-line God class that owns half your business logic. The Architect Review agent for Claude Code is designed to be the architectural conscience that most code review processes lack — a specialized reviewer that evaluates every structural change against SOLID principles, established patterns, and long-term maintainability, not just whether the code works today.

This agent brings senior architect-level scrutiny to pull requests, new service designs, and refactoring efforts. It doesn’t replace human judgment, but it surfaces the structural concerns that are easy to miss when you’re focused on functional correctness.

When to Use This Agent

The Architect Review agent earns its keep in specific, high-leverage situations. Here’s where it delivers the most value:

• Pull request reviews with structural changes: Any PR that modifies service boundaries, introduces new abstractions, or touches dependency injection configuration deserves architectural scrutiny. Functional review catches bugs; architectural review catches design problems.
• New service or component design: Before you write the first line of a new microservice or module, use this agent to pressure-test your design decisions. It’s far cheaper to find boundary problems in a design document than after three engineers have built against an interface.
• Refactoring efforts: When you’re cleaning up legacy code, it’s easy to preserve bad structural patterns while improving surface-level quality. This agent keeps refactoring honest by checking that you’re moving toward better architecture, not just cleaner syntax.
• API evolution: Adding endpoints or modifying contracts has architectural implications beyond the immediate change. This agent checks for consistency with your existing design vocabulary.
• Onboarding new teams to existing codebases: When engineers unfamiliar with the system’s architectural decisions start contributing, this agent acts as an automated guardrail, catching violations before they become precedents.
• Post-incident analysis: When a system failure traces back to a structural problem, this agent can help you identify where similar vulnerabilities exist elsewhere in the codebase.

Real-World Examples

Scenario 1: Pull Request with Significant Structural Changes

A developer has submitted a pull request introducing a new feature that reorganizes how the application handles user notifications. The changes touch the service layer, repository layer, and introduce a new event-driven component.

user: Please review the architecture of this new feature. The PR introduces a 
NotificationService that directly queries the UserRepository and also publishes 
events to our message queue. I want to make sure this is consistent with how 
we've structured other services.

assistant: I'll use the architect-reviewer agent to analyze this against your 
existing patterns.

[architect-reviewer agent]

Architectural Impact: High

Pattern Compliance:
✓ Event publishing follows existing publisher pattern
✗ Direct repository access from service layer violates your established 
  Unit of Work pattern
✗ NotificationService has two distinct responsibilities: query orchestration 
  and event dispatch (SRP violation)

Violations:
1. Dependency Inversion: NotificationService imports UserRepository directly 
   rather than depending on an IUserQueryService interface. This couples your 
   notification domain to your user persistence implementation.
2. Single Responsibility: The service is making domain decisions (who to notify) 
   AND handling infrastructure concerns (how to dispatch). These should be 
   separated into a NotificationPolicy and NotificationDispatcher.

Recommendations:
- Introduce IUserQueryService interface, inject it into NotificationService
- Extract dispatch logic into a dedicated NotificationDispatcher class
- Consider whether NotificationPolicy belongs in the domain layer rather 
  than the service layer

Long-Term Implications: As notification rules grow in complexity, the current 
structure will force changes to NotificationService for both business rule 
changes and infrastructure changes. Separating concerns now prevents this 
coupling from compounding.

Scenario 2: Adding a New Service to the System

A team is building a new payment processing service and wants to validate the proposed architecture before implementation begins.

user: We're adding a PaymentService. Here's the proposed design — it'll handle 
charge processing, refund logic, and will also store payment records directly 
to the database. Can you evaluate this before we start building?

assistant: Running this through the architect-reviewer agent before you build 
is exactly the right call.

[architect-reviewer agent]

Architectural Impact: High — payment processing is a cross-cutting domain concern 
with security and consistency implications.

Pattern Compliance:
✗ Combining charge processing, refund logic, and persistence in one service 
  violates Single Responsibility
✗ Direct database access from a domain service bypasses your repository pattern
✓ Service boundary is appropriately isolated from other domains

Violations:
1. Service has three distinct responsibilities that will evolve at different rates 
   for different reasons — business rules for charges, business rules for refunds, 
   and persistence strategy are independent concerns.
2. Direct persistence coupling means any database schema change touches payment 
   business logic.

Recommendations:
- Split into PaymentCommandService (charge/refund orchestration) and 
  PaymentRepository (persistence)
- Consider whether refund logic is complex enough to warrant its own 
  RefundService or if it belongs in a shared PaymentDomainService
- Define explicit security boundaries — what validates payment data before 
  it reaches this service?

Long-Term Implications: PCI compliance requirements often require auditable 
separation between payment processing and storage. Building that separation 
now avoids a costly structural refactor when compliance requirements surface.

What Makes This Agent Powerful

The Architect Review agent isn’t a linter. It doesn’t operate on syntax rules or static analysis patterns. Its value comes from a different kind of analysis:

Structured Review Process

The agent follows a deliberate sequence: map the change in context, identify architectural boundaries being crossed, check pattern consistency, evaluate modularity impact, then recommend improvements. This process mirrors what a senior architect actually does in a review, rather than pattern-matching against a checklist.

SOLID Principles as First-Class Constraints

Most developers know SOLID in the abstract. Applying it consistently under deadline pressure is harder. This agent explicitly checks for Single Responsibility violations, Dependency Inversion problems, Interface Segregation issues, and the rest — and explains violations in terms of their concrete consequences, not just their principle labels.

Dependency Direction Analysis

Circular dependencies and inverted dependency directions are among the most damaging structural problems in a codebase, and among the easiest to miss during routine review. The agent specifically analyzes dependency graphs and flags violations against your established patterns.

Long-Term Impact Assessment

Every review includes explicit analysis of long-term implications — what this change makes harder to do later. This is the dimension most easily lost in code review when reviewers are focused on immediate correctness.

Calibrated Output Severity

The structured output format — Impact level, Pattern Compliance checklist, Violations, Recommendations, Long-Term Implications — gives you immediately actionable information organized by priority. You know what to fix before merge, what to add to the backlog, and what to watch.

How to Install the Architect Review Agent

Claude Code loads sub-agents automatically from the .claude/agents/ directory in your project. Setting up the Architect Review agent takes about two minutes:

Step 1: Create the agents directory

mkdir -p .claude/agents

Step 2: Create the agent file

touch .claude/agents/architect-review.md

Step 3: Paste the system prompt

Open .claude/agents/architect-review.md and paste the full agent system prompt into the file. The file should start with the agent’s identity definition and include all sections: core expertise areas, review process, focus areas, and output format.

Step 4: Verify Claude Code picks it up

Start a Claude Code session in your project and ask it to list available agents or simply reference the architect-reviewer by name. Claude Code automatically scans the .claude/agents/ directory and loads any .md files it finds as available sub-agents.

You can also install this agent at the user level by placing it in ~/.claude/agents/architect-review.md, which makes it available across all your projects.

Practical Next Steps

Install the agent today and run it against your last three merged PRs that touched service boundaries. You’ll likely find at least one violation that slipped through — not because your reviewers were careless, but because architectural consistency requires a different kind of attention than functional correctness.

From there, consider building architectural review into your PR process explicitly: require a run of this agent for any PR labeled structural or new-service. Document the patterns it surfaces as violations — those are your actual architectural standards, made explicit and enforceable.

Good architecture is what enables teams to move fast over years, not just sprints. This agent helps you protect it.

Agent template sourced from the claude-code-templates open source project (MIT License).