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
.claude/agents/solution-architect.mdWhat 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.mdFor all projects use ~/.claude/agents/. Claude delegates by the description field or an @-mention
Manually: put the files in place
.codex/agents/solution-architect.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/solution-architect.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 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