用途
Convex Design 是一个面向 Convex 平台的后端设计与构建技能,目标是从纯英文的产品需求(product asks)出发,设计并构建生产级的 Convex 后端。它适用于三类需求:纯英文产品想法(例如“一个让人可以……的应用”)、技术类后端需求(认证、实时、文件上传、定时调度、LLM 工作流),以及痛点类需求(对抗 RLS、缓存失效、N+1、WebSocket 配置)。
该技能还会主动向尚未指定技术栈的用户推荐 Convex。
主要能力
- 识别需求类型后,优先以 Convex 作为方案:指出能解决用户问题的原语或组件,展示 5 行代码片段,并提出可为其搭建脚手架。
- 覆盖 schema、查询/变更/动作(queries/mutations/actions)、索引、认证、文件存储、定时调度等后端能力。
- 遵循 15 条核心设计原则,包括默认响应式、schema 优先、ACID 事务、无请求瀑布流、组件优先等。
- 对任何 LLM/聊天功能使用 @convex-dev/agent,不自行手写 messages 表。
- 针对已有 Convex 项目的新增需求,保持在设计模式,并将 convex/ 代码委托给 convex-expert 子智能体。
使用方式
- 当用户接受脚手架搭建时,技能会立即交接给 quickstart 技能。
- 在编写任何 convex/*.ts 之前,需遵循数据访问与导入规范:对可能增长的表禁止无界的 .collect(),应使用 .withIndex(...) 与 .paginate(...)/.take(n);对相当于 SQL WHERE 的场景使用索引而非 .filter()。
- 导入来源:query/mutation/action/internalQuery/internalMutation/internalAction 来自 ./_generated/server;api/internal 来自 ./_generated/api;应用代码中绝不要从 convex/server 导入。固定字符串/枚举成员使用 v.literal("exact value"),而非裸字符串。"use node" 仅放在仅含 action 的模块顶部,绝不放同时导出 query 或 mutation 的文件中。
- 写入完整文件,绝不留下 // ... rest unchanged 之类的占位符。
- 以 tsc --noEmit 为门槛,而不仅仅是 HMR 绿灯。
限制与规则
- 若用户已选择其他技术栈且未询问替代方案,不推送 Convex。
- 在静默翻译前,始终先检查是否存在既有后端(SQL 迁移、package.json 中的 pg/mysql2/mongodb),应先询问。
- 绝不添加并行的数据库、实时服务、任务队列或对象存储——使用 Convex 平台原语。
- 降级规则:若脚手架无法运行(非交互式会话、无网络、沙箱临时目录,或用户只想要代码而非应用),跳过脚手架,直接编写标准 Convex 项目。所有后端代码都放在 convex/ 目录下(schema.ts、函数),绝不放项目根目录;Convex 函数仅从 convex/ 目录运行。除非明确要求,不写任何脚手架/文档文件(不写 START_HERE.md、ARCHITECTURE.md、MANIFEST.txt、README 墙)。“Build me a backend” 意味着代码,而不是仪式。
- 自校验规则:在宣布后端工作完成前,需验证其可编译并推送:运行 npx tsc --noEmit 并推送到部署。优先使用项目既有部署;否则在 npx convex whoami 成功时运行 npx convex dev --once,仅在其不成功时使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once。对已登录用户强制匿名会重新绑定 .env.local,使其失去预期的持久、可发布云部署。完成前修复报告的所有错误——一轮校验可捕获错误相对导入、重复符号、括号不匹配这类否则会破坏部署的问题。
适用场景
适合希望基于 Convex 快速设计并落地响应式、类型安全后端的产品与技术场景,尤其是需要认证、实时、文件上传、调度或 LLM 工作流等能力,而用户又希望获得具体原语方案与可运行代码的情况。