Skip to Content

16a - AI 辅助架构设计

本文是《AI Agent 实战手册》第 16 章第 1 节。 下一节:16b-AI辅助UI-UX设计

概述

架构设计是软件项目成败的关键决策点。2025-2026 年,AI 工具已经从”辅助画图”进化到能够参与架构头脑风暴、权衡分析、ADR(Architecture Decision Record)生成、技术评估和架构审查的全流程。一个人借助 AI agent,可以在数小时内完成过去需要架构师团队数天才能产出的架构方案和决策文档。本节覆盖 AI 辅助架构设计的完整工具链、操作步骤、提示词模板和实战案例,帮助开发者和架构师用 AI 加速从”需求”到”技术蓝图”的全过程。


1. AI 辅助架构设计工具全景

1.1 核心工具推荐

工具用途价格适用场景
Claude Code(Plan Mode)架构头脑风暴、trade-off 分析、代码库分析$20/月(Pro)/ API 按量计费深度架构推理、方案对比、ADR 生成
Kiro(Spec-Driven)结构化技术设计文档自动生成免费预览 / $19/月(正式版)从需求到 design.md 的全流程
ChatGPT(o3/o4-mini)架构方案生成、技术评估$20/月(Plus)/ $200/月(Pro)快速方案迭代、多轮架构讨论
Gemini 2.5 Pro超长上下文架构分析、大代码库理解免费 / $19.99/月(Advanced)百万 token 级代码库架构审查
Eraser.ioAI 生成架构图、系统设计图免费 / $10/月(Pro)可视化架构图、C4 模型图
Mermaid + AI从文字生成流程图/序列图/架构图免费(开源)Markdown 内嵌架构图
Mermaid StudioMCP 集成的 Mermaid 图生成免费 / $9/月(Pro)AI 助手直接生成有效 Mermaid 图
PlantUMLUML 图生成(类图、序列图、组件图)免费(开源)标准 UML 建模
StructurizrC4 模型架构图(代码即图)免费(Lite)/ $5/月(Cloud)结构化 C4 架构文档

1.2 ADR 与决策文档工具

工具用途价格适用场景
Log4brainsADR 管理和浏览器(支持 Markdown)免费(开源)团队 ADR 管理、历史浏览
adr-tools命令行 ADR 管理工具免费(开源)CLI 驱动的 ADR 创建和索引
Workik ADR GeneratorAI 驱动的 ADR 自动生成免费(基础)/ 付费版快速生成 ADR 草稿
ADR GitHub ActionCI/CD 中自动验证 ADR 格式免费(开源)ADR 格式合规检查

1.3 技术评估与对比工具

工具用途价格适用场景
Perplexity Pro实时搜索技术对比信息免费 / $20/月(Pro)技术栈最新信息收集
StackShare技术栈对比和公司使用情况免费 / 企业版联系销售了解行业技术选型趋势
ThoughtWorks Tech Radar技术成熟度评估参考免费技术采纳/试验/评估/暂缓分类
Microsoft AI Decision FrameworkAI 项目技术评估框架免费(开源)结构化技术决策评分

2. AI 辅助架构头脑风暴

架构设计的第一步是探索可能的方案空间。AI 擅长快速生成多种架构方案并分析各自的优劣,帮助你在短时间内建立全局视野。

2.1 操作步骤

步骤 1:准备上下文

在开始架构头脑风暴前,准备好以下信息:

  • 需求文档(requirements.md 或 PRD)
  • 约束条件(预算、团队规模、上线时间、技术偏好)
  • 非功能需求(性能、可用性、安全性、可扩展性)
  • 已有技术栈(如果是现有系统的扩展)

步骤 2:用 AI 生成多方案架构

使用 Claude Code Plan Mode 或 ChatGPT 进行架构头脑风暴。Plan Mode 的优势在于它会先分析你的代码库,再给出与现有系统一致的架构建议。

步骤 3:对比分析和筛选

让 AI 对生成的方案进行结构化对比,输出决策矩阵。

