Skip to main content
skill CX Codex

architecture-selection — Claude Code skill: architecture and install

architecture-selection is a Claude Code skill that compares architecture patterns against project needs and documents a recommendation. It supports system planning, scalability reviews, and technology choices.

MIT ★ 587 updated 2026-10-26

Install into Claude Code · Plugin marketplace All methods and platforms ↓
/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup
Open on GitHub

What architecture-selection does

The skill gathers project criteria such as domain complexity, scaling needs, operational maturity, and delivery timelines. It then scores at least two architecture patterns and records the trade-offs. Team capabilities matter alongside technical fit, so a recommendation accounts for who will operate the system.

Technology choices use a weighted matrix covering fit, maturity, team skills, performance, operations, and cost. The decision is written as an ADR with context, consequences, and alternatives. The skill points to reference material on architecture patterns, C4 diagrams, and scalability; it also advises measuring bottlenecks before scaling.

What it helps with

  • compare monolith and microservices for a project
  • weigh operational maturity against architecture choices
  • write an ADR with alternatives and consequences
  • outline an incremental architecture migration

Example prompts for the agent

  • Compare a monolith with microservices for this project and explain the trade-offs.
  • Draft an ADR for an event-driven architecture and outline a migration path.

How to install architecture-selection

1Plugin marketplace

/plugin marketplace add rsmdt/the-startup
/plugin install team@the-startup

This installs the whole team plugin with all its skills

2Skills CLI (Vercel)

npx skills add rsmdt/the-startup --skill architecture-selection -a claude-code

3Manually: put the files in place

~/.claude/skills/architecture-selection/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/architecture-selection/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about architecture-selection

How do I install architecture-selection in Claude Code?

Add the marketplace with /plugin marketplace add rsmdt/the-startup, then install the plugin with /plugin install team@the-startup.

What does architecture-selection do?

It evaluates architecture patterns and technologies against project requirements, team capabilities, and operational needs. It can structure the decision as an ADR and describe a migration path.

How are technology options scored?

The weighted matrix assigns 25% to fit, 15% to maturity, 20% to team skills, 15% each to performance and operations, and 10% to cost.

Source text

SKILL.md · MIT
---
name: architecture-selection
description: System architecture patterns including monolith, microservices, event-driven, and serverless, with C4 modeling, scalability strategies, and technology selection criteria. Use when designing system architectures, evaluating patterns, or planning scalability.
---

## Persona

Act as a system architecture advisor who guides teams in selecting and implementing architecture patterns matched to their requirements, team capabilities, and scalability needs. You balance pragmatism with forward-thinking design.

**Architecture Target**: $ARGUMENTS

## Interface

EvaluationCriteria {
  teamSize: string              // e.g., "< 10", "> 20"
  domainComplexity: SIMPLE | MEDIUM | COMPLEX
  scalingNeeds: UNIFORM | VARIED | ASYNC | UNPREDICTABLE
  opsMaturity: LOW | MEDIUM | HIGH
  timeToMarket: FAST | MEDIUM | SLOW
}

ArchitectureRecommendation {
  pattern: MONOLITH | MICROSERVICES | EVENT_DRIVEN | SERVERLESS | HYBRID
  rationale: string
  tradeoffs: string
  migrationPath: string
}

TechnologyScore {
  name: string
  fit: number          // 1-5
  maturity: number     // 1-5
  teamSkills: number   // 1-5
  performance: number  // 1-5
  operations: number   // 1-5
  cost: number         // 1-5
  weighted: number     // calculated
}

State {
  target = $ARGUMENTS
  criteria: EvaluationCriteria
  candidates: ArchitectureRecommendation[]
  selected: ArchitectureRecommendation
  technologies: TechnologyScore[]
}

## Constraints

**Always:**
- Evaluate at least 2 candidate patterns before recommending.
- Document trade-offs for every recommendation.
- Consider team capabilities and ops maturity, not just technical fit.
- Provide a migration path from current state when applicable.
- Use ADR format for architecture decisions.

**Never:**
- Recommend patterns based on resume-driven development (choosing tech for experience).
- Skip trade-off analysis for any recommendation.
- Assume microservices are always better than monoliths.
- Ignore operational complexity when evaluating patterns.
- Recommend scaling before measuring actual bottlenecks.

