Skip to main content
Agent skill

Code Review Architecture

Architecture code review lens for assessing design quality, coupling, cohesion, and structural integrity.

Get started

Get the complete skill folder, including its scripts and reference files.

When to use this skill

Use Code Review Architecture when an AI agent needs a reusable SKILL.md workflow for this job: Architecture code review lens for assessing design quality, coupling, cohesion, and structural integrity.

When not to use it

Skip Code Review Architecture when the task is outside the analysis category, or when a more specific skill in this directory already covers the same workflow with clearer triggers.

How to install

Where will you use it?

Install scope
Claude Code folder setup
mkdir -p ~/.claude/skills/code-review-architecture
# Save SKILL.md to ~/.claude/skills/code-review-architecture/SKILL.md
  1. Claude Code personal install: place the skill and its bundled files at ~/.claude/skills/code-review-architecture/SKILL.md. For a shared project, commit the folder at .claude/skills/code-review-architecture/ instead.
  2. Current Claude Code detects SKILL.md changes in watched directories during the session. If you just created a top-level skills directory, run /reload-skills. Check that the skill is listed before testing its trigger.
  3. For Claude chat or Cowork in the Desktop app, manage uploaded skills in Customize > Skills; copying files into a local Claude Code folder is not a Desktop install. Other agents may use different install locations.

Full install guide for Claude, Cursor, and Codex →

Try a starter prompt

After installing the skill, paste this starter prompt into your agent to verify it triggers on a small task.

Starter prompt
Use the Code Review Architecture skill for this task: Use Code Review Architecture when this documented workflow matches the task. Confirm any required inputs or files before making changes.

What supports this recommendation?

66/100 provisional content score. This measures documentation, practical detail and source signals. It is not a measured task success rate or a security certification.

Documentation
70/100
Practical detail
68/100
Source evidence
53/100
Source signals
72/100
Model compatibility evidence
  • claudeuntested

    No model-specific signal or recorded compatibility test was found.

  • chatgptuntested

    No model-specific signal or recorded compatibility test was found.

  • geminiuntested

    No model-specific signal or recorded compatibility test was found.

  • copilotuntested

    No model-specific signal or recorded compatibility test was found.

  • llamauntested

    No model-specific signal or recorded compatibility test was found.

  • perplexityuntested

    No model-specific signal or recorded compatibility test was found.

  • mistraluntested

    No model-specific signal or recorded compatibility test was found.

  • grokuntested

    No model-specific signal or recorded compatibility test was found.

Inferred compatibility is based on content signals. Check the app, its available tools and setup requirements before running a skill.

What this skill does

# Code Review: Architecture Lens

Specialized agent for architectural analysis during code review. Focuses on design patterns, modularity, coupling, and systemic concerns.

## Scope Discipline

When PM explicitly dispatches this lens: - ✅ Review architectural concerns: design patterns, module structure, coupling - ✅ Analyze separation of concerns and responsibility assignment - ✅ Check for abstraction levels, interfaces, and boundaries - ✅ Verify systemic issues: scalability, maintainability, extensibility

Do NOT broaden into: - ❌ Type errors/coverage (use TYPE_SAFETY lens) - ❌ Security vulnerabilities (use SECURITY lens) - ❌ Error-handling hygiene, timeout discipline, retry semantics (use ERROR_HANDLING lens) - ❌ Performance characteristics (use PERFORMANCE lens) - ❌ Code complexity/readability (use SIMPLICITY lens)

## Output Format

All findings must follow this structure:

```markdown ## Must Fix - [CRITICAL|HIGH] [path:line] Title - Description: What is wrong and why it matters - Suggestion: Specific fix with code example - Metadata: cross_lens_candidate=true/false, tradeoff_required=true/false

## Observations - [MEDIUM|LOW] [path:line] Title - Description: Informational finding - Metadata: cross_lens_candidate=true/false, tradeoff_required=true/false

## Summary [One paragraph overall assessment] ```

## Severity Scale

- **CRITICAL**: A structural violation that reaches a real failure the finding can name — a dependency cycle that takes down both sides at once, a layer boundary crossed so writes bypass their validation, unfixable data corruption. - **HIGH**: Data loss or corruption, or a reachable failure the finding names along with how it is reached — e.g. a shared mutable singleton that a second request mutates while the first is in flight, so two users see each other's state. A structural preference argued only as an upkeep concern caps at MEDIUM. - **MEDIUM**: Structural and maintainability improvements — coupling, layering, cohesion, naming of modules — argued but not shown to break anything. - **LOW**: Minor structural suggestions, cosmetic issues.

## Metadata Guidance Tags

When reporting findings, always include:

**cross_lens_candidate**: Indicates this finding might also be relevant to other lenses - `true` if this finding could trigger other lens checks (e.g., tight coupling might affect both architecture and simplicity) - `false` if this is purely an architectural concern

**tradeoff_required**: Indicates if fixing this requires accepting a tradeoff - `true` if the fix involves significant refactoring, complexity, or timeline tradeoffs - `false` if the fix is straightforward with no downside

## What to Review

1. **Coupling and Cohesion** - Tight coupling between unrelated modules - Low cohesion (modules doing too many things) - Circular dependencies - Violation of dependency inversion principle

2. **Separation of Concerns** - Business logic mixed with presentation/persistence - Hardcoded configuration or business rules - Direct database access from UI/controllers - Single Responsibility Principle violations

3. **Abstraction and Interfaces** - Missing or inappropriate abstraction layers - Concrete dependencies instead of abstractions - Leaky abstractions - Inconsistent abstraction levels

4. **Module Boundaries** - Clear API contracts between modules - Proper use of public/private/internal boundaries - Layering violations (skipping layers) - Module size and complexity

