mcpField
W
well-architected

well-architected

github.com/avelikiy开发10853 次安装今天更新
代码仓库

关于 well-architected

well-architected 是用于发布前审查架构文档的 Agent 技能，面向构建 SaaS 和大模型应用的小团队。它围绕六大支柱提供审查问题、通过标准和风险处理指引。

主要功能

  1. 01六大支柱架构审查
  2. 02运营卓越与安全检查
  3. 03可靠性和性能问题清单
  4. 04成本与可持续性审查
  5. 05通过标准与风险处理

适用场景

  1. 01发布前审查架构方案
  2. 02发现安全或恢复计划的缺漏
  3. 03记录架构风险及缓解措施

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/avelikiy/great_cto --skill well-architected

安装后在 Claude Code 中输入/well-architected确认已加载。

详细介绍

架构良好 — 发布前需要核查的 6 大支柱

所有非 nano 工作的 ARCH 文档都必须回答以下 6 大支柱问题。 只有在明确说明理由时，才允许跳过某个支柱（例如： “Sustainability：不适用 — 仅后端，在共享基础设施上运行。”）。

本文改编自 AWS Well-Architected（适用范围：小团队 SaaS / LLM 应用）， 精简为适用于少于 10 名工程师团队的关键问题。

支柱 1 — 卓越运营

问题
  1. 可观测性： 我们会发出哪些指标、日志和跟踪信息？如何 通过仪表板判断它在生产环境中是否正常运行？
  2. 可部署性： 我们如何发布变更？CI 有哪些门禁？回滚路径是什么？
  3. 运行手册： 凌晨 3 点出现故障时，当班人员会查阅什么？
通过标准
  • ✅ 每项业务成果对应一个指标（例如 webhook-deliveries-acked）
  • ✅ 每个请求记录一条日志，且 request-id 可在各服务间关联
  • ✅ 已记录并测试部署流程（已执行回滚演练）
  • ✅ 运行手册涵盖事前分析中列出的 3 大故障模式
常见失败情况

❌ “我们以后再加监控。”监控是功能的一部分。

支柱 2 — 安全性

问题
  1. 信任边界： 不可信数据从哪里进入？如何验证和清理？
  2. 身份验证 / 授权： 谁可以调用此功能？谁可以读写这些数据？
  3. 密钥： API 密钥、DB 密码、JWT 签名密钥存储在哪里？
  4. 数据分类： 是否涉及 PII、PHI 或 PCI 持卡人数据？数据保留策略是什么？
通过标准
  • ✅ 每个外部输入都在边界处进行明确验证
  • ✅ 在数据层实施授权，而非仅在 UI 层
  • ✅ 密钥存储在环境变量或密钥管理器中，绝不放入源代码
  • ✅ 已对敏感数据分类并制定数据保留策略
常见失败情况

❌ “JWT 验证了用户，这就是我们的授权。”JWT 用于身份验证。 授权是另一回事（此用户可以读取这一行数据）。

支柱 3 — 可靠性

问题
  1. 故障模式： 下游依赖变慢、宕机或数据损坏时会发生什么？
  2. 幂等性： 重试请求后，能否安全地重新执行？
  3. 备份与恢复： RPO（可容忍的数据丢失量）和 RTO （可容忍的停机时间）是多少？两者的测试计划是什么？
  4. 容量： 此服务最多能处理多少 QPS？达到该值的 1.5 倍时会怎样？
通过标准
  • ✅ 对外部调用使用熔断器 / 超时机制
  • ✅ 会更改状态的端点接受幂等性密钥
  • ✅ 已记录备份，并在过去 90 天内测试过恢复
  • ✅ 存在负载测试；结果保存在 docs/perf/
常见失败情况

❌ “Postgres 有备份。”未经恢复测试的备份不算备份。

支柱 4 — 性能效率

问题
  1. SLO： p50 / p95 / p99 延迟目标是多少？错误率和 可用性目标是什么？
  2. 瓶颈： 对关键路径进行性能分析——最慢的步骤是什么？
  3. 缓存： 哪些内容可以缓存？缓存失效策略是什么？
  4. 扩展： 采用纵向扩展还是横向扩展？自动扩缩容规则是什么？
通过标准
  • ✅ ARCH 文档中列出 SLO 数值（而不是“够快”）
  • ✅ 附上非简单请求的性能分析结果
  • ✅ 已记录缓存策略，并明确缓存失效方式
  • ✅ 扩展决策有数据依据，而非“感觉合适”
常见失败情况

❌ “数据库能处理。”请量化：每秒查询数、行数、索引命中率。

支柱 5 — 成本优化

问题
  1. 热路径： 每个请求中最昂贵的操作是什么？为什么？
  2. 合理选型： 所选实例类型 / 模型 / DB 层级是否是在满足 SLO 的 前提下最小的配置？
  3. 清理： 如何处理旧数据、旧日志和旧分支环境？
通过标准
  • ✅ 使用技能 cost-model 记录明确的 $ 数值
  • ✅ 选择满足质量 SLO 的最小 LLM 模型（先用 haiku，再用 sonnet， 最后用 opus）
  • ✅ 为日志、指标和旧数据制定保留策略
常见失败情况

❌ 默认使用 Opus / GPT-4，而 Haiku 已足够。先用 Haiku 测试。

支柱 6 — 可持续性（环境 / 能源）

问题
  1. 工作负载效率： 本可以是 O(n)，代码却是 O(n log n) 吗？
  2. 空闲资源： 开发环境能否在夜间缩减到零？
  3. 数据最小化： 我们是否收集 / 存储了从未查询的数据？
通过标准
  • ✅ 已记录热循环的复杂度
  • ✅ 非生产资源已设置关闭计划
  • ✅ 数据生命周期涵盖摄取、保留和删除
常见失败情况

❌ 生产环境中日志处于调试级别，却从未审查。浪费存储空间并增加碳排放。

输出格式 — 添加到 ARCH

## Well-Architected review

### 1. Operational excellence
- Metrics: <list>
- Deploy path: <link to runbook>
- Verdict: PASS | RISKS LISTED

### 2. Security
- Trust boundaries: <list>
- Data classification: <PII / PHI / PCI / none>
- Verdict: PASS | RISKS LISTED

### 3. Reliability
- Failure modes: <link to pre-mortem>
- Idempotency: <yes/no per endpoint>
- Verdict: PASS | RISKS LISTED

### 4. Performance
- SLOs: p99=<ms>, error_rate=<%>, availability=<%>
- Verdict: PASS | RISKS LISTED

### 5. Cost
- Per-request cost: $<amount>
- Verdict: PASS | RISKS LISTED

### 6. Sustainability
- Hot-path complexity: O(<n>)
- Verdict: PASS | N/A | RISKS LISTED

## Open risks (rolled up)

<bullet list of all RISKS LISTED items + mitigation in plan>

何时可以接受附带风险的通过结果

并非每种架构都坚不可摧。附带风险的通过结果可以接受，但需满足以下条件：

  • 明确列出每项风险（不得含糊带过）
  • 每项风险都有计划中的缓解措施，或由用户明确接受
  • 事前验尸部分涵盖风险评分最高的 3 项

关卡：plan 可以批准附带风险的通过结果；gate:ship 则要求缓解措施已交付。

评论

支持 Markdown