步骤 4:深入推荐方案

选定方向后,让 AI 深入展开推荐方案的技术细节。

2.2 提示词模板

模板 1:架构头脑风暴(通用)

基于以下需求文档,请帮我做架构设计: [粘贴 requirements.md 或需求摘要] 请提出 2-3 种可行的技术架构方案,每种方案包含: 1. **方案名称**和一句话概述 2. **技术栈选择**及选择理由 3. **系统组件图**(用 Mermaid 语法) 4. **数据流图**(用 Mermaid 语法) 5. **优点**(至少 3 个) 6. **缺点**(至少 2 个) 7. **适用场景** 8. **预估复杂度**(1-5 星) 9. **预估成本**(月运行成本范围) 约束条件: - 应用类型:[桌面应用/Web 应用/移动应用/API 服务] - 团队规模:[人数] - 预算:[具体预算] - 上线时间:[具体时间] - 必须使用的技术:[如有] - 必须避免的技术:[如有] 最后给出你的推荐方案及理由,并列出需要我确认的关键技术决策点。

模板 2:架构方案对比矩阵

请将以下架构方案进行结构化对比: 方案 A:[方案描述] 方案 B:[方案描述] 方案 C:[方案描述] 对比维度: 1. 开发复杂度(1-5 星) 2. 运维复杂度(1-5 星) 3. 可扩展性(1-5 星) 4. 性能上限 5. 月运行成本估算 6. 团队学习曲线 7. 社区生态成熟度 8. 安全性 9. 适合的团队规模 10. 长期维护成本 请输出 Markdown 表格,并在表格下方给出加权评分推荐(权重根据我的约束条件自动分配)。 我的优先级:[性能优先/成本优先/开发速度优先/可维护性优先]

模板 3:针对现有系统的架构演进

我有一个现有系统,需要进行架构演进。 当前架构: [描述当前架构或粘贴 design.md] 面临的问题: - [问题 1:如性能瓶颈] - [问题 2:如扩展性不足] - [问题 3:如技术债务] 目标状态: - [目标 1] - [目标 2] 请提出 2-3 种演进方案,每种方案包含: 1. 演进路径(分阶段,每阶段可独立交付) 2. 每阶段的改动范围和风险评估 3. 回滚策略 4. 预估工时 5. 对现有功能的影响分析 约束:不能停机迁移,必须支持灰度发布。

3. AI 辅助 ADR(Architecture Decision Record)生成

ADR 是记录架构决策”为什么”的关键文档。传统方式下,ADR 编写耗时且容易被跳过。AI 可以将 ADR 生成从”痛苦的文档工作”变成”自然的决策流程副产品”。

3.1 ADR 是什么?为什么重要?

ADR 记录的不是”做了什么”,而是”为什么这样做”。一个好的 ADR 包含:

  • 上下文:面临什么问题或需求
  • 考虑的选项:评估了哪些方案
  • 决策:最终选择了什么
  • 理由:为什么选择这个方案
  • 后果:这个决策带来的影响(正面和负面)

没有 ADR,6 个月后你(或接手的人)会问:“当初为什么选了这个技术?“——然后没人能回答。

3.2 AI 辅助 ADR 的三种工作流

工作流 A:对话式 ADR 生成(推荐新手使用)

  1. 在架构讨论中,把决策过程的对话喂给 AI
  2. AI 从对话中提取决策要素,生成结构化 ADR
  3. 人工审查和补充

工作流 B:代码库扫描式 ADR 生成

  1. AI agent 扫描代码库,识别已有的架构决策(如框架选择、数据库选型)
  2. 自动生成”追溯性 ADR”,补全历史决策记录
  3. 人工确认和补充上下文

工作流 C:决策驱动式 ADR 生成(推荐团队使用)

  1. 面临架构决策时,先用 AI 生成选项分析
  2. 团队讨论后确定方向
  3. AI 根据讨论结果生成正式 ADR
  4. 存入版本控制

3.3 操作步骤

