Skip to main content
rule CX Codex

aws-well-architected-framework-review — Claude Code rule

aws-well-architected-framework-review runs a full Well-Architected review over your code and IaC: six pillars, findings tied to file and line, a report with a fix plan.

MIT-0 ★ 280 updated 2026-10-06

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/rules/aws-well-architected-framework-review.md
Open on GitHub

What aws-well-architected-framework-review does

The rule fires when you ask for an architecture review, a WA assessment, or mention Well-Architected. Scope comes first: workload name, directories to read, criticality tier, pain points. Then it walks every bit of infrastructure code it finds: CDK, CloudFormation, Terraform, SAM, Serverless Framework, CI/CD pipeline definitions, monitoring configs. It draws a PlantUML diagram of components and data flows. Application code gets its own pass — entry points, retries, auth, tracing.

Six pillars follow: operational excellence, security, reliability, performance efficiency, cost optimization, sustainability. Checks stay narrow: wildcard "Action": "*", 0.0.0.0/0 on ports other than 443 and 80, TLS below 1.2, unencrypted stores, stateful resources with no backups. Each entry gets a status, a file and line reference, the gap and the risk. Impact × likelihood sets severity; cross-pillar conflicts get a section of their own.

You get a report: executive summary, pillar scorecard 1–5, findings with a copy-ready fix in the project's IaC dialect (AWS CLI when there is no IaC), and a plan split into Quick Wins, Foundation, Strategic. No file-and-line evidence, no finding; where code cannot settle it, the status is Cannot Determine. On Cline the file sits under .clinerules/.

What it helps with

  • run a workload through all six Well-Architected pillars and get 1–5 scores
  • catch open security groups and unencrypted stores in your IaC
  • get a PlantUML diagram of the architecture from CDK or Terraform
  • sort findings by impact × likelihood
  • grab copy-ready fix snippets in the project's IaC dialect

Example prompts for the agent

  • Run a Well-Architected review of the orders-api workload, criticality high, cost is the main worry.
  • Do a WA assessment of this repo: Terraform lives in infra/, app code in src/.
  • Score the architecture against the six pillars and show findings with file and line references.

How to install aws-well-architected-framework-review

Manually: put the files in place

.claude/rules/aws-well-architected-framework-review.md

The paths frontmatter field limits the files

Step by step, with commands for each platform: AGENTS.md vs CLAUDE.md: what they are and which one to use

Questions about aws-well-architected-framework-review

How do I install aws-well-architected-framework-review in Claude Code?

Copy the rule file to .claude/rules/aws-well-architected-framework-review.md at the root of your project.

What does aws-well-architected-framework-review do?

It reviews a workload against the AWS Well-Architected Framework: reads your IaC and application code, scores the six pillars, ranks risk, and returns a report with fixes.

Which Well-Architected lenses does it recognise?

Serverless, SaaS, Data Analytics, ML, IoT, Containers, Games, Financial Services and Healthcare. If the lens is obvious from the code, it gets noted in the report.

Source text

aws-well-architected-framework-review.md · MIT-0
---
description: Run a full Well-Architected Framework review when the user asks for an architecture review, WA assessment, or mentions "Well-Architected review". Analyzes code, IaC, and configurations to produce evidence-backed findings.
globs:
alwaysApply: false
---

# Well-Architected Review Skill

When the user requests a WA review, follow these steps:

## Step 1: Define scope

Ask for: workload name, code packages/directories to analyze, business criticality (critical/high/standard/low), and pain points.

If you are already in a codebase with IaC, skip the prompt and proceed with discovery.

Determine if a specialized WA Lens applies (Serverless, SaaS, Data Analytics, ML, IoT, Containers, Games, Financial Services, Healthcare). If obvious from code, note it.

## Step 2: Infrastructure Discovery

Analyze ALL infrastructure-as-code in the codebase:

- CDK, CloudFormation, Terraform, SAM, Serverless Framework
- CI/CD pipeline definitions
- Monitoring configurations (CloudWatch alarms, dashboards)
- Deployment configurations

For each resource, document: type, configuration, file path and line numbers, security/resilience/cost relevance.

Create a PlantUML architecture diagram showing components, data flows, and boundaries.

## Step 3: Application Architecture Discovery

Analyze application code for:

- Entry points (API handlers, event processors, scheduled tasks)
- Service communication patterns (sync/async, retries, timeouts, circuit breakers)
- Data access patterns and error handling
- Authentication/authorization logic
- Observability instrumentation

## Step 4: Evaluate each pillar with code evidence

For each pillar, assess against WA Framework questions. Every finding MUST include:

- **Status**: Implemented / Partially Implemented / Not Implemented / Cannot Determine
- **Evidence**: specific file paths and line numbers
- **Gaps**: what's missing
- **Risk**: what could go wrong

### Operational Excellence

- OPS 4 — Observability: structured logging, tracing, custom metrics
- OPS 5 — Reduce defects: automated testing, linting, staged deployments
- OPS 6 — Deployment risk: canary/blue-green, feature flags, rollback
- OPS 8 — Workload health: dashboards, composite alarms
- OPS 10 — Event management: event routing, automated remediation

### Security

