# Software Architect

> Use this skill when user needs system architecture design, technology stack selection, or architecture review. Trigger keywords: system design, architecture proposal, tech stack, microservices, distributed systems, high availability, scalability, CAP theorem, architecture tradeoffs, refactoring plan. Applicable to high-level design decisions, not specific code implementation.

- **Type:** Skill
- **Install:** `agentstack add skill-miaoge-ge-coding-agent-skills-software-architect`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Miaoge-Ge](https://agentstack.voostack.com/s/miaoge-ge)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Miaoge-Ge](https://github.com/Miaoge-Ge)
- **Source:** https://github.com/Miaoge-Ge/coding-agent-skills/tree/main/plugins/software-architect/skills/software-architect

## Install

```sh
agentstack add skill-miaoge-ge-coding-agent-skills-software-architect
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Software Architecture Design

## Description
Provide system architecture design proposals, technology stack recommendations, and architecture tradeoff analysis to ensure solutions meet business requirements and non-functional requirements.

## When to Use
- User requests "design architecture for XX system" or "help me choose tech stack"
- User asks about system scalability, high availability, or performance optimization strategies
- User needs microservices decomposition, module partitioning, or service boundary design
- User requests architecture review or refactoring proposal
- User asks how to apply architectural theories (CAP theorem, consistency models, distributed transactions) to specific scenarios
- User compares different architecture patterns or technology stacks

## When NOT to Use
- User only needs specific code implementation or programming tips without architectural decisions
- User's problem is a pure algorithm or data structure implementation
- User needs UI/UX design rather than system architecture
- User only asks how to use a framework or library without system-level design
- User's project is extremely small (e.g., personal script, single-file tool) and doesn't require architecture

## Input
```typescript
{
  requirements: {
    businessScenario: string      // Business scenario description
    userScale?: string            // User scale (e.g., "1M DAU")
    qps?: string                  // Query/Request volume (e.g., "1000 QPS peak")
    dataVolume?: string           // Data volume (e.g., "10TB historical data")
    latencyRequirement?: string   // Latency requirement (e.g., "p99 < 100ms")
    readWriteRatio?: string       // Read/Write ratio (e.g., "read:write = 9:1")
    consistencyRequirement?: string // Consistency (strong/eventual/causal)
  }
  constraints: {
    budget?: string               // Budget constraints
    teamSize?: string             // Team size and skill set
    timeline?: string             // Delivery timeline
    existingTechStack?: string[]  // Existing technology stack
    complianceRequirements?: string // Compliance (e.g., GDPR, SOC2)
  }
  goals: {
    priority: string              // Core objective (performance/cost/time-to-market)
    tradeoffs?: string            // Known tradeoff preferences
  }
  existingArchitecture?: string   // Existing architecture (for review/refactoring)
}
```

## Output
```typescript
{
  architectureProposal: {
    style: string                 // Architecture style (monolithic/layered/microservices/event-driven/CQRS/serverless)
    topology: string              // Topology description (components, data flow, call relationships)
    diagram?: string              // Mermaid diagram or C4 model description
    componentBreakdown: {
      name: string
      responsibility: string
      technology: string
    }[]
  }
  techStackRecommendation: {
    category: string              // Category (database/cache/message queue/load balancer, etc.)
    options: {
      name: string
      pros: string[]
      cons: string[]
      justification: string       // Selection rationale
    }[]
    recommendation: string        // Recommended solution
    risks: string[]               // Potential risks
    mitigationPlan: string        // Risk mitigation measures
  }[]
  tradeoffAnalysis: {
    dimension: string             // Tradeoff dimension (performance vs cost/consistency vs availability, etc.)
    options: {
      choice: string
      pros: string[]
      cons: string[]
      applicableScenarios: string[]
    }[]
    recommendation: string
  }[]
  nonFunctionalRequirements: {
    highAvailability?: string     // HA solution (failover/degradation/circuit breaking/rate limiting)
    scalability?: string          // Scalability solution (stateless design/sharding/caching)
    observability?: string        // Observability (logging/monitoring/tracing/alerting)
    security?: string             // Security (authentication/authorization/encryption/audit)
  }
  evolutionPath?: string          // Architecture evolution path (e.g., monolith to microservices migration)
}
```

## Execution Workflow

Copy the following checklist before starting, and explicitly mark status after completing each step.

### Step 1: Requirement Clarification and Constraint Identification
- Confirm business scenario and core use cases
- Quantify key metrics (user scale, QPS, latency, data volume)
- Identify read/write patterns and consistency requirements
- Clarify resource constraints (budget, team, timeline, existing tech stack)
- Determine priority objectives (performance/cost/time-to-market)

**Feedback Loop**: If critical constraint information is missing (e.g., QPS or data volume), MUST ask user to provide details. Avoid designing based on assumptions.

### Step 2: Architecture Style Selection
- List candidate architecture styles (monolithic/layered/microservices/event-driven/CQRS/serverless)
- Compare applicability of each style in current scenario
- Explain recommended approach and rationale

**Feedback Loop**: If business scenario allows multiple reasonable architectures, provide 2-3 options for user to weigh, rather than a single answer.

### Step 3: Component Design and Technology Selection
- Define core system components and their responsibility boundaries
- Describe data flow and call relationships between components
- For each technology category (database/cache/message queue, etc.), provide candidate comparisons
- Explain recommended tech stack and selection rationale (performance/maturity/ecosystem/team familiarity)

**Feedback Loop**: If recommended tech stack conflicts with existing stack, MUST explain migration cost and evolution path, or provide compatible alternatives.

### Step 4: Tradeoff Analysis
- Identify key tradeoff dimensions (performance vs cost, consistency vs availability, complexity vs flexibility)
- Provide pros/cons analysis for different choices in each dimension
- Give recommended decision based on business objectives

**Example Tradeoff Dimensions**:
- Performance vs Cost: Vertical scaling vs Horizontal scaling
- Consistency vs Availability: CAP theorem application (CP vs AP)
- Complexity vs Flexibility: Monolith vs Microservices
- Real-time vs Resource consumption: Push vs Pull model

### Step 5: Non-Functional Requirements Design
- High Availability: Failover, service degradation, circuit breaking, rate limiting
- Scalability: Stateless design, sharding strategy, caching layers
- Observability: Log aggregation, metrics monitoring, distributed tracing, alerting rules
- Security: Authentication/authorization, data encryption, audit logs

**Feedback Loop**: If user hasn't clarified non-functional requirement priorities, provide default reasonable solutions and mark optional enhancements.

### Step 6: Risk Identification and Mitigation
- List potential risks of architecture proposal (technical, operational, cost risks)
- Provide mitigation measures for each risk
- Explain architecture evolution path (e.g., monolith to microservices migration strategy)

**Feedback Loop**: If solution has significant unmitigable risks, MUST explicitly inform user rather than hide or downplay.

## Failure Handling

### Unclear Requirements
- **Symptom**: User only provides vague description (e.g., "design a high-concurrency system")
- **Action**: Return requirement clarification checklist, ask user to provide key constraints (user scale, QPS, latency, data volume)

### Conflicting Constraints
- **Symptom**: User demands extremely high performance with extremely low budget
- **Action**: Clearly point out constraint conflicts, provide multiple solutions with cost/performance tradeoffs, let user decide

### Tech Stack Limitations
- **Symptom**: User requires using unsuitable tech stack (e.g., relational database for time-series data)
- **Action**: Explain tech stack limitations, provide alternatives or compromises (e.g., TimescaleDB)

### Architecture Review Failure
- **Symptom**: Existing architecture has serious design flaws
- **Action**: Clearly point out issues, impact scope, and severity. Provide incremental refactoring path rather than complete rewrite.

## See Also
- `deep-learning-expert` — when the system centers on model training or serving.
- `llm-testing-expert` — quality and safety infrastructure for LLM-powered systems.
- `github-master` — turning the design into CI/CD, branching, and release workflows.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Miaoge-Ge](https://github.com/Miaoge-Ge)
- **Source:** [Miaoge-Ge/coding-agent-skills](https://github.com/Miaoge-Ge/coding-agent-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-miaoge-ge-coding-agent-skills-software-architect
- Seller: https://agentstack.voostack.com/s/miaoge-ge
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.