步骤 1:安装 ADR 管理工具

# 方式 1:使用 adr-tools(推荐) brew install adr-tools # macOS # 或 npm install -g adr-tools # Node.js # 初始化 ADR 目录 adr init docs/adr # 方式 2:使用 Log4brains(带 Web 浏览器) npm install -g log4brains log4brains init

步骤 2:用 AI 生成 ADR 草稿

将决策上下文提供给 AI,生成结构化 ADR。

步骤 3:审查和存档

  • 人工审查 AI 生成的 ADR,补充团队讨论中的关键细节
  • 确认后提交到版本控制
  • 在 design.md 或 README 中引用相关 ADR

3.4 提示词模板

模板 4:从零生成 ADR

请帮我生成一份 Architecture Decision Record(ADR),使用以下格式: # ADR-[编号]: [决策标题] ## 状态 [提议/已接受/已废弃/已取代] ## 上下文 [描述面临的问题和背景] ## 考虑的选项 ### 选项 1: [名称] - 描述: - 优点: - 缺点: - 预估成本: ### 选项 2: [名称] - 描述: - 优点: - 缺点: - 预估成本: ### 选项 3: [名称] - 描述: - 优点: - 缺点: - 预估成本: ## 决策 [选择了哪个选项] ## 理由 [为什么选择这个选项,关键的权衡考量] ## 后果 ### 正面 - ### 负面 - ### 风险 - ## 相关 ADR - [关联的其他 ADR] --- 我的决策上下文: - 项目:[项目名称和简述] - 决策主题:[如:选择数据库/选择前端框架/选择部署方案] - 约束条件:[预算、团队技能、时间等] - 已知偏好:[如有]

模板 5:从代码库追溯生成 ADR

请分析以下代码库结构和配置文件,识别其中的关键架构决策,并为每个决策生成追溯性 ADR。 代码库结构: [粘贴目录树或 ls -la 输出] 关键配置文件: [粘贴 package.json / Cargo.toml / docker-compose.yml 等] 请识别以下类型的决策: 1. 编程语言和框架选择 2. 数据库和存储方案 3. API 设计风格(REST/GraphQL/gRPC) 4. 部署和基础设施方案 5. 测试策略 6. 第三方服务集成 对于每个识别到的决策,生成简洁的 ADR,重点推测"为什么"做出这个选择。

模板 6:决策对比分析(ADR 前置)

我正在做一个架构决策,需要你帮我分析选项。 决策主题:[如:选择消息队列方案] 背景: - [项目背景] - [当前痛点] - [期望目标] 候选选项: 1. [选项 A] 2. [选项 B] 3. [选项 C] 请从以下维度深度分析每个选项: - 技术成熟度和社区活跃度 - 学习曲线和团队适配度 - 性能特征(吞吐量、延迟、可靠性) - 运维复杂度 - 成本(许可证 + 基础设施 + 人力) - 锁定风险(vendor lock-in) - 与现有技术栈的兼容性 最后给出推荐,并说明在什么条件下你的推荐会改变。

4. AI 辅助技术评估框架

技术选型是架构设计中最容易引发争议的环节。AI 可以帮助你建立结构化的评估框架,减少主观偏见,让决策过程可追溯。

4.1 CLEAR 评估框架

参考 Microsoft AI Decision Framework 和企业级 Agentic AI 评估实践,推荐使用 CLEAR 五维评估模型:

维度英文评估内容权重建议
成本Cost许可证、基础设施、人力、迁移成本15-25%
延迟Latency响应时间、吞吐量、冷启动10-20%
效能Efficacy功能覆盖度、准确性、质量25-35%
保障Assurance安全性、合规性、可审计性10-20%
可靠性Reliability可用性、容错、恢复能力15-25%

4.2 操作步骤

步骤 1:定义评估维度和权重