5. **Design Patterns** - Appropriate use of design patterns - Over-engineering (pattern obsession) - Pattern misuse or anti-patterns - Consistent patterns across codebase

6. **Data Flow** - Clear data flow and transformation - Proper separation of data access and business logic - Immutable vs mutable data handling - State management approach

7. **Extensibility and Maintainability** - Hardcoded values that should be configurable - Duplicate code that should be abstracted - Difficulty in extending or modifying features - Missing extension points

8. **Transaction Boundary Invariants** - The pattern: work that modifies durable state inside a transactional scope, combined with hooks or callbacks that write to a store OUTSIDE that transactional scope, produces rollback-inconsistency — the durable store rolls back, the external store does not. - Transactional scopes exist across most ecosystems: SQL transactions (`BEGIN`/`COMMIT`), Spring `@Transactional`, .NET `TransactionScope`, Go `sql.Tx`, Elixir `Ecto.Multi`, Python SQLAlchemy `Session.begin`, any ORM's `transaction { }` / `transaction do end` block, and most database migrations (which run inside an implicit transaction by default on engines that support transactional DDL). - Lifecycle / hook mechanisms that can fire INSIDE the transaction exist in most ORMs and persistence frameworks: Rails callbacks (`after_save`, `after_create`, `after_update`, `after_destroy`, `before_save`), Django signals (`post_save`, `pre_save`, `post_delete`), SQLAlchemy events (`after_insert`, `before_update`), Hibernate/JPA listeners (`@PostPersist`, `@PreUpdate`), Sequelize hooks (`afterCreate`, `afterUpdate`), Prisma middleware, Entity Framework `SaveChanges` interceptors, Ecto changeset callbacks, Mongoose middleware (`pre`/`post`). The common failure mode: a hook fires as part of the save, writes to a non-transactional store, and is NOT rolled back when the enclosing transaction aborts. - Non-transactional stores (whose writes are NOT reverted by a DB rollback) include: caches (Redis, Memcached, in-process memoization that persists beyond the transaction), external HTTP / gRPC / API calls, message queues and job enqueues (Kafka, RabbitMQ, SQS, Sidekiq, Resque, Celery, BullMQ), search indices (Elasticsearch, OpenSearch, Algolia, Searchkick), filesystem writes, email senders, webhooks, and loggers that target external sinks. - Boundary-safe hook mechanisms DO exist in most ecosystems: Rails `after_commit` / `after_rollback`, Django `transaction.on_commit`, SQLAlchemy `after_commit` event, Spring `TransactionSynchronization`, .NET `TransactionCompleted`, Ecto `Repo.transaction` combined with explicit post-commit side-effects. External side effects MUST use the boundary-safe variant, OR be explicitly documented as safe-under-rollback (idempotent on replay, append-only with dedup). - Trigger scan: when a diff wraps multiple persistence calls in an explicit transactional scope, performs bulk persistence in a loop, OR adds a migration/script that mutates domain tables, open the model/entity files of every referenced type and enumerate their lifecycle hooks. For each hook that is NOT the post-commit variant, read its body; if it writes to a non-transactional store, flag it. - This scan requires reading files outside the diff. It is NOT optional for diffs that include migrations, transactional scripts, or new bulk-persistence call sites. A review that does not explicitly list the types read and the hooks inspected is incomplete — return BLOCKED. - Out of scope: writes that are explicitly documented as idempotent-on-replay (append-only event streams with dedup keys, audit logs), and reads that require no cleanup. Flag only when rollback would leave the external store inconsistent with durable state.

## Example Finding

```markdown ## Must Fix - [HIGH] [src/controllers/order.ts:23] Pricing state shared across requests via a module singleton - Description: The controller mutates a module-level `pricingContext`; two concurrent orders interleave and the second is priced with the first's tier — reproducible by submitting two orders with different tiers in parallel. - Suggestion: Pass pricing context per request, or extract to `OrderService.validateAndPrice(ctx)` with no module state. - Metadata: cross_lens_candidate=true, tradeoff_required=false ```

## Adversarial Input Discipline

Before returning any verdict, identify one plausible failure scenario for the primary architectural change in the diff — a transaction rollback mid-way through, a hook firing under a constraint violation, a dependency cycle triggered under load, a layering bypass, a contract change that existing callers don't honor — and trace the state the system ends in. If you cannot construct such a scenario, your review is incomplete — return BLOCKED with the reason "could not construct failure scenario" rather than APPROVED.

When a diff touches migrations, bulk persistence operations, or new persistence call sites, read the lifecycle hooks of every affected type before concluding. Cross-file reasoning is required; line-by-line diff review is insufficient for architectural findings.

Concretely for transactional-scope diffs: name the transactional entry point, list every type whose persistence methods are called inside it, list every lifecycle hook declared on those types that is NOT a post-commit variant, and for each such hook state what it would write to an external store on partial rollback. If the type/model files were not opened and their hooks not inspected, return BLOCKED — the analysis is incomplete regardless of whether a finding was reached.

## Integration Notes

This lens is part of the six-pass code review protocol. Findings are merged with other lenses via deterministic synthesis: - Dedupe by (path, line, title) - Precedence: SECURITY > ERROR_HANDLING > TYPE_SAFETY > PERFORMANCE > ARCHITECTURE > SIMPLICITY

Intended uses

  • Use Code Review Architecture when this documented workflow matches the task.

Implementation notes

  • Review the source instructions and adapt inputs before running the workflow.

Try it, then tell us how it went

A copied prompt does not tell us whether the task worked. Report your result after checking the output. We collect your tool and outcome, never your files or prompt.