给 AI 编码工具装上 AWS 架构顾问的大脑

当开发者的 AI 助手开始"懂架构"

想象一下这个场景：团队刚完成一套无服务器微服务部署，开发者一边喝着咖啡，一边让 AI 帮他生成下一个 Lambda 函数。AI 流畅地写完了代码，还贴心地加上了错误处理。然而，这份代码隐藏着一个隐患——它没有设置重试机制，一旦上游服务短暂不可用，整条链路就会悄悄失败。更糟的是，代码里还留下了调试用的 print 语句，上了生产环境后 Performance Efficiency 支柱直接扣分。

这不是开发者的错。传统的架构审查是独立流程，要专门预约架构师、填写审查表格、等上几天才能拿到报告。而这个项目解决的核心问题是：让架构最佳实践，在写代码的那一刻，就被 AI 助手内化进去。

背景：AWS 优良架构框架的"AI 困境"

AWS Well-Architected Framework（WA Framework）是 AWS 官方推荐的架构评审方法论，涵盖六大支柱：

• 运营卓越（Operational Excellence）：自动化部署、可观测性、故障响应
• 安全（Security）：身份验证、授权、数据保护、合规性
• 可靠性（Reliability）：容错设计、灾备恢复、限流机制
• 性能效率（Performance Efficiency）：资源选型、弹性伸缩、监控调优
• 成本优化（Cost Optimization）：按需付费、右置资源、费用监控
• 可持续发展（Sustainability）：能源效率、减少浪费、托管服务

框架本身有 57 个核心问题和 307 条最佳实践（Best Practices），内容非常详尽。但问题在于：AI 编码工具在生成代码时，并不知道这些最佳实践的存在。 它们只是在完成用户指令，而用户往往也记不住每一条 WA 要求。

aws-samples/sample-well-architected-skills-and-steering 正是在这个交叉点诞生——它将 WA 框架"翻译"成 AI 编码工具能理解的指令集，让 AI 在写代码的每一个瞬间都带上架构意识。

类比：给 AI 配一个"架构陪练"

可以把传统的架构审查想象成"事后验尸"：代码写完了，架构师来挑毛病。而这个项目的思路更接近于"陪练式训练"：找一个技术全面的教练，在对练过程中实时纠正你的动作，最终让你形成肌肉记忆，不需要教练在场也能打出标准动作。

项目支持的 14 款主流 AI 编码工具 包括：Kiro、Kiro CLI、Claude Code、Cursor、Codex、Windsurf、GitHub Copilot、Gemini CLI、Antigravity、Junie、Amp、OpenClaw、Cortex Code、AWS DevOps Agent。无论团队用哪款工具，都可以用同一套指令集。

核心功能：三层指令体系

这个项目的架构设计非常清晰，分为 Steering（引导层）、Skills（技能层） 和 Adapters（适配层），各自承担不同职责。

Steering：常驻的架构意识

steering/well-architected.md 是 AI 的"常驻架构顾问"——每次对话都会被加载的上下文文件。它包含六大支柱的定义、设计原则，以及一张"意图路由表"：当用户提到"安全审查"时，路由到 security-assessment 技能；当用户提到"成本优化"时，路由到 cost-optimization-review 技能。这确保了 AI 不会在用户明确要求单支柱分析时，动不动就去做全量 WA 评审。

steering/wa-review.md 则定义了完整的 WA 评审流程：当用户说"帮我做个架构评审"时，AI 会依次要求提供工作负载名称、代码包路径、业务关键性等级、是否使用专业 WA Lens（如 Serverless、SaaS、机器学习等 27 种），然后分阶段执行基础设施发现、应用栈发现、逐支柱分析，最终输出带风险等级的修复计划。

Skills：独立的操作手册

每个 Skill 都是一个自包含的操作手册，以 SKILL.md 格式存储，包含：

Skill 名称	功能	适用场景
wa-review	全量 WA 评审（6 大支柱 × 57 问题）	全面了解系统架构健康度
security-assessment	安全态势深度评估	IAM 配置、加密、审计日志
reliability-improvement-plan	可靠性改进计划	SPOF 识别、灾备方案
cost-optimization-review	成本优化评审	右置资源、闲置资源、定价模型
performance-efficiency	性能效率评估	资源选型、伸缩策略、缓存
operational-excellence	运营卓越评估	CI/CD、可观测性、故障响应
sustainability-optimization	可持续性优化	能源效率、数据生命周期
wa-builder	WA 学习 + 可视化产物生成	生成带 WA 标注的架构图、决策树、路线图
wa-guardrails	预防性控制生成	AWS Config 规则、SCPs、CI 策略检查
wafr-facilitator	WAFR 会议主持	引导客户完成架构评审工作坊
migration-readiness	迁移就绪评估	7Rs 分析、依赖扫描、迁移计划

每个 Skill 的 SKILL.md 文件结构规范：包含 YAML frontmatter（name、description、version、not_for）、使用条件判断、分步骤操作流程、约束规则，以及按pillar-playbook 组织的 per-pillar 参考文件（307 条 BP 全部覆盖）。

Adapters：工具无关的最后一公里