根据项目特点调整 CLEAR 各维度的权重。例如:

  • 金融系统:保障(30%)> 可靠性(25%)> 效能(20%)> 成本(15%)> 延迟(10%)
  • 创业 MVP:成本(30%)> 效能(25%)> 延迟(20%)> 可靠性(15%)> 保障(10%)
  • 实时游戏:延迟(30%)> 可靠性(25%)> 效能(20%)> 成本(15%)> 保障(10%)

步骤 2:用 AI 收集技术信息

使用 Perplexity Pro 或 ChatGPT 联网模式收集候选技术的最新信息。

步骤 3:AI 辅助评分

让 AI 根据收集的信息对每个候选技术进行 CLEAR 评分。

步骤 4:生成评估报告

AI 输出结构化评估报告,包含评分矩阵、推荐结论和风险提示。

4.3 提示词模板

模板 7:技术评估矩阵

请帮我评估以下技术选项,使用 CLEAR 框架进行结构化评分。 评估主题:[如:后端框架选型] 候选技术: 1. [技术 A] 2. [技术 B] 3. [技术 C] 项目背景: - 类型:[Web 应用/API 服务/桌面应用] - 预期用户量:[数量级] - 团队技术栈:[现有技能] - 预算范围:[月预算] 请按以下格式输出评估矩阵(每项 1-10 分): | 维度 | 权重 | 技术 A | 技术 B | 技术 C | |------|------|--------|--------|--------| | 成本 | [%] | | | | | 延迟 | [%] | | | | | 效能 | [%] | | | | | 保障 | [%] | | | | | 可靠性 | [%] | | | | | **加权总分** | 100% | | | | 每个评分请附带一句话理由。最后给出推荐结论。

模板 8:技术栈兼容性分析

我当前的技术栈是: - 前端:[框架/语言] - 后端:[框架/语言] - 数据库:[类型] - 部署:[平台] - CI/CD:[工具] 我想引入 [新技术/新工具]。请分析: 1. **兼容性**:与现有技术栈的集成难度(1-5 星) 2. **冲突风险**:可能产生的技术冲突 3. **迁移路径**:如何平滑引入 4. **替代方案**:如果兼容性差,有什么替代选择 5. **长期影响**:对技术栈整体复杂度的影响

5. AI 辅助权衡分析(Trade-off Analysis)

架构设计的本质是权衡。没有完美的架构,只有在特定约束下的最优选择。AI 可以帮助你系统化地分析权衡,避免遗漏关键因素。

5.1 常见架构权衡维度

权衡对说明典型场景
一致性 vs 可用性CAP 定理的经典权衡分布式数据库选型
性能 vs 可维护性优化代码往往更难维护热路径优化决策
灵活性 vs 简单性过度抽象增加复杂度框架和中间件选择
安全性 vs 用户体验更多安全检查意味着更多摩擦认证和授权设计
开发速度 vs 技术债务快速交付可能积累债务MVP vs 长期产品
自建 vs 购买控制力 vs 维护成本基础设施和服务选择
单体 vs 微服务简单性 vs 可扩展性系统架构风格选择
同步 vs 异步实时性 vs 吞吐量通信模式选择

5.2 操作步骤

步骤 1:识别关键权衡点

在架构设计过程中,让 AI 帮你识别需要做出权衡的关键决策点。

步骤 2:量化权衡影响

对每个权衡点,让 AI 分析不同选择的具体影响。

步骤 3:生成权衡决策文档

将权衡分析结果整理为可追溯的决策文档(可以直接作为 ADR 的一部分)。

5.3 提示词模板

模板 9:权衡分析

我正在设计 [系统/功能] 的架构,需要做以下权衡决策: 决策点:[如:选择同步 API 还是异步消息队列] 请从以下角度分析两种选择的权衡: 1. **性能影响**:吞吐量、延迟、资源消耗 2. **可靠性影响**:故障模式、恢复策略、数据一致性 3. **开发影响**:实现复杂度、调试难度、测试策略 4. **运维影响**:监控需求、扩缩容、故障排查 5. **成本影响**:基础设施成本、开发人力、维护成本 6. **演进影响**:未来需求变化时的适应能力 对于每个角度,请给出: - 选择 A 的影响(正面/负面) - 选择 B 的影响(正面/负面) - 在什么条件下选择 A 更优 - 在什么条件下选择 B 更优 我的具体约束: - [约束 1] - [约束 2] - [约束 3]

