wa-guardrails

架构完善性护栏

此技能会生成预防性和侦测性控制，确保工作负载长期保持架构完善。与评估技能（用于发现差距）或修复技能（用于一次性修复特定发现）不同，护栏会将最佳实践写成规范，自动阻止或标记不合规的变更——在 CI 中、部署时以及持续在账户中执行。

你将生成的内容： 可直接提交的控制文件（Config 规则、SCP、CI 策略检查、警报），每项都关联到其所执行的 WA 问题/最佳实践 ID，并注明该控制是预防性（阻止不当变更）还是侦测性（事后标记）。

第 1 步：收集上下文

询问用户（跳过已提供或可从代码库推断的信息）：

我可以生成护栏，帮助你的工作负载保持架构完善。请提供以下信息：

• 工作负载名称和代码包/目录（IaC、CI/CD 配置）
• IaC 方言：CDK（使用哪种语言）、CloudFormation、Terraform、SAM，或混合使用
• 控制措施的来源：先前的 /aws-well-architected-framework-review 或评估结果、具体关注点，或“扫描并提出建议”
• 可用的强制执行点：CI 流水线（使用哪种）、AWS Organizations/SCP、AWS Config、账户级管理员——这样控制措施就能针对实际可部署的内容
• 优先考虑的支柱（可选；默认：安全性和可靠性）

如果当前位于代码库中，请直接继续，并根据现有文件推断 IaC 方言和 CI 系统。

第 2 步：发现——要执行的控制措施

根据以下两种输入之一，确定要生成的控制措施：

路径 A——基于评估（优先）： 解析先前的评审，提取发现项、所属支柱、严重性、证据（文件:行），以及引用的最佳实践 ID。每个高危/严重发现都应成为候选护栏，以防同一差距再次出现。

路径 B——独立扫描： 分析 IaC，识别实际使用且值得制定控制措施的配置——存储加密、公共访问、IAM 范围、多可用区、备份、日志记录、TLS、标签。将每项配置映射到相关的 WA 最佳实践。

生成一份控制措施候选列表：逐项记录支柱、WA 问题/BP ID、适用的资源类型、当前状态（合规/不合规/不存在），以及适用的强制执行点（CI 检查、Config 规则、SCP、警报）。

第 3 步：为每项控制措施选择预防性或侦测性方式

对于每项候选控制措施，选择用户可用的强制执行点所允许的最强控制方式。优先选择预防性（在变更发布前阻止不当操作），而非侦测性（事后发现）。请参考以下决策指南：

• 能否在部署前通过 IaC 检查发现配置错误？→ CI 策略检查（CDK Aspect、cfn-guard/cfn-lint、Terraform OPA/Sentinel）。最强且成本最低。
• 是否必须无论由谁部署都在整个组织范围内阻止？→ SCP 或权限边界。
• 是否只能在实际运行的资源上进行观测（例如偏移、运行时状态）？→ AWS Config 规则（侦测性；只有在用户确认后才添加自动修复）。
• 是否属于持续的可靠性/成本/性能信号？→ CloudWatch 指标 + 警报。

如果现有的强制执行点无法实施某项控制措施，请明确说明，而不是生成无法运行的控制措施。

第 4 步：生成控制措施

将每项选定的控制措施生成为可直接提交的代码，并遵循工作负载现有的方言和约定。每项控制措施 MUST：

• 注明其执行的 WA 问题/BP ID（例如 SEC 8、REL 9）
• 标记为 🛡️ Preventive 或 🔍 Detective
• 用一句话说明其会阻止/标记什么，以及这为何重要

根据工作负载情况，涵盖以下适用内容：

安全（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 开放时导致合成失败的 CDK Aspect。

可靠性（REL） — rds-multi-az-support、dynamodb-pitr-enabled、db-instance-backup-enabled（Config）；要求有状态资源启用 DeletionProtection 的 cfn-guard 规则；针对 DLQ 深度的告警。

卓越运营（OPS） — 要求包含标签（owner、cost-center、environment）的 CI 检查；要求设置 CloudWatch 日志保留期的 Config 规则；防止在 IaC 之外手动更改的 SCP。

成本（COST） — 标记实例类型或容量模式不在批准列表中的 CI 检查；预算/异常告警。

性能 / 可持续性（PERF/SUS） — 在适用情况下优先选择 Graviton/托管服务的 CI 检查。

将每项控制措施的代码片段放入带有目标文件名的围栏代码块中，以便用户可以直接提交。匹配工作负载的方言 — 以下是三种最常见形式的示例：

侦测式 — 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 }

预防式 — 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}`);
    }
  }
}

预防式 — cfn-guard 规则（REL 9，有状态资源需要启用删除保护）：

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

第 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 问题/BP ID，并保持文档简短，便于纳入始终启用的上下文而不臃肿。

第 7 步：提供后续选项

你希望我：

• 生成用于运行策略检查的 CI 工作流配置（GitHub Actions / CodePipeline 步骤）吗？
• 编写治理指导文档（CLAUDE.md / .cursor/rules/ / .kiro/steering/），为你的 AI Agent 记录这些标准吗？
• 为侦测式 Config 规则添加自动修复功能（并进行安全审查）吗？
• 修复现有违规项（修复当前代码），即这些防护措施会阻止的问题吗？
• 将某项控制措施从警告模式收紧为阻止模式吗？

校准指南

• 优先采用预防性控制（在 CI/IaC 中发现问题），而非检测性控制——前者成本更低，也能在问题发布前阻止它；只有当问题只能在实时资源上发现时，才退而采用检测性控制。
• 如果用户没有相应的执行点，切勿生成控制——应说明该控制无法强制执行，以及需要什么条件。
• 先以警告/日志模式推出预防性控制。 一开始就建议使用硬性 block 或 Deny SCP，可能会破坏现有流水线——应指出这一风险并分阶段实施。
• 自动修复具有破坏性：只有用户明确提出要求时才生成，并附上安全/回滚说明。
• 将每项控制关联到一个 WA Question/BP ID，以便构建者追溯其依据——没有“为什么”的护栏，一旦造成不便就会被禁用。
• 不要生成过多控制：一组精简且高价值、团队会持续保留的控制，胜过 50 条会被静音的嘈杂规则。
• 遵循工作负载现有的方言和惯例——对于 CDK 应用，生成 CDK Aspects；对于 CloudFormation，使用 cfn-guard；对于 Terraform，使用 OPA/Sentinel；不要混用范式。
• 治理指导文档是对控制的补充，而非替代——只要存在机器可强制执行的控制，就优先使用它；文档则用于说明代码无法表达的内容。文档应足够简洁，以便始终作为上下文使用。