wa-guardrails

Well-Architected ガードレール

このスキルは、ワークロードが長期にわたって Well-Architected な状態を維持できるように、予防的および発見的なコントロールを生成します。ギャップを見つける評価スキルや、特定の検出事項を一度だけ修正する修復とは異なり、ガードレールはベストプラクティスをルール化し、準拠していない変更を CI、デプロイ時、アカウント内で継続的に自動ブロックまたは検出します。

作成するもの： コミット可能なコントロールファイル（Config ルール、SCP、CI ポリシーチェック、アラーム）です。それぞれに適用対象の WA Question／Best Practice ID と、そのコントロールが予防的（不適切な変更をブロック）か発見的（事後に検出）かを記載します。

Step 1: コンテキストを収集する

ユーザーに尋ねます（すでに提供されている情報、またはコードベースから推測できる情報は省略します）。

ワークロードが Well-Architected な状態を維持できるように、ガードレールを生成できます。次の情報をお知らせください。

• ワークロード名とコードのパッケージ／ディレクトリ（IaC、CI/CD 設定）
• IaC の記法：CDK（使用言語も記載）、CloudFormation、Terraform、SAM、または混在
• コントロールのソース：以前の /aws-well-architected-framework-review または評価の出力、具体的な懸念事項、または「スキャンして提案」
• 利用可能な適用ポイント：CI パイプライン（使用しているもの）、AWS Organizations／SCP、AWS Config、アカウントレベルの管理者。実際にデプロイできるものを対象にコントロールを設定します。
• 優先する柱（任意。デフォルト：セキュリティと信頼性）

コードベース内にいる場合は、そのまま進め、存在するファイルから IaC の記法と CI システムを推測してください。

Step 2: 検出 — 適用するコントロール

次のいずれかの入力から、生成するコントロールを決定します。

パス A — 評価に基づく（推奨）： 以前のレビューを解析し、検出事項、その柱、重大度、根拠（ファイル：行）、引用されている Best Practice ID を抽出します。重大または高の検出事項はそれぞれ候補となるガードレールとし、同じギャップが再発しないようにします。

パス B — 単独スキャン： IaC を分析し、実際に使用されている、コントロールの対象となる設定（ストレージの暗号化、パブリックアクセス、IAM の範囲、マルチ AZ、バックアップ、ログ記録、TLS、タグ付け）を特定します。それぞれを関連する WA Best Practice に対応付けます。

コントロール候補の一覧を作成します。それぞれについて、柱、WA Question／BP ID、適用対象のリソースタイプ、現在の状態（準拠／非準拠／未設定）、適切な適用ポイント（CI チェック、Config ルール、SCP、アラーム）を記録します。

Step 3: コントロールごとに予防的か発見的かを選択する

各候補について、ユーザーが利用できる適用ポイントで可能な、最も強力なコントロールを選びます。発見的（事後に検出）よりも、予防的（リリース前に不適切な変更を防止）を優先してください。次の指針を使用します。

• デプロイ前に IaC で設定ミスを検出できますか？ → CI ポリシーチェック（CDK Aspect、cfn-guard／cfn-lint、Terraform OPA／Sentinel）。最も強力で、最も低コストです。
• デプロイするユーザーにかかわらず、組織全体でブロックする必要がありますか？ → SCP またはアクセス許可境界。
• ライブリソースでのみ確認できますか（ドリフト、実行時の状態など）？ → AWS Config ルール（発見的。自動修復を追加するのは、ユーザーが確認した場合に限ります）。
• 継続的な信頼性、コスト、パフォーマンスのシグナルですか？ → CloudWatch メトリクス + アラーム。

利用可能な適用ポイントでは適用できないコントロールがある場合、実行されないコントロールを出力せず、その旨を明示してください。

Step 4: コントロールを生成する

選択したすべてのコントロールを、ワークロードで既に使われている形式と規約に従い、そのままコミットできるコードとして生成します。各コントロールには必ず次の内容を含めます。