模板 10:Iron Triangle 分析

请用"铁三角"模型分析我的架构决策: 项目:[项目描述] 决策:[架构决策描述] 铁三角维度: - 质量(Quality):功能完整性、可靠性、安全性 - 速度(Speed):开发时间、上线速度 - 成本(Cost):人力、基础设施、许可证 对于我的决策,请分析: 1. 当前选择在铁三角中的定位 2. 如果要提升某个维度,其他维度会如何受影响 3. 推荐的平衡点在哪里 4. 有没有"打破铁三角"的创新方案(如用 AI 工具降低成本同时提升速度)

6. 用 Kiro 生成 Design Doc(Spec-Driven 工作流)

Kiro 是 AWS 推出的 Spec-Driven AI IDE,其核心理念是”先规格、后代码”。在架构设计阶段,Kiro 可以从需求文档自动生成结构化的技术设计文档。

6.1 Kiro Spec-Driven 工作流

需求输入 → Kiro 分析 → 自动生成 design.md → 人工审查 → 确认后生成 tasks.md

Kiro 生成的 design.md 通常包含:

  • 技术架构概述:系统整体架构描述
  • 组件设计:各模块的职责和接口
  • 数据模型:TypeScript 接口、数据库 schema
  • API 设计:端点定义、请求/响应格式
  • 正确性属性(Correctness Properties):可验证的系统行为属性
  • 测试策略:单元测试、集成测试、属性测试的规划

6.2 操作步骤

步骤 1:准备 requirements.md

在 Kiro 中创建或导入需求文档。Kiro 使用 EARS(Easy Approach to Requirements Syntax)格式:

### Requirement 1: 用户认证 **User Story:** As a 用户, I want 安全的登录功能, so that 我的数据受到保护。 #### Acceptance Criteria 1. WHEN 用户提交有效凭证, THE 系统 SHALL 返回 JWT token 并设置 httpOnly cookie 2. WHEN 用户提交无效凭证, THE 系统 SHALL 返回 401 错误并记录失败尝试 3. WHEN 连续失败超过 5 次, THE 系统 SHALL 锁定账户 15 分钟

步骤 2:触发 Design Doc 生成

在 Kiro 中确认 requirements.md 后,Kiro 会自动分析需求并生成 design.md。

步骤 3:审查和迭代

  • 检查架构是否符合你的技术偏好
  • 验证数据模型是否完整
  • 确认 API 设计是否合理
  • 审查正确性属性是否覆盖关键行为

步骤 4:从 Design Doc 到任务分解

确认 design.md 后,Kiro 自动生成 tasks.md,将架构设计分解为可执行的开发任务。

6.3 Kiro 与手动架构设计的对比

维度手动架构设计Kiro Spec-Driven
耗时数小时到数天数分钟生成草稿
一致性依赖个人经验结构化模板保证
可追溯性需要手动维护需求→设计→任务自动关联
遗漏风险容易遗漏边界情况AI 辅助发现遗漏
灵活性完全自由模板约束(可自定义)
适用场景复杂系统、创新架构标准化项目、快速迭代

7. AI 辅助架构图生成

架构图是沟通架构设计的核心媒介。AI 可以从文字描述直接生成 Mermaid、PlantUML 或 Eraser 格式的架构图,大幅降低画图的时间成本。

7.1 操作步骤

步骤 1:选择图表类型

根据沟通目的选择合适的图表类型:

图表类型用途推荐工具
C4 Context 图系统与外部交互的全局视图Eraser.io / Structurizr
C4 Container 图系统内部容器(服务、数据库)关系Eraser.io / Mermaid
组件图模块内部组件关系Mermaid / PlantUML
序列图核心流程的交互时序Mermaid / PlantUML
数据流图数据在系统中的流转路径Mermaid
状态机图有状态管理的业务逻辑Mermaid
部署图基础设施和部署拓扑Eraser.io / Mermaid

