01 - 架构设计食谱

从技术选型到系统架构，用 AI 辅助做出可靠的架构决策。

---

适用场景

场景	痛点	本食谱解法
技术选型犹豫不决	信息散落、对比维度不统一	食谱 1：多维度加权矩阵
系统设计缺乏全局视角	口头描述不够精确	食谱 2：分层架构方案
API 接口反复变更	前后端约定不一致	食谱 3：契约先行设计
数据库设计遗漏关系	实体关系考虑不全	食谱 4：实体关系建模
模块职责不清	耦合过紧、边界模糊	食谱 5：职责与依赖分析
架构决策无据可查	事后忘记当初为什么选 A 不选 B	食谱 6：ADR 标准化模板

---

食谱 1：技术选型对比

场景描述

在多个框架/库/方案中做出选择，从 AI 友好度、性能、生态等维度系统对比，产出可执行的推荐结论。

核心模板

我正在为 {{项目名称}} 做技术选型。

项目背景：
- 类型：{{项目类型，如 SaaS/移动端/CLI 工具}}
- 团队：{{人数和技术背景}}
- 规模：{{用户量/数据量/并发量}}
- 时间：{{上线时间约束}}

候选方案：{{候选方案列表，如 Next.js vs Nuxt vs Remix}}

请从以下维度对比：
1. 成熟度 — 版本稳定性、breaking change 频率
2. 社区与生态 — GitHub Stars、npm 周下载量、插件丰富度
3. 性能与可扩展性 — 基准测试数据、已知瓶颈
4. 学习曲线 — 上手时间、文档质量
5. AI 友好度 — 类型安全、文档密度、约定优先程度

输出：对比矩阵表格（每项 1-5 分）+ 加权总分 + 各方案优劣势 + 最终推荐

变量说明

变量	说明	示例
{{项目名称}}	项目代号	TaskFlow 任务管理系统
{{项目类型}}	应用形态	全栈 Web SaaS
{{人数和技术背景}}	团队情况	1 人，熟悉 React 和 Node.js
&#123;&#123;用户量/数据量/并发量&#125;&#125;	量化约束	初期 1k DAU，数据量 < 10GB
&#123;&#123;候选方案列表&#125;&#125;	待对比选项	Next.js 14 vs Remix v2 vs Nuxt 3

好坏对比

❌ 模糊提问：

Next.js 和 Remix 哪个好？帮我选一个。

✅ 结构化提问：

我要做一个个人博客+作品集站点，1 人开发，熟悉 React。
需要 SSG 为主、偶尔 SSR，部署到 Vercel。
对比 Next.js 14 App Router vs Astro 4，
从构建速度、内容管理友好度、AI 友好度三个维度分析，给出推荐。

实战案例

项目：个人记账 App（Web + PWA）
团队：1 人，3 年 React 经验，无 Vue 经验
规模：初期 500 用户，数据量 < 1GB
时间：4 周 MVP
候选：Next.js 14 vs Remix v2
维度：AI 友好度、全栈能力、PWA 支持、部署成本
请输出对比表格和推荐结论。

Claude 增强 💡

先用 Web Search 获取 Next.js 14 和 Remix v2 的最新 npm 周下载量、
GitHub Stars 和最近一次 breaking change 的日期，
然后基于实际数据填充对比矩阵，不要用模糊的定性描述。

---

食谱 2：系统架构方案设计

场景描述

为项目设计整体架构，包括分层结构、核心组件、数据流向和部署方式，输出可落地的架构方案文档。

核心模板

为 {{项目名称}} 设计系统架构方案。

功能需求：{{核心功能列表，3-5 条}}

非功能需求：
- 性能：{{响应时间/吞吐量}}
- 可用性：{{SLA 要求}}
- 安全：{{认证/授权要求}}

技术约束：
- 框架：{{已确定的技术栈}}
- 部署：{{云平台/自建/Serverless}}
- 预算：{{月成本上限}}

请输出：
1. 架构分层图（ASCII 字符画或 Mermaid 语法）
2. 各层职责说明（每层 2-3 句话）
3. 核心组件清单及交互方式
4. 关键数据流示意（主要用户场景的请求链路）
5. 需要权衡的技术决策点（至少 2 个）