• 適用対象となる WA Question/BP ID を記載する（例：SEC 8、REL 9）
• 🛡️ Preventive または 🔍 Detective とラベル付けする
• ブロック／検出する内容と、その重要性を1行で説明する

ワークロードに応じて、次の項目をカバーしてください。

Security（SEC） — 例：s3-bucket-server-side-encryption-enabled、s3-bucket-public-read-prohibited、iam-policy-no-statements-with-admin-access（Config）；暗号化されていないリソースの作成や CloudTrail の無効化を拒否する SCP；非 Web ポートで 0.0.0.0/0 に公開されたセキュリティグループがある場合に synth を失敗させる CDK Aspect。

Reliability（REL） — rds-multi-az-support、dynamodb-pitr-enabled、db-instance-backup-enabled（Config）；ステートフルリソースに DeletionProtection を必須とする cfn-guard ルール；DLQ の深度に関するアラーム。

Operational Excellence（OPS） — タグ（owner、cost-center、environment）を必須とする CI チェック；CloudWatch ログの保持期間を必須とする Config ルール；IaC 外での手動変更を防止する SCP。

Cost（COST） — 承認済みリスト以外のインスタンスタイプやキャパシティモードを検出する CI チェック；予算／異常検知アラーム。

Performance / Sustainability（PERF/SUS） — 該当する場合に Graviton／マネージドサービスを優先する CI チェック。

各コントロールのスニペットは、対象ファイル名を付けたフェンス付きコードブロックで示し、そのままコミットできるようにしてください。ワークロードの形式に合わせてください。次は最も一般的な3つの形式の例です。

Detective — AWS Config マネージドルール（SEC 8、保存時の暗号化）、CloudFormation：

# guardrails/config-rules.yaml
Resources:
  S3EncryptionEnabled:                      # 🔍 Detective — flags any S3 bucket without SSE
    Type: AWS::Config::ConfigRule
    Properties:
      ConfigRuleName: s3-bucket-server-side-encryption-enabled
      Source: { Owner: AWS, SourceIdentifier: S3_BUCKET_SERVER_SIDE_ENCRYPTION_ENABLED }

Preventive — CDK Aspect（SEC 5、公開されたセキュリティグループなし）、TypeScript：

// guardrails/no-open-sg.aspect.ts
import { IAspect, Annotations } from "aws-cdk-lib";
import { CfnSecurityGroupIngress } from "aws-cdk-lib/aws-ec2";
import { IConstruct } from "constructs";

// 🛡️ Preventive — fails `cdk synth` on 0.0.0.0/0 ingress to non-web ports
export class NoOpenIngress implements IAspect {
  visit(node: IConstruct): void {
    if (node instanceof CfnSecurityGroupIngress &&
        node.cidrIp === "0.0.0.0/0" && ![80, 443].includes(Number(node.fromPort))) {
      Annotations.of(node).addError(`SEC 5: security group open to 0.0.0.0/0 on port ${node.fromPort}`);
    }
  }
}

Preventive — cfn-guard ルール（REL 9、ステートフルリソースには削除保護が必要）：

# guardrails/reliability.guard
# 🛡️ Preventive — blocks RDS instances without Multi-AZ + deletion protection
AWS::RDS::DBInstance {
  Properties { MultiAZ == true  DeletionProtection == true }
}

Step 5: ガードレール計画を作成する

次の構成で成果物を出力します。

# Well-Architected Guardrails: {Workload Name}

## Summary
- **IaC dialect**: {CDK/CloudFormation/Terraform/SAM}
- **Enforcement points used**: {CI / Config / SCP / alarms}
- **Source**: {prior review / standalone scan}
- **Controls generated**: {N} ({P} preventive, {D} detective) across {pillars}

## Controls by pillar

