Skip to main content
skill CX Codex

architecture-review · owainlewis — Claude Code skill: what it does, how to install

architecture-review — a skill for Claude Code and Codex reviews RFCs, ADRs, and technical proposals before code gets written. It flags critical architectural flaws, unsafe patterns, and missing recovery paths.

MIT 347 installs ★ 438 updated 2026-11-10

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add owainlewis/blueprint --skill architecture-review -a claude-code
Open on GitHub

What architecture-review does

The skill evaluates technical decisions early when corrections require minimal effort. The reviewer checks the proposal against existing code, schemas, REQUIREMENTS.md, and ARCHITECTURE.md to spot discrepancies with the live system.

The review traces a concrete request lifecycle from input to output, testing for retries, race conditions, and error states. It evaluates data ownership, schema migrations, rollbacks, and authorization boundaries. Stylistic feedback is omitted entirely: the output only lists blockers and decisions that lead to divergent implementations.

A dedicated read-only agent or an unpolluted subagent (claude -p or codex exec) must execute the review without modifying files. If an independent evaluator is missing, the tool sets the verdict to Blocked.

What it helps with

  • catch fatal architecture errors and security bugs before coding begins
  • trace request lifecycles through concurrent executions and unexpected failures
  • validate database migration plans and rollback feasibility
  • simplify technical designs by reducing unnecessary state and moving parts

Example prompts for the agent

  • Review the technical proposal in docs/rfcs/002-billing.md for concurrency and data ownership issues
  • Run an architecture review on spec.md before we start implementing the changes

How to install architecture-review

1Skills CLI (Vercel)

npx skills add owainlewis/blueprint --skill architecture-review -a claude-code

2Manually: put the files in place

~/.claude/skills/architecture-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/architecture-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about architecture-review

How to install architecture-review in Claude Code?

Run npx skills add owainlewis/blueprint --skill architecture-review -a claude-code in your terminal.

What does architecture-review do?

It reviews architectural documents like specs, RFCs, and ADRs, returning actionable blockers, important design risks, and a final verdict of Approve, Request changes, or Blocked.

Who actually performs the review?

The review must be conducted by a neutral party, such as a fresh subagent or a separate read-only CLI session (claude -p or codex exec), rather than the agent that drafted the proposal.

Source text

SKILL.md · MIT
---
name: architecture-review
description: "Reviews a technical proposal before any code is written: an architecture, spec, RFC, ADR, or design issue. Finds choices that would make it wrong, unsafe, or impossible to prove, and the open questions that block building it."
user-invocable: true
argument-hint: "[architecture, spec, RFC, ADR, or issue]"
disable-model-invocation: true
---

# Architecture review

Find the choices that would make a design wrong, unsafe, or impossible to prove, while they are still cheap to change. Judge the decisions, not the document's length or format.

## Reviewer

Someone who did not write the proposal: a fresh subagent, or another agent CLI run read-only (`codex exec "<prompt>"` or `claude -p "<prompt>"`). If neither is available, say review is blocked. The reviewer changes nothing.

## Steps

1. Read the proposal, `REQUIREMENTS.md`, `ARCHITECTURE.md`, and the code, schemas, and config it touches. Check every claim about the current system against them.
2. Write down the problem, who it affects, the intended outcome, and the main tradeoff. Flag any the proposal leaves unclear.
3. Walk one real request from input to what the user sees, including what happens when a step fails, is retried, or runs twice at once.
4. Check data ownership, interfaces, migrations, rollback, security (auth, untrusted input, secrets), and the scale the proposal claims.
5. Look for a simpler design that gets the same result with less state or fewer moving parts.
6. Check that each important rule and failure has an acceptance check.

## Findings

Report only what could change the design:

- **Blocker:** unsafe, contradicts the goal or the current system, or cannot recover from a likely failure.
- **Important:** two capable engineers could build it in ways that differ for users, data, or security.

For each: where it is, what goes wrong and when, the evidence, and the smallest fix or your recommended answer. Say whether you ran it, traced it through the code, or only read the proposal. Skip wording preferences and questions that cannot change the design. No findings is a valid result.

## Verdict

End with this block:

```text
VERDICT: Approve | Request changes | Blocked
UNVERIFIED: <what you could not check, or None>
REVIEWED_AT: <commit SHA, or the proposal's date>
```

Any Blocker or Important finding means `Request changes`. Use `Blocked` when context or a reviewer is missing. A detailed document is not a reason to approve. On a later round, confirm the old findings are settled and review only what changed since `REVIEWED_AT`.

© owainlewis · MIT · owainlewis/blueprint

Similar skills

All skills for Code review and refactoring →

architecture-review by other authors comes first.

architecture-review Donchitos architecture-review — a skill for Claude Code, Codex, Cursor and other agents that maps every GDD requirement to an architectural decision record. Runs before the project moves from Technical Setup into Pre-Production. CX Codex +1 653installs architecture-review decebals architecture-review — a skill that reviews a Java project at the macro level: package layout, module boundaries, dependency direction and layering. Useful once a codebase grows past the point where you can hold its structure in your head. CX Codex +1 394installs review-architecture serpro69 review-architecture is a Claude Code skill that checks a written architecture artifact against the system it describes. CX Codex +1 ★ 155repo stars System Architecture Reviewer microsoft The System Architecture Reviewer subagent reviews architecture choices against project constraints and records trade-offs. Use it to scope a design review or preserve the reasoning behind a decision. CX Codex +1 ★ 1,627repo stars adr-review ruvnet adr-review reviews git diffs against accepted Architecture Decision Records to detect violations, forbidden patterns, and architecture drift before merging code. CX Codex +1 747installs architecture-compass stark-ai-de architecture-compass is a Claude Code and Codex skill that manages architecture decisions and checks code against them. It audits repositories, governs ADRs, and guides scoped refactors. CX Codex +1 2,700installs Python Backend Architecture Review rknall Python Backend Architecture Review — a skill that reviews Python backend architecture: patterns, database, API, security, scalability. Useful when the design doc exists and you want the weak spots found before release. CX Codex +1 528installs technical-spec majiayu000 technical-spec enforces strict structures for technical design docs, RFCs, and ADRs with mandatory alternatives, diagrams, and risk matrices. CX Codex +1 245installs

From the same set9

plan plan breaks down feature specs into end-to-end tasks designed for an agent to finish in a single pull request. Runs before coding begins to turn requirements into ready-to-build work slices. CX Codex +1 788installs review Runs an isolated read-only code review. It checks changes against specs, probes security flaws, and verifies tests by breaking code deliberately. CX Codex +1 787installs task-to-pr task-to-pr — a skill that carries a spec, issue, or task to an open pull request: branch, tests, Conventional Commits, CI, and an independent review. Merges only on explicit request. CX Codex +1 452installs spec Writes a feature specification before coding begins. It produces a short PRD with user journeys and a technical design for the implementing agent. CX Codex +1 440installs improve The improve Claude Code skill simplifies existing code while preserving its behavior. It targets duplication, dead code, unclear names, and needless abstractions. CX Codex +1 372installs architecture Writes or updates the root ARCHITECTURE.md file from a fixed template. It locks in system boundaries, data flow diagrams, and architectural rules. CX Codex +1 331installs html-doc The html-doc skill turns a finished Markdown PRD or technical design into a static HTML reading page. It is useful when a document needs browser and print presentation. CX Codex +1 288installs codex-issue-coordinator codex-issue-coordinator is a Codex skill that assigns GitHub issues to AI workers, tracks PRs and tests, and merges completed work. It handles batches in one Codex conversation. CX Codex +1 241installs

Project sponsors

Companies that keep this analytics open