变量说明

变量	说明	示例
{{项目名称}}	项目代号	BookShelf 读书管理
{{核心功能列表}}	主要功能	书籍 CRUD、阅读进度追踪、笔记标注
{{已确定的技术栈}}	技术约束	Next.js + Prisma + PostgreSQL
{{云平台/自建/Serverless}}	部署形态	Vercel + Supabase
{{月成本上限}}	预算	$20/月（含数据库）

好坏对比

❌ 模糊提问：

帮我设计一个读书 App 的架构。

✅ 约束明确：

帮我设计读书管理 App 的架构。1 人开发，Next.js + Supabase，部署 Vercel。
核心功能：书籍管理、阅读进度、笔记。预算 $20/月。
请用 ASCII 字符画分层架构图，说明每层职责。单体优先，不要微服务。

实战案例

项目：TaskFlow — 个人任务管理 SaaS
功能：任务 CRUD、看板视图、番茄钟、周报生成
技术栈：Next.js 14 App Router + Prisma + PostgreSQL
部署：Vercel (前端) + Railway (数据库)，预算 $10/月
请输出 ASCII 分层架构图、目录结构建议、关键数据流示意。

Claude 增强 💡

请用 ASCII 字符画出架构图（+--+ 画框、--> 画箭头），不用 Mermaid。
确保架构中每个技术选择都符合 AI 友好度 S/A 级别。

---

食谱 3：API 契约设计

场景描述

编码前先定义 API 输入输出契约，含 endpoint、请求响应格式、错误码，确保前后端有明确的接口规范。

核心模板

为 {{模块名称}} 设计 RESTful API 契约。

业务背景：{{模块核心业务逻辑，2-3 句话}}

资源/实体：{{实体列表及关键字段}}

技术约束：
- 框架：{{如 Next.js Route Handlers / FastAPI}}
- 校验：{{如 zod / pydantic}}
- 认证：{{如 JWT / NextAuth Session}}

请输出：
1. API 端点清单（方法 + 路径 + 简述）
2. 每个端点的请求/响应 TypeScript 类型定义
3. 统一错误响应格式（含错误码枚举）
4. 分页、排序、过滤的查询参数约定
5. 认证与权限要求标注

变量说明

变量	说明	示例
{{模块名称}}	功能模块	用户管理模块
{{模块核心业务逻辑}}	业务描述	支持注册、登录、信息修改和头像上传
{{实体列表及关键字段}}	核心实体	User: id, email, name, avatar, role
{{框架}}	后端框架	Next.js 14 Route Handlers
{{校验库}}	数据校验	zod

好坏对比

❌ 模糊提问：

帮我写用户管理的 API。

✅ 契约先行：

先为用户管理模块设计 API 契约，不要写实现代码。
实体：User (id, email, name, avatar, role, createdAt)
框架：Next.js Route Handlers + zod 校验
端点：注册、登录、获取/更新个人信息、上传头像
输出 TypeScript 类型定义和端点清单。
错误响应统一用 { error: string, code: string } 格式。

实战案例

模块：书籍管理
实体：Book (id, title, author, isbn, coverUrl, status, rating, userId)
status 枚举：WANT_READ | READING | FINISHED | DROPPED
框架：Next.js 14 Route Handlers + zod
认证：NextAuth Session（userId 从 session 获取）

设计 CRUD + 状态变更 + 按状态筛选的 API 契约。
输出 zod schema 定义和端点清单。
分页用 cursor-based，排序支持 createdAt 和 rating。

Claude 增强 💡

基于上面的 API 契约，直接生成 OpenAPI 3.0 spec（YAML 格式），
包含 paths、requestBody、responses 和 components/schemas。

• 如果项目已采用 Zod → OpenAPI 工作流，在定义 zod schema 时同步添加 .openapi() 元数据（description + example），避免事后补充。详见 doc-17 API 接口维护体系

---

食谱 4：数据模型设计

场景描述

从用户故事或需求描述推导数据模型，设计 ER 关系、字段定义、索引策略和种子数据。

核心模板

