Architecture Scenario Explorer Action

Explore and compare multiple architectural approaches for a given requirement by generating side-by-side trade-off analyses covering scalability, complexity, and implementation cost.

When to Use This Command

Run this command when...

• You are evaluating whether to use microservices vs monolith, SQL vs NoSQL, or similar design decisions
• You need a structured comparison of multiple design approaches before committing to one
• You want to stress-test an architecture against different scale and failure scenarios

Avoid this command when...

• The architectural decision has already been made and you need implementation help
• You are looking for a quick code fix rather than a high-level design exploration

Quick Start

Copy
# .claude/commands/architecture-scenario-explorer-action.md
---
allowed-tools: ["Read", "Glob", "Grep", "WebSearch"]
---
Analyze the codebase and the given architectural question.
Generate 2-3 alternative approaches with trade-off analysis.
Evaluate each against scalability, complexity, and team fit.

Example usage:

/architecture-scenario-explorer-action "Should we split the auth service into its own microservice?"

Example output:

Scenario Analysis: Auth Service Extraction
==========================================

Option A: Keep Monolith
  Complexity: Low    | Scale: Medium  | Migration: None
  Pro: No network overhead, simpler debugging
  Con: Coupling increases over time

Option B: Extract Microservice
  Complexity: High   | Scale: High    | Migration: 3-4 weeks
  Pro: Independent scaling, team autonomy
  Con: Network latency, distributed transactions

Option C: Modular Monolith
  Complexity: Medium | Scale: Medium  | Migration: 1-2 weeks
  Pro: Clean boundaries without network cost
  Con: Still single deployment unit

Recommendation: Option C for current team size and scale

Core Concepts

Concept	Description
Scenario modeling	Defines load, failure, and growth scenarios to test each option
Trade-off matrix	Compares options across complexity, scalability, cost, and risk
Codebase analysis	Reads existing code to understand coupling and dependency depth
Decision record	Outputs an ADR-style document capturing the analysis and reasoning

Question --> Analyze Codebase --> Identify Options
                                       |
                            +----------+----------+
                            |          |          |
                         Option A  Option B  Option C
                            |          |          |
                         Evaluate Against Scenarios
                            |          |          |
                            +--- Trade-off Matrix -+
                                       |
                               Recommendation

Configuration

Option	Default	Description
options	auto	Number of alternatives to generate (2-5)
scenarios	growth,failure	Scenarios to evaluate against
depth	medium	Analysis depth (quick, medium, thorough)
format	markdown	Output format (markdown, adr, json)
include-code	false	Include sample implementation snippets for each option

Best Practices

1. Frame the question precisely -- "Should we use Redis?" is too vague. "Should we use Redis for session storage given 50k concurrent users?" is actionable.
2. Include current constraints -- team size, timeline, and budget dramatically change which option wins.
3. Do not skip the modular monolith -- it is often the right middle ground that teams overlook.
4. Save the output as an ADR -- Architecture Decision Records preserve the reasoning for future team members.
5. Revisit after scale changes -- the right architecture at 1k users may be wrong at 100k users.

Common Issues

1. Analysis too generic -- provide specific metrics (request volume, data size, team count) for a more grounded comparison.
2. Too many options generated -- more than 4 options leads to analysis paralysis. Constrain to 2-3 realistic alternatives.
3. Ignores existing code -- the command reads your codebase to assess coupling. Run it from the project root for best results.