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
.claude/rules/aws-well-architected-framework-review.mdWhat 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-apiworkload, criticality high, cost is the main worry. - Do a WA assessment of this repo: Terraform lives in
infra/, app code insrc/. - 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.mdThe paths frontmatter field limits the files
AGENTS.md
Codex reads AGENTS.md: paste the rule text there
Manually: put the files in place
.cursor/rules/aws-well-architected-framework-review.mdcFrontmatter: description, globs, alwaysApply
Manually: put the files in place
.github/instructions/aws-well-architected-framework-review.instructions.mdThe applyTo field sets which files it applies to
Manually: put the files in place
.devin/rules/aws-well-architected-framework-review.mdManually: put the files in place
.clinerules/aws-well-architected-framework-review.mdStep 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