为 {{项目名称}} 设计数据模型。

核心业务实体：
{{实体及其业务含义，每个 1 句话}}

业务规则：
{{实体间的关系和约束，3-5 条}}

技术约束：
- 数据库：{{如 PostgreSQL / SQLite}}
- ORM：{{如 Prisma / Drizzle / SQLAlchemy}}
- 特殊需求：{{软删除/多租户/审计日志等}}

请输出：
1. ER 图（Mermaid erDiagram 语法）
2. ORM Schema 定义（完整可执行代码）
3. 索引策略（哪些字段需要索引及原因）
4. 种子数据示例（至少 3 条记录）
5. 迁移注意事项

变量说明

变量	说明	示例
{{项目名称}}	项目代号	TaskFlow
{{实体及其业务含义}}	核心实体	Task: 待办事项；Tag: 分类标签；TimeLog: 番茄钟记录
{{实体间的关系和约束}}	业务规则	Task 可有多个 Tag（多对多）；TimeLog 属于一个 Task
{{数据库类型}}	数据库	PostgreSQL
{{ORM 工具}}	ORM	Prisma

好坏对比

❌ 模糊提问：

帮我设计任务管理的数据库。

✅ 约束完整：

用 Prisma + PostgreSQL 设计任务管理的数据模型。
实体：User、Task、Tag、TimeLog
关系：User 1:N Task，Task M:N Tag，Task 1:N TimeLog
要求：软删除、自动时间戳、Task.status 用枚举
请输出 Prisma schema 和 Mermaid ER 图。
索引：按 userId+status 复合索引，按 createdAt 排序索引。

实战案例

请从以下用户故事推导数据模型：
- US-1：作为用户，我想记录正在读的书，追踪阅读进度
- US-2：作为用户，我想为每本书打分和写笔记
- US-3：作为用户，我想记录每天的阅读时长和页数
技术栈：PostgreSQL + Prisma
要求：输出完整 Prisma schema，Book 按 ISBN 去重，阅读状态用枚举。

Claude 增强 💡

读 @prisma/schema.prisma，在现有模型基础上新增实体，确保与已有 User 兼容。
生成增量迁移 SQL 预览，确认后再执行 prisma migrate dev。

---

食谱 5：模块划分与依赖分析

场景描述

分析现有代码库的模块边界，检测循环依赖，重新划分职责清晰的模块结构。

核心模板

为 {{项目名称}} 进行模块划分与依赖分析。

系统功能概览：
{{功能列表，5-10 条}}

技术栈：{{语言/框架}}

当前痛点（如有）：
{{现有代码的结构问题}}

设计原则偏好：
- {{按功能切分 vs 按层切分}}
- {{单体内模块化 vs 微服务}}

请输出：
1. 模块清单（模块名 + 职责 + 对外接口）
2. 模块依赖关系图（Mermaid flowchart）
3. 循环依赖检测结果与解耦建议
4. 推荐目录结构
5. 模块间通信方式（函数调用/事件/消息队列）
6. 需要警惕的耦合风险点

变量说明

变量	说明	示例
{{项目名称}}	项目代号	TaskFlow
{{功能列表}}	系统功能	用户认证、任务 CRUD、看板视图、番茄钟、统计报表
{{语言/框架}}	技术栈	Next.js 14 + TypeScript
{{现有代码的结构问题}}	痛点	所有逻辑集中在 pages/api，service 和 controller 混在一起

好坏对比

❌ 模糊提问：

帮我把项目重构一下，代码太乱了。

✅ 问题导向：

我的 Next.js 项目 app/api/ 下每个 route.ts 直接操作 Prisma，无 service 层。
功能：用户、任务、看板、番茄钟、统计。请按功能领域划分模块，给出：
1. 目录结构（src/modules/{feature}/ 模式）
2. 每个模块的 public API（函数签名）
3. 依赖方向图（不允许循环依赖）+ 共享代码放置策略

实战案例

项目：TaskFlow，Next.js 14 App Router + Prisma
现状：app/api/ 下 15 个 route.ts，直接 import prisma，无 service 层
功能：用户认证、任务管理、标签、番茄钟、周报、通知
请按 feature-based 模式重组为 src/modules/{feature}/，
app/api/ 只做路由转发。输出模块清单、依赖图和迁移步骤。