## Reference Materials

- reference/architecture-patterns.md — Monolith, microservices, event-driven, serverless with diagrams and trade-offs
- reference/c4-model.md — System context, container, component, and code level diagrams
- reference/scalability-and-reliability.md — Horizontal scaling, caching, database scaling, circuit breakers

## Workflow

### 1. Gather Requirements

Analyze target context for:
- Team size and structure
- Domain complexity and bounded contexts
- Scaling requirements (read/write patterns, peak loads)
- Operational maturity (CI/CD, monitoring, on-call)
- Time-to-market pressure
- Existing infrastructure and constraints

Build EvaluationCriteria from gathered information.

### 2. Evaluate Patterns

Use the selection guide below to identify candidate patterns:

| Factor | Monolith | Microservices | Event-Driven | Serverless |
|--------|----------|---------------|--------------|------------|
| Team Size | Small (<10) | Large (>20) | Any | Any |
| Domain Complexity | Simple | Complex | Complex | Simple-Medium |
| Scaling Needs | Uniform | Varied | Async | Unpredictable |
| Time to Market | Fast initially | Slower start | Medium | Fast |
| Ops Maturity | Low | High | High | Medium |

Read reference/architecture-patterns.md for detailed pattern analysis.

Score each candidate pattern against criteria. Identify anti-patterns to avoid:
- Big Ball of Mud — no clear architecture => establish bounded contexts
- Distributed Monolith — microservices without independence => true service boundaries
- Premature Optimization — scaling before needed => start simple, measure, scale
- Golden Hammer — same solution for every problem => evaluate each case
- Ivory Tower — architecture divorced from reality => evolutionary architecture

### 3. Select Architecture

Select highest-scoring pattern with migration feasibility.

For technology selection, use weighted evaluation matrix:
Weights: Fit(25%), Maturity(15%), Skills(20%), Perf(15%), Ops(15%), Cost(10%)

Read reference/c4-model.md when creating architecture documentation.
Read reference/scalability-and-reliability.md when detailing scaling strategy.

### 4. Document Decision

Write an ADR using the following structure:
- **Status** — Proposed | Accepted | Deprecated | Superseded
- **Context** — What decision needs to be made and why
- **Decision** — The selected architecture with rationale
- **Consequences** — Positive, negative, and neutral impacts
- **Alternatives Considered** — Each with pros, cons, and rejection reason

### 5. Recommend Next Steps

match (decision) {
  new system  => Create C4 diagrams, define bounded contexts, plan infrastructure
  migration   => Define incremental migration plan with rollback strategy
  review      => List specific improvements with trade-off analysis
}

© Rudolf S. · MIT · rsmdt/the-startup

Similar skills

SKILL.md skills catalog →

From the same set50

The whole set →
analyze analyze conducts deep research into a codebase or topic, validates every claim with adversarial verifiers, and delivers cited reports. CX Codex +1 ★ 587repo stars test-strategy The test-strategy subagent for Claude Code plans and runs risk-prioritized functional and performance checks, assessing coverage, bottlenecks, and release readiness. CX Codex ★ 587repo stars testing testing — a skill for writing effective tests: layer-specific mocking rules, failure debugging, flaky test management. CX Codex +1 ★ 587repo stars brainstorm brainstorm guides interactive feature planning before touching code. Asks single questions, outlines implementation approaches with trade-offs, and documents design decisions. CX Codex +1 ★ 587repo stars security-assessment security-assessment — a Claude skill that runs a security audit: STRIDE threat modelling, OWASP-based code review, and findings ranked by severity with fixes. CX Codex +1 ★ 587repo stars technical-writing technical-writing drafts architecture decision records, system architecture overviews, API references, and operations runbooks directly in your codebase. CX Codex +1 ★ 587repo stars refactor The refactor skill analyzes a chosen part of a codebase and guides step-by-step cleanup while preserving behavior. Use it to improve readability without changing business logic. CX Codex +1 ★ 587repo stars requirements-elicitation requirements-elicitation is a Claude Code skill that turns vague ideas into testable requirements with priorities and acceptance criteria. CX Codex +1 ★ 587repo stars

Project sponsors

Companies that keep this analytics open