这是整个项目最有工程含量的部分。同一个 wa-review Skill，通过 adapters/ 下的适配器文件，被转换成各工具的原生格式：

• Claude Code：写入 ~/.claude/skills/wa-review/SKILL.md + CLAUDE.md 配置
• Cursor：写入 .cursor/rules/ 下的 .md 文件
• Codex：写入 AGENTS.md + skills/wa-review/SKILL.md
• Windsurf：写入 .windsurfrules
• GitHub Copilot：写入 .github/copilot-instructions.md
• Kiro：写入 ~/.kiro/steering/ 和 ~/.kiro/skills/
• ……以此类推，覆盖全部 14 款工具

适配器的职责是"格式化翻译"——Skill 内容本身不变，只是输出位置和文件格式随工具而变。这保证了"一个 WA 知识源，所有工具同步更新"。

安装体验：一条命令搞定

项目提供两种安装方式，均无需手动 clone：

Linux/macOS：

curl -sL https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.sh | bash

Windows PowerShell：

powershell -ExecutionPolicy Bypass -Command "Invoke-WebRequest -Uri 'https://raw.githubusercontent.com/aws-samples/sample-well-architected-skills-and-steering/main/bootstrap.ps1' -OutFile bootstrap.ps1; .\bootstrap.ps1"

或者 clone 后用 install.sh，支持：

• 指定目标项目目录 ./install.sh ~/my-project --tool auto（auto 自动检测已安装的 AI 工具）
• 全局安装 ./install.sh --global --tool claude-code
• 符号链接模式 --symlink（源仓库更新后自动同步）
• 卸载 ./install.sh --uninstall --tool claude-code

安装脚本 install.sh 约 700 行，用 set -euo pipefail 严格错误处理，支持 --force 覆盖、--check-update 检查更新，是相当成熟的工程实践。

示例应用：故意植入问题的 IaC 靶场

项目在 examples/ 下提供了两个故意植入 WA 问题的 IaC 靶场，用于演示和评测：

• insecure-serverless-app-cdk/：CDK TypeScript 实现，约 20 个 WA 问题遍布 6 大支柱
• insecure-serverless-app-terraform/：Terraform 实现，约 17 个 WA 问题

evals/ 目录下还有完整的自动评测框架：通过 Bedrock 调用 Claude Opus 4 对 Skill 执行效果打分（LLM-as-judge），config.yaml 定义评测模型为 us.anthropic.claude-opus-4-8，run.py 是评测入口，grade.py 是评判器，report.py 输出评分。pyproject.toml 明确要求 Python >= 3.13，使用 boto3（AWS）和 openai（OpenAI）双 SDK。

争议与局限

1. 依赖 AWS 语境：虽然 Skill 内容本身是框架级别的，但示例 IaC、评测环境、参考文档大量围绕 AWS 生态展开。对于非 AWS 用户，上手门槛会比文档暗示的要高——用户需要理解 Lambda、DynamoDB、S3 等 AWS 概念，才能真正用好这些 Skill。

2. 安装的"副作用"：install.sh 会在用户项目目录或全局配置目录下创建 .kiro/、.claude/skills/、.cursor/rules/ 等目录和文件。用户可能不清楚这些文件何时被加载、是否会与已有配置冲突。对于有洁癖的开发者，这相当于在项目里埋了一堆隐藏文件。

3. Skill 版本同步：项目当前版本 1.3.0，WA Framework 本身也会更新（AWS 每半年大版本迭代），Skill 的参考文件需要定期同步。虽然 scripts/crawl-wa-framework.py 提供了自动化爬取脚本，但维护节奏依赖贡献者投入。

4. 评测结果的主观性：LLM-as-judge 评测依赖 prompt 设计，评测结果可能存在偏差（偏向于"看起来完整"的输出，而非真正有用的输出）。项目自己也在 README 中注明"This sample is provided for educational and demonstrative purposes. It is not intended for production use without additional review and testing"。

行业意义：AI Agent 编程规范化的先声

这个项目的更大意义在于，它代表了 AI Agent Skill 标准化 方向的早期实践。

2024 年底，skills.sh 规范（agentskills.io）开始推广，试图定义"如何给 AI Agent 写技能包"的统一格式。AWS 这个 Sample 紧跟规范，提供了高质量的参考实现。一个 Skill 的 frontmatter 中声明了 name、description、version、not_for（明确本 Skill 不适用的场景），这让 AI 在路由时能做出更精确的判断。

截至目前，项目的 Topics 包含了几乎所有主流 AI 编码工具的关键字：AI coding agents、claude-code、github-copilot、cursor、codex、windsurf、gemini-cli、cline 等。这说明 AWS 的目标是：让 WA 框架成为所有 AI 编码工具的默认架构知识。

未来，如果更多云厂商和开源项目参照这个模式，将自己的最佳实践打包成 Skill 并遵循统一规范，那么 AI 编码工具将不再只是"代码生成器"，而会成为真正的"架构顾问"——知道什么该做，什么不该做，什么是行业共识的最佳实践。这，才是这个项目最值得关注的潜力所在。

---

项目仓库：aws-samples/sample-well-architected-skills-and-steering，MIT-0 许可证，由 AWS Samples 团队维护。