Purpose
Evaluate a specific architecture or technology decision against cloud-native principles, surface the trade-offs explicitly, and produce a formal Architecture Decision Record (ADR) that an architecture review board can act on. Replaces gut-feel decisions and undocumented choices with a scored, defensible record.
When to Use
Invoke this skill when the user asks to:
- Decide whether to containerize, refactor to microservices, or adopt serverless for a workload
- Choose between self-managed infrastructure and a managed cloud service (e.g., self-hosted Kafka vs. managed streaming)
- Evaluate a build-vs-buy decision for a platform capability
- Assess whether a proposed design aligns with the organization's cloud-native maturity targets
- Document an architecture decision for review, governance, or future reference
- Compare two or three competing architecture approaches for the same problem
Inputs Required
Before starting, collect:
- Decision under evaluation: The specific choice being made, framed as a question (e.g., "Should the order service move from EC2 to managed Kubernetes?")
- Current state: Existing stack, deployment model, and how the workload runs today
- Alternatives being considered: 2–3 candidate options (if only one is given, generate plausible alternatives)
- Constraints: Budget ceiling, team skills, compliance/regulatory requirements, vendor commitments
- Workload characteristics: Traffic pattern (steady/spiky/bursty), state requirements, latency sensitivity, scale targets
- Cloud provider context: Primary provider(s) and any multi-cloud or portability requirements
- Time horizon: Decision urgency and how long this decision must hold (1 year vs. 5 years)
If maturity targets or constraints are missing, assume a mid-maturity organization optimizing for operational leanness over maximum control, and note the assumption.
Instructions
Step 1: Frame the Decision and Context
Restate the decision as a single clear question. Summarize the forces driving it — what changed, what's broken, or what's being newly built. Capture the constraints and workload characteristics in 4–6 bullets so the rest of the evaluation is grounded in this specific situation, not generic best practice.
Step 2: Score Each Option Against the Cloud-Native Pillars
For each candidate option, evaluate against five pillars. Score each pillar Strong / Adequate / Weak with one sentence of reasoning specific to this workload — not generic.
- Containerization & Portability: Is the workload packaged for portable, reproducible deployment? Does the option lock the team to a single runtime or provider?
- Service Decomposition: Does the option support appropriate granularity (monolith / modular monolith / microservices / functions) for this workload's change rate and scale? Over-decomposition is a failure, not a virtue.
- Elasticity & Scaling: Does the option scale to match the traffic pattern? Spiky/bursty workloads favor serverless or autoscaling; steady high-throughput workloads often favor provisioned capacity.
- Managed Services Leverage: Does the option offload undifferentiated heavy lifting (patching, HA, backups) to the provider, or does it create operational burden the team must own?
- Operational Maturity Fit: Does the option match the team's current skills and on-call capacity? A serverless event mesh is the wrong answer for a team with no distributed-systems debugging experience.
Step 3: Trade-off Analysis
For the leading options, make the trade-offs explicit across these axes:
- Operational burden vs. control: Managed services reduce burden but reduce tuning control and increase provider dependency
- Cost model shift: CapEx → OpEx, fixed → consumption-based; flag where consumption pricing could spike with scale
- Lock-in vs. velocity: Quantify the lock-in (proprietary APIs, data egress, migration cost) against the speed gained
- Latency, cold-start, and statefulness: Flag serverless cold-start risk and stateful-workload mismatch where relevant
- Failure modes: How does each option fail, and is the failure mode acceptable for this workload's criticality?
Be opinionated — name which trade-offs are acceptable here and which are dealbreakers.
Step 4: Identify Risks and Anti-Patterns
Flag any of the following if present in the leading option:
- Microservices proposed for a workload with no independent deployment or scaling need (distributed monolith risk)
- Serverless for latency-critical or long-running compute
- Self-managing a service that a mature managed equivalent exists for, without a control-based justification
- A choice that exceeds the team's operational maturity by more than one step
- Single-provider lock-in on a capability with a hard portability requirement
For each flagged risk, give a severity (High / Medium / Low) and a mitigation.
Step 5: Produce the Architecture Decision Record
Render the final ADR in standard format:
- Title: ADR-NNN — short decision name
- Status: Proposed
- Context: The framing from Step 1
- Decision: The recommended option, stated as a committed choice
- Consequences: Positive consequences, negative consequences, and risks accepted
- Alternatives Considered: Each rejected option with the one-line reason it was rejected
Step 6: Recommendation
State one recommended option clearly. Give the reasoning in 2–3 sentences tied to the pillar scores and trade-offs. If the recommendation is conditional (e.g., "managed Kubernetes if headcount grows; serverless otherwise"), state the condition explicitly. Do not hedge into "it depends" without resolving the dependency.
Output Format
- Structure: Context framing → pillar scorecard table → trade-off analysis → risk flags → formal ADR block → recommendation
- Length: 900–1,300 words
- Format: Structured document; pillar scores as a table (option × pillar); ADR rendered in standard ADR block format
- Sections: Decision Context → Cloud-Native Pillar Scorecard → Trade-off Analysis → Risks & Anti-Patterns → Architecture Decision Record → Recommendation
- Tone: Principal architect reviewing a peer's proposal — direct, evidence-based, willing to call a bad idea a bad idea
Quality Checklist
Before delivering output, verify:
- [ ] Every candidate option is scored against all five pillars (count: options × 5 scores)
- [ ] Each pillar score includes workload-specific reasoning, not a generic statement
- [ ] At least three trade-off axes are addressed with named consequences
- [ ] The ADR block contains all six standard fields (Title, Status, Context, Decision, Consequences, Alternatives Considered)
- [ ] Each flagged risk has a severity and a concrete mitigation
- [ ] The final recommendation names one option (or one conditional rule) without hedging
Notes
- Cloud-native is a means, not the goal — a modular monolith on managed infrastructure is often the right cloud-native answer, and "microservices everywhere" is the most common expensive mistake at this level
- Match the recommendation to the team's operational maturity; the best architecture the team cannot operate is the wrong architecture
- When two options score nearly identically, break the tie on reversibility — prefer the decision that is cheaper to undo
- The ADR should be self-contained enough that an engineer joining in two years understands why the choice was made without additional context
How to use this skill
This file is a Claude Code skill in Anthropic's standard format — markdown with YAML frontmatter at the top.
Installing in Claude Code:
~/.claude/skills/<folder-name>/SKILL.md— auto-loads in every session anywhere on your machine (recommended for skills you'll use across multiple projects)<your-project>/.claude/skills/<folder-name>/SKILL.md— auto-loads only when working in that project (recommended for project-specific skills)
Restart Claude Code or open a new session to register.
Using in Claude.ai, ChatGPT, Gemini, or other AI tools:
- Drag this file into a new chat, or copy and paste its contents
- Send your task or request as your next message — the AI will apply the skill where it fits
For Claude Code skill details: https://docs.anthropic.com/en/docs/claude-code/skills