Introduction

Products and their context change constantly.
Architectures must evolve with them.

Yet ensuring systems follow best practices remains largely manual.

The barriers to creating our own standards are too high, so we adopt generic industry ones.
Best practices live in long PDFs, written without your context.
Compliance becomes a checkbox exercise, replacing informed decisions with overly broad rules.
Reviews happen late, risking expensive mistakes and incidents.
All systems are now distributed, but best practice knowledge is not.
Teams run hybrid, multi-vendor systems - but our tools reason about them one property at a time.

Well-Architected 2 (WA2) is an architecture reasoning system, not a compliance scanner.

WA2 builds a graph of your system and evaluates it against your intent.

As you build or evolve architectures, WA2 guides you, explaining best practices, what they imply, and how their consequences ripple through your architecture.

Instead of asking:

• Have you backed up this S3 bucket?

WA2 determines:

• Are your critical stores protected from data loss?

What WA2 is

WA2 consists of:

• Book: this guide, explaining both the thinking and the tool.
• Intents language: a small language for expressing architectural policies.
• Framework: vendor-independent best practices built on architectural concepts.
• Tooling:
  • CLI: enforcement in CI/CD.
  • Extension: editor integration that guides you around problems as you build.

The Big Idea

WA2 separates:

• How a system is implemented

from

• What it must guarantee

Rules add evidence to a shared graph.
Policies evaluate that evidence.

Vendor-specific logic produces facts.
Architectural intent consumes them.

This keeps governance clean and portable.
And allows us to establish an evidence chain - back to source code.

Why This Matters

Architectures have grown far more complex.
Our tooling has not kept up.

WA2 changes how we think about architecture:

• Architecture becomes queryable.
• Best practices become executable.
• Governance becomes scalable.
• Vendor specifics become interchangeable.
• Developers get guidance in context.

Current Scope

Warning

WA2 in a work in progress, and should not be used for production workloads
As WA2 evolves we continue to discover things that leads to breaking changes, its very volatile.
It’s absolutely is missing features, lacks consistency, and has bugs - beware!
This book is updated in parallel with tooling and framework, so check back for progress.

• Today WA2 supports AWS CloudFormation (JSON & YAML).
• It is designed to support additional systems over time.