architecture-reviewer — Claude Code subagent: review system designs
The architecture-reviewer subagent for Claude Code independently checks architectural documents against repository code. It verifies declared structures, not runtime behavior.
Elastic-2.0 ★ 155 updated 2026-10-29
/plugin marketplace add serpro69/claude-toolbox
/plugin install kk@claude-toolboxWhat architecture-reviewer does
The subagent executes in structural isolation from the design authoring session. It has zero access to conversational history, discarded drafts, or file-writing tools, which eliminates confirmation bias. Operations are strictly limited to file reading, search via Grep and Glob, and knowledge retrieval through capy_search.
Execution follows three rigid stages. First, the reviewer parses the text in a repo-blind extraction pass to list every explicit claim. Next, it verifies the existence and topological layout of declared entities in the codebase, such as a database column or a specific endpoint. It explicitly leaves behavioral validity under retries or edge cases to code-review tools.
Without a valid absolute plugin path in its prompt, execution halts immediately because the agent lacks shell execution and cannot expand environment variables. Security boundaries, permission modeling, and data classification are routed out to dedicated security tools rather than handled directly.
What it helps with
- verify ADR assertions against declared repository layout
- evaluate reversibility and reasoning soundness in design docs
- detect missing infrastructure mechanisms referenced in specifications
- audit composite domain glossary and constraint kits
Example prompts for the agent
- Run an architecture review on
docs/adr/0004-idempotency.md - Validate the architecture section of
docs/design/billing-v2.mdagainst codebase - Audit domain reference files in
docs/domain/for missing links
How to install architecture-reviewer
1Plugin marketplace
/plugin marketplace add serpro69/claude-toolbox/plugin install kk@claude-toolbox2Manually: put the files in place
.claude/agents/architecture-reviewer.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/architecture-reviewer.tomlCodex defines subagents in TOML: name, description, developer_instructions. Move the Markdown text into developer_instructions by hand. For all projects use ~/.codex/agents/
Manually: put the files in place
.cursor/agents/architecture-reviewer.mdCursor also reads .claude/agents/
Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean
Questions about architecture-reviewer
How to install architecture-reviewer in Claude Code?
Run /plugin marketplace add serpro69/claude-toolbox in Claude Code, then execute /plugin install kk@claude-toolbox.
What scope does architecture-reviewer cover?
It confirms that declared architectural building blocks actually exist in the code structure and evaluates decision soundness. It deliberately avoids testing behavioral or runtime execution correctness.
Does this subagent handle threat modeling?
No, trust boundaries and authentication structures are delegated out to dedicated audit tooling rather than analyzed in the review report.