核心论点：AI 可以帮你设计架构，但它不会替你做"权衡"。它的真正价值不是"给出正确答案"，而是穷举你没有考虑到的方案和约束------把直觉驱动的设计决策，变成可追溯的权衡过程。
为什么架构设计值得单独一篇
在 Shop-Agent 的多 Agent 协作体系中，architecture-designer 是编码前的第一个关卡：
architecture-designer → coder → test-generator → code-reviewer它的职责很明确：在代码动手之前，把模块划分、技术选型、架构权衡这些"系统长什么样"的问题，结构化地梳理清楚。
架构设计的下游是接口契约和数据模型------API URL 结构、请求/响应格式、错误码体系。但这里有一个上游缺口：
"architecture-designer 出的设计是模块级的------但 API 的 URL 结构、请求/响应格式、错误码体系，它不定义。"
那 architecture-designer 到底做什么？如果你不告诉它项目上下文，它会给你一个"看起来很美但跟你的项目毫无关系"的设计。这篇文章解决的就是：怎么让 AI 在你的项目土壤上做架构设计，而不是在真空中画框图。
什么时候该让 AI 参与架构设计
不是所有改动都值得走 architecture-designer。Shop-Agent 项目用一套"复杂度门控"来判断：
| 场景 | 是否走 architecture-designer | 理由 |
|---|---|---|
| 新增一个 CRUD 接口 | ❌ 跳过 | 模式固定，直接写更快 |
| 新增一个模块（如支付模块） | ✅ 需要 | 涉及模块边界、数据流、技术选型 |
| 现有模块内加功能 | ⚠️ 视复杂度 | 超过 3 个新文件 → 走 |
| 技术栈升级（如 Milvus 升大版本） | ✅ 需要 | 影响评估、回滚方案 |
| 性能瓶颈需要架构调整 | ✅ 需要 | 缓存策略、数据分片影响全局 |
判断原则：如果这个改动会影响两个以上模块的交互方式，就让 architecture-designer 介入。
给 architecture-designer 喂什么------上下文的四层结构
architecture-designer agent 的定义只有 31 行，它本身不携带项目知识。你需要喂给它四层上下文：
第一层：现有架构
请先理解以下项目的现有架构：
1. 模块划分：
- 基础设施层：配置、限流、权限、Token管理
- 业务模块：核心业务逻辑
- 监控与运维：指标采集、链路追踪
2. 架构模式：Orchestrator 模式------统一编排入口，按复杂度分流到不同执行器
3. 关键技术决策：
- 向量存储：方案A（默认），方案B（备选）
- 多级降级：规则 → 本地模型 → 云端 LLM这是项目的"地质报告"------让 AI 知道它是在什么土壤上盖房子。
第二层：设计原则与约束
设计约束：
- 所有重量级服务必须单例懒加载（Embedding、Milvus、Reranker）
- 新模块必须兼容现有的 Skill SOP 配置驱动机制
- 不允许引入新的向量数据库（Milvus / pgvector 二选一）
- 内存占用上限：本地模型总加载 ≤ 4GB这些告诉 AI 不是"什么都可以做"------约束越明确，AI 的方案越靠谱。
第三层：待解决问题的上下文
不要只说"设计一个退款模块"。要给出业务约束：
需求：新增退款确认功能
业务约束：
- 退款需要人工确认（人在回路），但 90% 的小额退款应自动处理
- 退款确认结果要写回对话上下文，影响后续推荐
- 高峰期 QPS 约 200，不能因为加退款而拖慢主流程
现有关联模块：
- ChatAgentService（Orchestrator 入口）
- DisputeCoordinator（已处理纠纷协调）
- ExperimentService（A/B 实验可能影响退款策略）第四层：备选方向（可选但推荐）
如果你已经有倾向的方向，告诉 AI：
备选方向（供评估，不是必须采纳）：
A. 在 DisputeCoordinator 内扩展一个新的 RefundHandler
B. 新建独立 RefundCoordinator，通过 Orchestrator 路由
C. 作为 ReActAgent 的新工具，用 function calling 处理有备选方向时，AI 的产出从"帮你设计"变成"帮你对比"------质量跃升一个量级。
ADR------让 AI 用架构决策记录格式输出
不要求 AI 用 ADR 格式，它会给你一段散文------读起来很美，但无法追溯"为什么选了这个方案"。
要求 AI 按 ADR 格式输出，立刻变成可审查、可追溯的架构资产：
markdown
## ADR-007：退款确认功能架构方案
### 状态
提议中
### 背景
当前 DisputeCoordinator 处理纠纷协调，但不支持退款后的确认流程。
退款确认涉及：自动审批（小额）+ 人工审批（大额）+ 结果回写对话上下文。
### 决策
选择方案 B：新建 RefundCoordinator，通过 Orchestrator 路由。
### 方案对比
| 维度 | A: 扩展 DisputeCoordinator | B: 新建 RefundCoordinator | C: ReActAgent 工具 |
|------|--------------------------|--------------------------|---------------------|
| 模块耦合度 | 高------退款逻辑耦合进纠纷模块 | 低------独立模块，职责单一 | 中------混入 Agent 工具列表 |
| 可测试性 | 中------需要完整 Dispute 上下文 | 高------独立单元测试 | 低------依赖 Agent 循环 |
| 人在回路支持 | 需要改造 Dispute 流程 | 原生支持异步等待 | 需额外实现状态机 |
| 扩展性 | 中------逻辑纠缠时难加功能 | 高------RefundHandler 可插拔 | 中------工具可新增但需 Agent 感知 |
| 实现工期 | 3 天 | 5 天 | 2 天 |
| 风险 | 低------在现有模块上改 | 中------新增模块，需 Orchestrator 路由改造 | 高------ReActAgent 循环可能超时 |
### 理由
- 退款和纠纷是两种业务场景：纠纷是"买卖双方分歧"，退款是"已确认退款后的财务流程"
- 人在回路是硬需求（大额退款需人工审批），方案 A 要在 DisputeCoordinator 内嵌入状态机，违反单一职责
- 方案 C 工期最短但有隐患------ReActAgent 的工具选择依赖本地小模型，可能选错工具导致退款链路不可靠
- 方案 B 的额外工期（5天 vs 3天）换取的是可以独立演进、独立测试、独立部署的模块
### 后果
- 正面：退款流程独立，后续可扩展退款原因分析、退款率监控
- 负面：Orchestrator 路由表需要增加一个分支，增加约 20ms 判断开销
- 风险：新增模块意味着新的故障面，需要补充退款链路的 Prometheus 指标和告警这个格式的核心价值不是"看着整齐"，而是 权衡可见。你能看到 AI 考虑了哪些维度、放弃了什么------架构设计的本质就是权衡，AI 不能替你做，但能帮你把所有因素摊在桌面上。
技术选型------AI 作为权衡探索器
技术选型是 AI 最能帮上忙的环节------它知道的技术栈比你多，不会漏掉方案。真正的问题是你需要给它"评估维度"。
反例：开放式提问
❌ "向量数据库选哪个好？"
→ AI 给你一个列表，你可能直接采纳第一个正例：带评估维度的提问
✅ "以下三种向量存储方案，请按以下维度对比：
维度：
1. 查询延迟（P99，100万向量规模）
2. 混合检索能力（Dense + Sparse）
3. 运维复杂度（部署、监控、备份）
4. 与现有 LangChain 集成的成本
5. 中文场景的社区活跃度
方案：
A. Milvus 2.6（当前使用）
B. pgvector（已有 PostgreSQL 实例）
C. Qdrant
上下文：我们的向量规模约 50 万，QPS 约 200，现有 PostgreSQL 实例负载 40%。"AI 的输出就不再是一个列表，而是带权衡维度的对比------这才能真正辅助决策。
模块分解------AI 需要的是"划分维度"
让 AI 拆模块，最怕的是它给出一个"教科书式"的分法------controller → service → repository 三层，每个实体一个目录。这在简单场景下是对的，但遇到复杂系统时，这种分法不解决任何实际问题。
给 AI 正确的拆分维度
请将以下功能拆分为模块。拆分时请使用以下维度，并对每个维度给出你的判断：
功能：智能客服核心（意图识别 + RAG 检索 + Agent 执行 + 文档管理）
拆分维度：
1. 变化频率------哪些功能会独立演进？
2. 团队边界------哪些功能会被不同的人维护？
3. 技术依赖------哪些功能依赖特定的基础设施（GPU、向量库）？
4. 复用边界------哪些功能可能被其他模块消费？一个典型的分层结果正好呼应了这四个维度：
- 变化频率高 → 编排逻辑独立于基础服务层
- 技术依赖重 → 模型推理服务独立，懒加载
- 复用边界 → 基础层被上层消费，不反向依赖
审查 AI 的架构输出------四个检查点
AI 出的架构方案，人必须审。不是检查"代码对不对"（还没写代码），而是四个维度：
检查点 1：假设是否成立
AI 经常会悄悄做一个假设------比如"假设数据库连接池无限大"。找出这些隐含假设：
方案里说"每个请求直接查询向量库"------
你的连接池上限是多少？高峰 QPS × 查询延迟 = 需要的连接数，够吗？检查点 2：边界条件是否有覆盖
方案里说"缓存命中则跳过 LLM 调用"------缓存未命中时呢？
降级路径写了吗？缓存挂了怎么办？检查点 3：与现有架构的冲突
这是 AI 最容易出错的地方------它设计的模块可能跟现有约定打架：
方案里新模块用 asyncpg 直连 PostgreSQL------
但项目已有 SQLAlchemy 封装的 get_db，新模块是不是该统一？检查点 4：复杂度是否合理
方案里为了解决一个边缘场景，引入了一个新的消息队列------
这个边缘场景的发生概率是多少？值不值得加一个中间件的运维负担？architecture-designer 在流程中的定位
architecture-designer 在整个开发流程中的位置：
Prompt 工程 → 学会跟 AI 说话
Rules → 项目知识进 AI 上下文
@ 引用 + 搜索 → 精准喂入相关文件
Ask/Craft/Plan → 选对模式
← architecture-designer 在这里
架构设计 → 模块划分 + 技术选型 + ADR
↓
接口与数据设计 → 接口契约 + 数据模型
↓
编码与质量保障 → 编码 + 测试 + 审查 + 优化architecture-designer 回答的问题是"系统长什么样"------它走在所有编码工作之前。AI 在这个阶段帮你把设计空间穷举一遍，后面写代码时就不会因为一个没考虑到的约束而推到重来。
总结
| 要点 | 说明 |
|---|---|
| 何时启用 | 改动影响两个以上模块的交互 |
| 输入四层 | 现有架构 → 设计原则/约束 → 问题上下文 → 备选方向 |
| 输出格式 | ADR（架构决策记录），带方案对比和权衡理由 |
| 技术选型 | 给评估维度，不给开放式问题 |
| 模块分解 | 给拆分维度（变化频率/团队边界/技术依赖/复用边界） |
| 人审查重点 | 隐含假设、边界条件、架构冲突、复杂度合理性 |
AI 架构设计的核心不是"让 AI 替你做决定"，而是"让 AI 把决策所需要的所有信息结构化地摊在桌面上"。权衡永远是人做的------但 AI 让你不会漏掉任何一个应该纳入权衡的因素。