- SEC 3 — Permissions: least privilege. Flag `"Action": "*"` or `"Resource": "*"` on mutating actions
- SEC 5 — Network: VPC design, security groups. Flag `0.0.0.0/0` on non-443/80 ports
- SEC 8 — Data at rest: encryption on ALL stores. Flag unencrypted storage
- SEC 9 — Data in transit: TLS enforcement. Flag TLS < 1.2
- SEC 2/3 — Identity: IAM roles, credential management. Flag hardcoded secrets

### Reliability

- REL 2 — Network topology: multi-AZ, subnet distribution
- REL 3 — Demand: auto-scaling, capacity modes. Flag compute without scaling
- REL 4 — Distributed interactions: retries, timeouts, idempotency
- REL 9 — Backup: automated backups, PITR. Flag stateful resources without backups
- REL 11 — Component failures: redundancy, failover
- REL 13 — DR: cross-region resources, DR automation

### Performance Efficiency

- PERF 1 — Resource selection: instance types, Graviton usage
- PERF 4 — Database: read replicas, connection pooling
- PERF 5 — Networking: CloudFront, VPC endpoints
- PERF 8 — Tradeoffs: caching, async patterns

### Cost Optimization

- COST 4 — Decommission: lifecycle policies. Flag "never expire" logs
- COST 5 — Service selection: pricing alignment. Flag over-provisioned resources
- COST 8 — Data transfer: VPC endpoints vs NAT Gateway

### Sustainability

- SUS 2 — Scale-to-zero, scheduled scaling
- SUS 4 — Data tiering, lifecycle, compression
- SUS 5 — Flag x86 where Graviton available

## Step 5: Risk Assessment

Assess each finding using Impact × Likelihood matrix:

| Impact   | Likelihood | Risk Level |
|----------|------------|------------|
| Severe   | High       | Critical   |
| Severe   | Medium     | High       |
| Severe   | Low        | High       |
| Moderate | High       | High       |
| Moderate | Medium     | Medium     |
| Moderate | Low        | Medium     |
| Minor    | High       | Medium     |
| Minor    | Medium     | Low        |
| Minor    | Low        | Low        |

Identify cross-pillar conflicts (security vs performance, cost vs reliability).

## Step 6: Output report

Structure:

- Executive Summary (date, workload, criticality, lens, findings count, overall maturity 1-5)
- Architecture Overview (PlantUML diagram)
- Pillar Scorecard (table: pillar, score 1-5, key strength, key gap)
- Critical and High Risk Findings (ID, pillar, title, evidence file:line, impact, recommendation, fix — ready-to-copy snippet in the workload's IaC dialect, AWS CLI when no IaC, report-only, effort, AWS services)
- Medium Risk Findings (condensed, each with its fix snippet)
- Low Risk Findings (summary table)
- Cross-Pillar Trade-offs
- Prioritized Remediation Plan (Quick Wins < 1 week, Foundation 1-4 weeks, Strategic 1-3 months)
- Next Steps (top 5 concrete actions)

## Calibration

- Mature workloads (multi-AZ, encryption, CI/CD, monitoring, scaling) should score 4+ — don't over-penalize
- Every finding MUST have code evidence — no generic recommendations
- "Cannot Determine" is valid when code alone is insufficient
- Acknowledge strengths before gaps
- Match expectations to business criticality tier

<!--
Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
SPDX-License-Identifier: MIT-0
-->

© aws-samples · MIT-0 · aws-samples/sample-well-architected-skills-and-steering

Similar IDE rules

All IDE rules for Cloud: AWS, Azure, GCP →

From the same set19

The whole set →
sustainability-optimization sustainability-optimization runs an AWS Well-Architected review limited to the Sustainability pillar and returns a report with a resource-efficiency table and a scorecard. CX Codex +1 ★ 280repo stars prompt prompt audits AWS workloads against the Well-Architected Framework, surfacing risks in code and IaC without modifying repository files directly. CX Codex +1 ★ 280repo stars well-architected This rule applies AWS Well-Architected principles to architecture reviews, infrastructure code, and design advice. It helps agents organize findings and explain trade-offs. CX Codex +1 ★ 280repo stars wa-builder wa-builder explains AWS Well-Architected concepts for your project and generates annotated diagrams, decision trees, and remediation roadmaps. CX Codex +1 ★ 280repo stars migration-readiness The migration-readiness command analyzes a codebase to assess a workload’s readiness for AWS migration. Use it to surface blockers and map out a component-by-component migration plan. CX Codex +1 ★ 280repo stars wa-guardrails wa-guardrails generates preventive AWS Well-Architected guardrails, including CI checks, AWS Config rules, SCPs, and CloudWatch alarms, to block regressions. CX Codex +1 ★ 280repo stars aws-well-architected-framework-review aws-well-architected-framework-review is a Claude Code command that reviews AWS workloads against the Well-Architected Framework, using code and infrastructure settings as evidence. CX Codex +1 ★ 280repo stars wa-builder wa-builder teaches AWS Well-Architected against your own workload, then generates commit-ready artifacts: an annotated architecture diagram, decision trees and an improvement roadmap. CX Codex +1 ★ 280repo stars

Project sponsors

Companies that keep this analytics open