步骤 2:用 AI 生成图表代码

将设计文档或架构描述提供给 AI,生成对应的图表代码。

步骤 3:渲染和调整

  • Mermaid:直接在 Markdown 中渲染,或使用 Mermaid Live Editor
  • Eraser.io:粘贴到 Eraser 编辑器中渲染
  • PlantUML:使用 PlantUML Server 或 VS Code 插件渲染

7.2 提示词模板

模板 11:生成 Mermaid 架构图

基于以下设计文档,生成以下 Mermaid 图: 1. **系统架构图**(C4 模型 - Context 层):展示系统与外部用户、服务的交互 2. **核心组件交互序列图**:展示 [核心功能] 的完整调用链 3. **数据流图**:展示数据从输入到存储到输出的完整路径 4. **状态机图**:展示 [有状态实体] 的状态转换 设计文档: [粘贴 design.md 或架构描述] 要求: - 使用最新的 Mermaid 语法 - 每个图附带简短说明 - 节点命名使用中英文混合(中文标签,英文 ID)

模板 12:生成 C4 模型全套图

请为以下系统生成 C4 模型的三层架构图(使用 Mermaid 语法): 系统名称:[名称] 系统描述:[一句话描述] 用户角色: - [角色 1]:[描述] - [角色 2]:[描述] 外部系统: - [系统 1]:[描述] - [系统 2]:[描述] 内部服务: - [服务 1]:[描述] - [服务 2]:[描述] 请生成: 1. **Context 图**:系统边界、用户、外部系统 2. **Container 图**:内部服务、数据库、消息队列 3. **Component 图**(针对核心服务):模块、接口、依赖

8. AI 辅助架构审查与验证

架构设计完成后,AI 可以作为”虚拟架构审查员”,帮助发现设计中的潜在问题。

8.1 架构审查清单

让 AI 按照以下清单审查你的架构设计:

审查维度关键问题
单点故障系统中是否存在单点故障?每个组件是否有冗余?
可扩展性流量增长 10x 时,哪些组件会成为瓶颈?
数据一致性跨服务的数据一致性如何保证?
安全边界信任边界在哪里?敏感数据如何保护?
故障恢复每个组件故障时的降级策略是什么?
可观测性如何监控系统健康?关键指标是什么?
成本效率资源利用率如何?有没有过度配置?
技术债务当前设计会引入什么技术债务?

8.2 提示词模板

模板 13:架构审查

请作为一位资深架构师,审查以下架构设计: [粘贴 design.md 或架构描述] 请从以下维度进行审查,对每个维度给出评分(1-5 星)和具体建议: 1. **可靠性**:单点故障、冗余设计、故障恢复 2. **可扩展性**:水平扩展能力、瓶颈识别 3. **安全性**:攻击面、数据保护、认证授权 4. **可维护性**:代码组织、模块耦合度、文档完整性 5. **性能**:延迟、吞吐量、资源效率 6. **成本效率**:基础设施成本、运维成本 7. **可观测性**:监控、日志、追踪 8. **演进能力**:应对未来需求变化的灵活性 对于每个发现的问题,请给出: - 严重程度(高/中/低) - 具体问题描述 - 推荐的改进方案 - 改进的优先级 最后给出整体评价和 Top 3 优先改进建议。

模板 14:架构反模式检测

请检查以下架构设计中是否存在常见的架构反模式: [粘贴架构描述] 请检查以下反模式: 1. **大泥球**(Big Ball of Mud):缺乏清晰的模块边界 2. **金锤子**(Golden Hammer):过度使用某一技术 3. **过度工程**(Over-Engineering):不必要的复杂性 4. **分布式单体**(Distributed Monolith):微服务但强耦合 5. **简历驱动开发**(Resume-Driven Development):选技术为了简历而非需求 6. **过早优化**(Premature Optimization):在没有数据支撑的情况下优化 7. **忽视运维**(Ignoring Operations):只考虑开发不考虑运维 8. **缺少故障模式设计**(No Failure Mode Design):没有考虑故障场景 对于检测到的反模式,请说明: - 在设计中的具体表现 - 可能导致的后果 - 推荐的修正方案

