核心论点：API 和数据库是系统的两个"承重墙"——接口契约定义模块间怎么通信，数据模型定义信息怎么存储。这两样东西一旦定了就很难改。让 AI 参与设计，不是让它"代替人做决定"，而是让它"穷举你没有考虑到的约束"。
为什么 API 和数据库设计值得单独一篇
回顾 SDD（规约驱动开发）中定义的 Agent 流水线：
architecture-designer → coder → test-generator → code-reviewer但 architecture-designer 出的设计是模块级的——“experiment_service 负责分流和记录，experiment_metrics 负责采集”。它不定义：
- API 的 URL 结构、请求/响应格式、错误码体系
- 数据库的表结构、索引、迁移策略
这两件事在"设计"和"编码"之间有一个空档——架构设计文档太粗，代码太细。API 契约和数据模型正是这个中间层。
API 设计——AI 帮你穷举约束
API 设计中最容易犯的错误
看一下 Shop-Agent 项目早期的一个 API：
# 早期版本——有几个常见问题@router.post("/chat")asyncdefchat(request:ChatRequest):...有其他非功能性问题容易漏掉：
| 问题 | 影响 |
|---|---|
ChatRequest没有max_tokens限制 → 用户发超长内容 | LLM 费用暴涨 |
| 响应没有分页 → 聊天记录一多，响应体 5MB+ | 接口超时 |
POST /chat和POST /chat/history语义不一致 | 重构成本 |
| 错误响应没有统一格式 → 前端解析异常困难 | 联调延期 2 天 |
这些问题在"设计"阶段都可以避免——但人做 API 设计时，通常只关注"功能能不能用"，不关注这些工程约束。
AI 的价值：它可以对照一个完整的 API 设计检查清单，逐项验证。
实战：让 AI 审查 API 设计
@ src/modules/chat/routers/chat.py 审查这个模块的 API 设计，按以下维度检查： 1. RESTful 规范：URL 命名、HTTP 方法、状态码 2. 安全性：输入校验、限流、认证 3. 性能：分页、字段过滤、响应体大小 4. 一致性：错误格式、命名风格、版本策略 5. 可维护性：向后兼容、废弃策略 输出问题的严重程度（高/中/低）和修复建议。AI 输出类似 code-reviewer 但聚焦 API 层面的审查报告，会发现：
- 缺少
page_size上限（DOS 风险） POST用了不应该的幂等语义- 错误响应格式不统一（有的是
{"error": ...}，有的是{"detail": ...}）
从零设计一个新 API
需求：在 Agent 对话系统中加 A/B 实验管理功能。 功能： - 创建实验（指定名称、分流比例、变体配置） - 启用/关闭实验 - 查询实验列表和状态 - 查看实验结果（各变体的指标对比） 要求： - RESTful 风格 - 统一错误格式 {"code": "ERROR_CODE", "message": "...", "details": {}} - 需要分页的接口统一用 page/page_size - 实验配置变更需要版本号（乐观锁） - 输出 OpenAPI 3.0 格式的文档AI 输出包含完整的 endpoint 列表和契约文档。更重要的是，AI 会主动做出设计决策并说明理由：
- 用 PATCH 而非 PUT：实验配置是部分更新（如只改分流比例）
- 删除限制草稿状态：防止误删运行中的实验
- version 字段做乐观锁：防止并发修改冲突
和直接让 coder 实现的区别：coder 看到"创建实验"会立刻开始写代码，但不会思考 PATCH vs PUT、乐观锁、删除的安全策略——这些是"设计决策"，不是"实现细节"。
数据库设计——AI 帮你从前到后走一遍
数据建模中最容易犯的错误
-- 人凭直觉写的表CREATETABLEexperiments(idVARCHARPRIMARYKEY,nameVARCHAR(100),config JSON,-- 问题 1：JSON 字段无法索引查询statusVARCHAR(20),-- 问题 2：没有 CHECK 约束created_atTIMESTAMP,updated_atTIMESTAMP);问题：
config JSON——“分流比例"在 JSON 里，没法用 SQL 查"所有分流比 50/50 的实验”status VARCHAR——没有约束，可以写入"actvie"（拼写错误）- 缺少实验变体表（variants）——当前是一对一，将来可能需要 A/B/C 多变体
- 缺少实验结果表——每次查结果要扫全表
两步走：先让 AI 分析查询模式，再决定索引
这可能是数据库设计中 AI 最有价值的环节。人的问题是：先设计表，再想索引。正确顺序是：先想"我会怎么查"，再决定"怎么建索引"。
@ …/experiment_service.py（分析业务查询模式） 基于这个 service 的代码，分析它对数据库的所有查询模式，然后给索引建议。AI 输出覆盖按状态过滤、按用户查分流、按实验+时间查指标等场景，并给出对应索引建议。关键价值在第 4 条：
4. JSON 字段查询 → config->>'traffic_split' = ? → 问题：无法用 B-tree 索引 → 建议：traffic_split 提出来做独立字段这种问题如果到上线后才暴露，改表成本就大了。
API 设计 + 数据库设计 + 代码生成的串联
把 api-designer 和 database-designer 插入流水线后，各 Agent 之间的约束传递关系：
api-designer 输出 → database-designer 输入 POST /experiments → experiments 表 request: {name, → name VARCHAR(100) NOT NULL traffic_split, traffic_split JSON NOT NULL variants[]} variants 独立表（1:N） database-designer 输出 → coder 输入 experiments 表结构 → Pydantic model 的字段定义 索引策略 → repository 层的查询方式核心要点
- API 和数据库是系统的承重墙——让 AI 参与设计，不是让它代替人做决定，而是让它穷举你没想到的约束。
- API 设计检查清单（RESTful 规范 + 安全 + 性能 + 一致性 + 可维护性）是 AI 一次性检查的——人手动逐项过太容易漏。
- 数据库设计先分析查询模式，再定索引。而不是先建表再补索引。让 AI 读 service 代码反推查询模式，索引建议更精准。
- api-designer → database-designer → coder是标准的新模块设计链。API 契约约束数据库字段，数据库字段约束代码 model——每一步的输出是下一步的输入。
- 小改动不需要这些 Agent。给已有接口加字段、给已有表加列——直接 Craft 就够了。Agent 的价值在"从零设计"，不在"打补丁"。