### {Pillar} — {WA Question/BP ID}
- **Control**: {name}  |  🛡️ Preventive / 🔍 Detective  |  Enforcement: {CI / Config / SCP / alarm}
- **Blocks/flags**: {what, and why it matters}
- **File**: `{path}`
  ```{lang}
  {ready-to-commit snippet}

• カバレッジのギャップ（該当する場合）：{このコントロールでは検出できない内容}

ロールアウト計画

順序	コントロール	適用方法	誤検出のリスク	備考
{予防的な CI チェックと SCP は警告／ログモードから始め、問題がなくなった後にブロックモードへ移行します。}

検証

{各コントロールの動作を確認する方法。例：ブランチで既知の不正な変更を試し、CI が失敗することを確認する；Config ルールのコンプライアンスステータスを確認する。}

対象外

{利用可能な適用ポイントでは実装できないコントロールと、それに必要なもの。}

## Step 6: Offer a governance steering doc

Beyond machine-enforced controls, offer to capture the same standards as a **human- and agent-readable governance doc** — the prose counterpart to the guardrails. This is useful for the standards a control can't fully express (design conventions, review expectations) and for teams that want an always-on policy their AI coding agent will follow.

Generate it on request as a steering file the agent loads automatically (e.g. `.kiro/steering/`, `CLAUDE.md`, `.cursor/rules/`), structured as:

```markdown
# {Workload} — Well-Architected Guardrails (Governance)

## Enforced automatically
{One line per machine control, linking the rule file and its WA BP ID — so readers know what is already gated in CI/Config.}

## Conventions to follow (not auto-enforced)
- {Pillar} — {convention}, because {WA BP ID rationale}. {How a reviewer/agent checks it.}

## When proposing or reviewing changes to this workload
- {Standing instruction, e.g. "new data stores MUST set encryption + backups before merge (SEC 8 / REL 9)"}

各記述を WA Question/BP ID に結び付け、常時参照するコンテキストに収まるよう、文書を簡潔に保ってください。

Step 7: 次の対応を提案する

次の対応を行いますか？

• ポリシーチェックを実行する CI ワークフロー（GitHub Actions / CodePipeline のステップ）を生成する
• AI エージェント向けに、これらの標準をまとめたガバナンス方針ドキュメント（CLAUDE.md / .cursor/rules/ / .kiro/steering/）を作成する
• Detective Config ルールに自動修復を追加する（安全性レビュー付き）
• 既存の違反を修正する（現在のコードを修復する）
• コントロールを警告モードからブロックモードに強化する

キャリブレーションのガイダンス

• 予防的なコントロール（CI／IaC で検出する）を検知的なコントロールより優先してください。コストが低く、問題がリリースされる前に防止できます。問題が稼働中のリソースでしか確認できない場合に限り、検知的なコントロールを使用してください。
• ユーザーが利用できない強制ポイントに対するコントロールは、決して出力しないでください。強制できないことと、代わりに必要なものを伝えてください。
• 予防的なコントロールは、まず警告／ログモードで導入してください。 初日からハードな block や Deny SCP を推奨すると、既存のパイプラインを壊すおそれがあります。このリスクを伝え、段階的に導入してください。
• 自動修復は破壊的です。ユーザーが明示的に求めた場合にのみ生成し、安全性とロールバックに関する注記を含めてください。
• すべてのコントロールを WA の質問／BP ID に関連付け、ビルダーが根拠を追跡できるようにしてください。「なぜ」がわからないガードレールは、都合が悪くなったときに最初に無効化されます。
• 生成しすぎないでください。チームが使い続ける、価値の高いコントロールに絞ったセットのほうが、ミュートされるノイズの多いルールを 50 個並べるより効果的です。
• ワークロードで既に使われている方言や規約に従ってください。CDK アプリには CDK Aspects、CloudFormation には cfn-guard、Terraform には OPA／Sentinel を出力し、パラダイムを混在させないでください。
• ガバナンスの方針を定めるドキュメントはコントロールを補完するものであり、置き換えるものではありません。機械的に強制できるコントロールがある場合はそちらを優先し、コードでは表現できない事項にドキュメントを活用してください。常時参照するコンテキストとして使えるよう、簡潔に保ってください。