核心论点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,-- 问题 1JSON 字段无法索引查询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 的价值在从零设计不在打补丁。