实战案例

案例 1:RustSync 桌面应用架构设计

RustSync 是一个本地文件与百度网盘的同步工具,使用 Tauri(Rust 后端 + React 前端)架构。以下是用 AI 辅助完成架构设计的完整过程。

第一步:架构头脑风暴

向 Claude 提供需求后,AI 生成了三种方案:

方案架构优点缺点
A: Tauri + ReactRust 后端 + React 前端,桌面应用性能好、包体积小、跨平台Rust 学习曲线陡峭
B: Electron + Node.jsNode.js 全栈,桌面应用开发速度快、生态丰富内存占用大、包体积大
C: Web App + 本地 AgentWeb 界面 + 本地守护进程无需安装、易更新需要本地 agent、架构复杂

第二步:生成架构图

AI 生成的 Mermaid 架构图(方案 A):

第三步:生成 ADR

AI 为关键决策生成了 ADR:

ADR-001: 选择 Tauri 而非 Electron

  • 上下文:需要跨平台桌面应用,文件同步对性能敏感
  • 决策:选择 Tauri(Rust + WebView)
  • 理由:Rust 的文件 I/O 性能远优于 Node.js;Tauri 包体积约 5MB vs Electron 约 150MB;内存占用低 10x
  • 后果:团队需要学习 Rust,但后端逻辑(文件监控、差异计算)正好适合 Rust 的系统编程能力

第四步:用 Kiro 生成 Design Doc

在 Kiro 中导入 requirements.md 后,自动生成了包含组件设计、数据模型、API 设计的完整 design.md,并分解为 47 个可执行任务。

案例 2:SaaS API 服务架构决策

一个 B2B SaaS 产品需要设计 API 服务架构,团队 3 人,预算有限。

权衡分析过程

使用模板 9 进行权衡分析,AI 输出了关键决策矩阵:

决策点选项 A选项 B推荐理由
API 风格RESTGraphQLREST团队熟悉、工具链成熟、3 人团队不需要 GraphQL 的灵活性
数据库PostgreSQLMongoDBPostgreSQL数据关系明确、ACID 事务需求、pgvector 支持未来 AI 功能
部署KubernetesRailwayRailway3 人团队运维 K8s 成本过高、Railway 自动扩缩容足够
认证自建Auth0Auth0安全关键功能不应自建、Auth0 免费额度够用
缓存Redis应用层缓存RedisAPI 有高频读取场景、Redis 运维成本低

生成的 ADR 示例

# ADR-003: 选择 Railway 而非 Kubernetes 部署 ## 状态 已接受 ## 上下文 团队 3 人,需要部署 API 服务、数据库和缓存。 需要自动扩缩容和零停机部署。 ## 考虑的选项 1. Kubernetes(自管理或 EKS/GKE) 2. Railway(PaaS) 3. Fly.io(边缘部署) ## 决策 选择 Railway。 ## 理由 - 3 人团队没有专职运维,K8s 运维成本过高 - Railway 支持 Docker 部署、自动扩缩容、零停机部署 - 月成本约 $50-200,远低于 K8s 集群的 $300+ - 未来用户量超过 10 万时再考虑迁移到 K8s ## 后果 - 正面:运维成本极低,团队可以专注产品开发 - 负面:平台锁定风险,自定义能力有限 - 风险:Railway 服务中断时无法自行恢复

案例 3:微服务架构演进决策

一个电商平台从单体架构演进到微服务,使用 AI 辅助规划演进路径。

使用模板 3(架构演进)的输出

AI 分析了现有单体应用后,推荐了分阶段演进方案:

