Shift-Left Well-Architected Reviews Inside Your Kiro IDE
A hands-on tutorial: catch AWS architecture gaps before you commit — using a Well-Architected steering doc in Kiro.
Why "shift-left" matters for architecture
We've shifted testing left. We've shifted security left. But architecture reviews? Those still mostly happen after the code is written — in a PR review, or worse, in a post-incident retro.
The result is predictable: the same Well-Architected gaps (unencrypted storage, missing retries, single-AZ deployments, no cost guardrails) show up again and again, caught late, fixed expensively.
With an AI coding agent like Kiro, we can finally move that review to the moment of authoring. Here's how.
What you'll build
By the end of this tutorial, Kiro will:
- Know the AWS Well-Architected Framework's key questions across all pillars.
- Flag architecture gaps as you write infrastructure code.
- Explain why something is a risk and suggest the Well-Architected-aligned fix.
All without leaving your IDE, and without any AWS credentials.
Step 1 — Add the Well-Architected steering doc
Drop the Well-Architected steering document into your Kiro project's steering directory. This is the authoritative guidance layer — it tells Kiro how to think about your code through the lens of the six pillars (Operational Excellence, Security, Reliability, Performance Efficiency, Cost Optimization, and Sustainability).
1
2
3
4
your-project/
└── .kiro/
└── steering/
└── wa-review.md ← the steering docBecause it's steering (not a one-off prompt), Kiro applies it consistently across every interaction in the project — no re-prompting.
Step 2 — Write some infrastructure code
Let's say you ask Kiro to create an S3 bucket for storing customer exports. With the steering doc in place, instead of a bare bucket, Kiro proactively raises:
- Security: "This bucket has no encryption or bucket policy. Well-Architected (SEC08) recommends encryption at rest — want me to add SSE-KMS?"
- Reliability: "No versioning enabled. For customer data, consider versioning + lifecycle rules."
- Cost: "Add a lifecycle policy to transition old exports to a cheaper tier?"
You're getting a Well-Architected review in the editor, at authoring time.
Step 3 — Find gaps before you commit
The real magic is running a review pass before you commit. Ask Kiro:
"Review the infrastructure in this changeset against the Well-Architected Framework and list any gaps by pillar."
Kiro walks the diff, maps each resource to the relevant Well-Architected questions, and gives you a prioritized list of gaps — with fixes. No context-switching to a separate tool, no waiting for a reviewer.
Step 4 — Make it a habit
Wire this into your workflow:
- Keep the steering doc in version control so the whole team shares the same standards.
- Run the "review against Well-Architected" prompt as a pre-commit ritual.
- Treat Kiro's flags like linter warnings — resolve or consciously accept each one.
The payoff
This is the shift-left promise finally applied to architecture: the gaps get caught while the code is fresh in your head and cheap to fix, not three weeks later. Your reviews get faster because the obvious stuff is already handled. And your whole team codes to the same standard, consistently.
Wrapping up
Kiro turns 1 this week, and this is the kind of workflow that got me excited about it in the first place — not just generating code, but generating well-architected code, by default. Give the steering doc a try and let me know what gaps it catches in your projects.
Happy birthday, Kiro. 🎂
Get the steering doc: https://github.com/aws-samples/sample-well-architected-skills-and-steering · Questions? Drop them below 👇
Enjoyed reading this content? Let the author know!
Your likes, comments, shares, and saves help creators reach more builders.
Loading recommendations
Loading article