Architect Review Agent

Your agent for reviewing code changes through an architectural lens — ensuring consistency with established patterns, identifying structural regressions, and maintaining system integrity across pull requests.

When to Use This Agent

Choose Architect Review Agent when:

• Reviewing PRs for adherence to established architectural patterns
• Detecting structural regressions (layer violations, circular dependencies, coupling)
• Evaluating whether new code follows existing conventions and principles
• Assessing the architectural impact of proposed changes
• Enforcing boundary rules between modules, layers, or services

Consider alternatives when:

• You need code-level review (naming, logic, bugs) — use a code reviewer agent
• You need to design new architecture — use an architect helper agent
• You need security-focused review — use a security engineer agent

Quick Start

Copy
# .claude/agents/architect-review.yml
name: Architect Review Agent
model: claude-sonnet
tools:
  - Read
  - Glob
  - Grep
  - Bash
description: Architecture review agent that validates code changes against established patterns and structural integrity

Example invocation:

claude "Review the changes in PR #87 for architectural consistency — check for layer violations, proper dependency direction, and adherence to our hexagonal architecture"

Core Concepts

Architecture Review Checklist

Category	What to Check	Red Flags
Layer Integrity	Dependencies flow inward only	Controller importing from infrastructure
Boundaries	Modules communicate through defined interfaces	Direct database access from UI layer
Patterns	Consistent use of established patterns	Mix of repository and direct SQL queries
Dependencies	New deps align with tech stack decisions	Adding ORM when raw SQL is the standard
Naming	Follows established conventions	Inconsistent file/class naming patterns
Coupling	Changes don't increase coupling	Service A importing internals of Service B

Dependency Direction Rules

✅ Correct Direction:
  Controller → Service → Repository → Database
  UI → Application → Domain → Infrastructure

❌ Layer Violations:
  Controller → Repository (skipping service layer)
  Domain → Infrastructure (domain depends on implementation)
  Service A → Service B internals (breaks encapsulation)

Configuration

Parameter	Description	Default
architecture_style	Expected pattern (layered, hexagonal, clean, feature-based)	auto-detect
strictness	Review strictness (advisory, standard, strict)	standard
scope	Review scope (changed-files, affected-modules, full-impact)	affected-modules
report_format	Output format (inline-comments, summary, both)	both
auto_detect_patterns	Infer architecture from codebase structure	true

Best Practices

1. Establish architecture rules before reviewing against them. Document your architectural decisions in ADRs or a ARCHITECTURE.md file. Reviewing without documented standards becomes subjective opinion, not architectural enforcement.

2. Review the dependency graph, not just individual files. A single file change may look fine in isolation but create a circular dependency or layer violation when viewed in the context of the broader module structure. Check import paths across the affected module.

3. Distinguish between intentional evolution and accidental drift. If a PR deliberately introduces a new pattern (with rationale), that's evolution. If it accidentally violates an existing pattern, that's drift. Treat them differently in review feedback.

4. Flag structural issues early, before the pattern spreads. One layer violation is easy to fix. Twenty files following the wrong pattern is a major refactor. Catch and correct structural regressions in the PR where they're introduced.

5. Provide the "why" with every architectural objection. "This violates our layered architecture" is less helpful than "This controller imports the repository directly, bypassing the service layer. This makes it harder to add cross-cutting concerns like caching or audit logging later."

Common Issues

Developers bypass architectural patterns for convenience. When the "right" way requires significantly more code than the shortcut, developers take the shortcut. Make the right way easy — provide scaffolding tools, templates, and code generators that produce architecturally-correct boilerplate.

Architecture reviews slow down the development process. If every PR needs manual architecture review, it creates a bottleneck. Automate what you can — use ArchUnit, dependency-cruiser, or ESLint rules to catch common violations automatically, reserving human review for nuanced decisions.

Legacy code doesn't follow current architectural standards. Applying new standards to old code retroactively is impractical. Establish a "campground rule" — leave code better than you found it. When modifying legacy code, incrementally align it with current patterns.