阶段 1(第 1-2 月):Strangler Fig 模式启动

  • 在单体前面加 API Gateway
  • 将用户认证服务独立出来(风险最低、依赖最少)
  • 保持单体继续运行,新请求通过 Gateway 路由

阶段 2(第 3-4 月):核心服务拆分

  • 拆分订单服务(业务价值最高)
  • 引入消息队列处理服务间通信
  • 建立服务发现和配置中心

阶段 3(第 5-6 月):数据层拆分

  • 每个服务拥有独立数据库
  • 实现最终一致性(Saga 模式)
  • 建立分布式追踪和监控

AI 同时生成了每个阶段的回滚策略和风险评估,确保任何阶段失败都可以安全回退。


避坑指南

❌ 常见错误

  1. 完全信任 AI 的架构建议

    • 问题:AI 可能推荐”教科书式”的架构,忽略你的具体约束(团队技能、预算、时间)
    • 正确做法:把 AI 的输出当作”起点”而非”终点”,始终结合实际约束做最终决策
  2. 跳过 ADR 直接开始编码

    • 问题:3 个月后没人记得为什么选了这个技术栈,修改架构时缺乏决策依据
    • 正确做法:每个关键架构决策都生成 ADR,哪怕只是简短的 3 段话
  3. 过度依赖 AI 生成的架构图

    • 问题:AI 生成的图可能遗漏关键组件或错误表示依赖关系
    • 正确做法:AI 生成初稿后,人工审查每个连接和组件,确保与实际设计一致
  4. 用 AI 做架构设计时不提供约束条件

    • 问题:没有约束的架构建议往往是”理想化”的,不切实际
    • 正确做法:始终提供团队规模、预算、时间线、技术偏好等约束条件
  5. 一次性让 AI 设计整个系统架构

    • 问题:上下文过多导致 AI 输出质量下降,关键细节被遗漏
    • 正确做法:分层设计——先做高层架构(C4 Context),再逐层深入到组件级别
  6. 忽视架构决策的”保质期”

    • 问题:6 个月前的技术评估可能已经过时(新版本发布、价格变动、竞品出现)
    • 正确做法:在 ADR 中标注”复审日期”,定期用 AI 重新评估关键决策

✅ 最佳实践

  1. 用 Claude Plan Mode 做架构探索——它会先分析你的代码库,再给出与现有系统一致的建议
  2. 每个架构决策都生成 ADR,存入版本控制,与代码一起演进
  3. 使用 CLEAR 框架做技术评估,避免”拍脑袋”决策
  4. 架构图用 Mermaid 写在 Markdown 中,与文档一起版本管理
  5. 用 Kiro 的 Spec-Driven 工作流,从需求到设计到任务一气呵成
  6. 架构审查时,让 AI 扮演”魔鬼代言人”,专门挑战你的设计决策
  7. 权衡分析时,明确列出”在什么条件下这个决策需要重新评估”

相关资源与延伸阅读

  1. C4 Model  — Simon Brown 的 C4 架构建模方法,从 Context 到 Code 四层架构图的标准方法论
  2. ADR GitHub Organization  — Architecture Decision Records 的官方资源集合,包含模板、工具和最佳实践
  3. Kiro 官方文档  — Kiro IDE 的 Spec-Driven 开发工作流文档,了解从需求到设计的自动化流程
  4. Mermaid 官方文档  — Mermaid 图表语法参考,支持流程图、序列图、C4 图等多种图表类型
  5. ThoughtWorks Technology Radar  — 每半年更新的技术成熟度评估,帮助判断技术的采纳时机
  6. Microsoft AI Decision Framework  — 微软开源的 AI 项目技术评估框架,提供结构化的决策评分方法
  7. Eraser.io AI 架构图生成器  — 从文字描述生成专业架构图的在线工具
  8. Structurizr  — 基于代码的 C4 模型架构文档工具,支持 DSL 定义架构

参考来源

Content was rephrased for compliance with licensing restrictions.


📖 返回 总览与导航 | 下一节:16b-AI辅助UI-UX设计

Last updated on