Claude 增强 💡

先读 @src/ 下所有 TS 文件的 import 语句，生成依赖图（Mermaid flowchart），
标记循环依赖路径并给出解耦方案。不改代码，先输出分析报告。

---

食谱 6：架构决策记录（ADR）

场景描述

记录重要架构决策的背景、候选方案、理由和后果，确保团队（含未来的自己）能追溯决策过程。

核心模板

为以下架构决策撰写 ADR。

决策标题：{{决策标题}}
背景：{{为什么需要做这个决策，1-3 句话}}
约束：{{技术、时间、成本等限制}}

候选方案：
1. {{方案 A}}：{{简述}}
2. {{方案 B}}：{{简述}}
3. {{方案 C（如有）}}：{{简述}}

已选方案：{{选中的方案}}

请按以下格式输出：
- 标题（ADR-NNN: 简短描述）
- 状态（Proposed / Accepted / Deprecated）
- 背景（Context）— 业务和技术上下文
- 决策（Decision）— 选了什么
- 理由（Rationale）— 为什么选 A 不选 B，逐条对比
- 后果（Consequences）— 正面影响 + 负面影响 + 需接受的代价
- 合规检查（Compliance）— 如何验证决策被正确执行

变量说明

变量	说明	示例
{{决策标题}}	决策简称	选择 Prisma 作为 ORM
{{背景}}	决策上下文	需要 TS 友好的 ORM，支持 PostgreSQL 和迁移
&#123;&#123;约束&#125;&#125;	限制因素	必须支持 Serverless，冷启动 < 3s
&#123;&#123;方案 A/B/C&#125;&#125;	候选项	Prisma / Drizzle ORM / TypeORM
&#123;&#123;选中的方案&#125;&#125;	最终决策	Prisma

好坏对比

❌ 事后补记：

我们用了 Prisma，帮我写个 ADR。

✅ 决策过程完整：

写一份 ADR：ORM 选型。
背景：个人全栈项目，Next.js + PostgreSQL，需要类型安全的 ORM。
候选：Prisma（声明式 Schema）、Drizzle（SQL-like API）、Kysely（查询构建器）
约束：支持 Vercel Serverless、迁移管理、AI 辅助友好。已选：Prisma。
请分析各方案优劣，说明选择 Prisma 的理由及需接受的代价。

实战案例

请根据以下讨论记录自动生成 ADR：
主题：状态管理方案选型（Next.js 14 App Router 项目）
讨论要点：
- 小明：Server Component 为主，客户端状态少，Context 够用
- 小红：后续可能加复杂表单，Zustand 更有弹性
- 结论：选 Zustand，学习成本低且可渐进式引入
请在 Rationale 中反映双方观点。

Claude 增强 💡

读 @docs/adr/ 已有 ADR，保持编号连续和格式一致，新编号为最大编号 +1。
生成后自动更新索引文件。

---

组合技巧

技巧	组合路径	适用场景
选型→架构→API 三连	食谱 1 → 2 → 3，每步确认后继续	新项目从零开始
数据驱动设计	食谱 4 → 3 → 5，关键决策用食谱 6 记录	业务实体已明确
遗留系统重构	食谱 5（分析现状）→ 6（记录决策）→ 2（设计目标架构）	现有项目改造
/plan 协同	先 /plan 生成任务清单，再按清单执行食谱 1-6	复杂系统设计

新项目全流程串联：食谱 1（选型）→ 2（架构）→ 4（数据模型）→ 3（API 契约）→ 5（模块划分）→ 6（记录 ADR），每步确认后再进下一步。

---

相关资源

• doc-14 技术栈选型指南 — AI 友好度分级与选型框架
• doc-15 Prompt 工程实战 — 提示词理论基础与速查表
• /tech-research Skill — 技术调研自动化
• /plan Skill — 项目规划与任务分解
• 00-需求分析食谱 — 上游：从需求到设计的衔接
• 02-代码实现食谱 — 下游：从设计到编码的衔接