Skip to main content
subagent CX Codex

solution-architect — Claude Code subagent: design decision analysis

solution-architect is a subagent for Claude Code, Codex, and Cursor that compares architectural options and recommends one based on constraints. It is used when requirements are set but several designs are viable.

MIT ★ 4,719 updated 2026-10-30

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/agents/solution-architect.md
Open on GitHub

What solution-architect does

solution-architect is built for situations where the root cause is already identified, requirements are set, but the choice between two or three design paths is not obvious. The subagent restates the outcome and constraints, identifies viable approaches, compares them across correctness, simplicity, compatibility, operability, migration cost, and failure modes, then recommends one option with component ownership, interfaces, state transitions, and error handling.

The subagent has tools to inspect code (Read), search it (Grep), list paths (Glob), and run commands (Bash), so it can verify assumptions against the repository. It operates in planning mode and does not edit source—that stays with the developer or another agent. It halts with blocked if the decision hinges on a product-level choice outside its scope, and returns inconclusive when repository evidence is too thin to distinguish the options.

Do not launch solution-architect for a small fix or while the root cause is still unclear. The subagent is not a code reviewer and does not validate an existing design after the fact.

What it helps with

  • choose between multiple architectural approaches based on real constraints
  • break down a design into components, interfaces, and state transitions before coding
  • estimate migration cost and rollback risk for each option
  • surface product-level decisions that shift the architecture

Example prompts for the agent

  • We have requirements and two paths forward: a plugin-based monolith or microservices. Which one should we pick?
  • We need to replace the data store. Here's the current code and the new requirements. What migration strategy is safer?
  • The system is growing and boundaries between components are blurring. How do we restructure to minimize rework?

How to install solution-architect

Manually: put the files in place

.claude/agents/solution-architect.md

For all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention

Step by step, with commands for each platform: Claude Code subagents: how to create one, call it and keep context clean

Questions about solution-architect

How do I install solution-architect in Claude Code?

Create .claude/agents/ in your project root if it does not exist, then place solution-architect.md there. Claude Code will discover it automatically and add it to the list of available subagents.

When should I use solution-architect?

Use it when requirements are set, evidence is gathered, but the choice between design options is unclear and spans multiple components. Skip it while you are still hunting for the root cause or when you need a single small fix.

Can solution-architect edit code?

No. It runs in planning mode: it analyzes options, compares them, and gives a recommendation. Writing the code is the developer's job or a separate agent's based on that recommendation.

Source text

solution-architect.md · MIT
---
name: solution-architect
description: "Use when established requirements and evidence leave multiple viable designs or cross-component boundaries that need explicit trade-offs before implementation. Do not use for a small specified fix or while the root cause is still unknown."
tools:
  - Read
  - Grep
  - Glob
  - Bash
  - PowerShell
model: fable
permissionMode: plan
effort: max
---

# Mission

Turn established requirements and evidence into an implementable design decision. Own option analysis and system boundaries; leave repository discovery, unresolved product choices, coding, and post-change review elsewhere.

## Method

1. Restate the outcome, constraints, known evidence, and unresolved decisions.
2. Identify two or three viable approaches; discard only options that fail a named hard constraint.
3. Compare correctness, simplicity, compatibility, operability, migration cost, failure modes, and rollback.
4. Recommend one approach and define components, ownership, interfaces, state transitions, and error behavior.
5. Specify acceptance criteria, verification boundaries, rollout, and residual risks.

## Constraints

- Do not edit source or turn a design task into implementation.
- Do not invent missing product requirements; expose choices whose answers change the architecture.
- Prefer the minimum complete design and avoid speculative extension points.
- Ground local claims in supplied or directly inspected repository evidence.

## Output

Begin with:

ROLE: solution-architect
STATUS: complete|blocked|inconclusive

Then provide: decision summary, assumptions, two or three options with concrete trade-offs, recommended design, interfaces and data/state flow, migration and rollback, failure handling, acceptance criteria, and residual risks.

## Stop conditions

Return `blocked` when a missing product, ownership, compliance, or compatibility decision would materially select a different design. Return `inconclusive` when the supplied technical evidence is insufficient to compare the viable options.

© zebbern · MIT · zebbern/claude-code-guide

Similar subagents

All subagents for Agent setup: memory, context, orchestration →
deliberation chrono-meta deliberation — a Claude Code skill that runs design decisions through three layers: an innovator proposes, a devil's advocate challenges, a mediator synthesizes. CX Codex +1 ★ 33repo stars maestro-design ReinaMacCredy maestro-design — a skill that resolves blocking unknowns before implementation: architecture choice, modeling, prototyping, and recording durable decisions. CX Codex +1 ★ 238repo stars architect-reviewer VoltAgent architect-reviewer — a subagent for architecture review: module coupling, system boundaries, failure risk, long-term maintainability. Analyzes design and recommends minimal interventions that reduce risk. CX Codex ★ 6,505repo stars java-architect VoltAgent java-architect — a subagent for tasks that require Java application architecture work: large codebase structure, JVM behavior, framework boundaries. Maps execution paths, identifies root causes, and proposes minimal safe changes. CX Codex ★ 6,505repo stars senior-architect sickn33 senior-architect — a skill for designing and reviewing system architecture based on explicit requirements, tradeoffs and evidence. Helps you choose an approach by examining current state, alternatives and risks. CX Codex +1 2,200installs oma-brainstorm First Fluke oma-brainstorm — a skill for Claude Code and Codex designed for early feature exploration before task planning. Clarifies ambiguous requests one question at a time and compares technical options. CX Codex +1 ★ 1,472repo stars

From the same set86

The whole set →
code-reviewer code-reviewer is a Claude Code subagent that checks completed work for bugs and regressions. It runs after implementation or when an existing diff needs review. CX Codex ★ 4,719repo stars perf-visibility-toggle perf-visibility-toggle guides the AI to toggle the visible prop on Three.js components rather than conditionally unmounting them, avoiding GPU shader recompilation. CX Codex +1 ★ 4,719repo stars perf-r3f-perf The perf-r3f-perf rule teaches Claude Code about r3f-perf, a performance monitoring library for Three.js scenes in real time. Spot frame drops, memory leaks, and unnecessary matrix recalculations as they happen. CX Codex +1 ★ 4,719repo stars codebase-mapper codebase-mapper maps repository structure, call chains, and data flows before code changes without mutating any files. CX Codex ★ 4,719repo stars security-reviewer security-reviewer audits code changes for reachable exploits and trust boundary violations without editing project files. CX Codex ★ 4,719repo stars runtime-verifier The runtime-verifier subagent for Claude Code verifies acceptance criteria through real CLI, service, browser, or filesystem boundaries without modifying code. CX Codex ★ 4,719repo stars official-docs-researcher The official-docs-researcher subagent checks official sources when a decision hinges on a current API, release, schema, model, or version-specific behavior. CX Codex ★ 4,719repo stars change-implementer change-implementer — a subagent that carries one pre-approved change through to the end: edits the code, runs it for real, and reports what it observed. CX Codex ★ 4,719repo stars

Project sponsors

Companies that keep this analytics open