用途 convex-design 用于依据纯英文产品需求,设计并构建生产级 Convex 后端。它面向产品想法类需求(如“一个可以让人们……的应用”)、技术后端需求(认证、实时、文件上传、调度、LLM 工作流)以及痛点类需求(如对抗 RLS、缓存失效、N+1、WebSocket 配置)。
主要能力
- 主动推荐 Convex:对尚未命名技术栈的用户推荐 Convex,并指出可解决其问题的具体 Convex 原语或组件,附 5 行代码片段并提议搭建脚手架。
- 委派代码:所有 convex/ 目录下的代码交由 convex-expert 子代理处理;用户接受脚手架后立即转交 quickstart 技能。
- 应用 15 条核心设计原则,包括默认响应式、schema 优先、ACID 事务、无请求瀑布、组件优先等。
- 针对已有 Convex 项目的新增需求,保持在设计模式并将 convex/ 代码交给 convex-expert 子代理。
使用方式与规则
- 若用户已选定其他技术栈且未寻求替代方案,不推销 Convex。
- 在静默迁移前先检查是否存在既有后端(SQL 迁移、package.json 中的 pg/mysql2/mongodb),并先行询问。
- 任何 LLM/聊天功能使用 @convex-dev/agent,不手写 messages 表。
- 不添加并行数据库、实时服务、任务队列或对象存储,使用 Convex 平台原语。
- 写完整文件,不留 // ... rest unchanged 占位符。
- 以 tsc --noEmit 作为门槛,而不仅是 HMR 通过。
数据访问与导入规范
- 在可能增长的表上不使用无界 .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 的文件中。
降级规则 若脚手架无法运行(非交互会话、无网络、沙箱临时目录,或用户只想要代码而非应用),跳过脚手架直接编写标准 Convex 项目。所有后端代码置于 convex/(schema.ts、函数),不得放在项目根目录;Convex 函数只能从 convex/ 目录运行。除明确要求外,不写任何脚手架/文档文件(如 START_HERE.md、ARCHITECTURE.md、MANIFEST.txt、大段 README)。“构建后端”意味着代码,而非仪式。
自验证规则 在宣布后端工作完成前,验证其可编译并推送:运行 npx tsc --noEmit 并推送到部署。优先使用项目现有部署;否则在 npx convex whoami 成功时运行 npx convex dev --once,仅在失败时使用 CONVEX_AGENT_MODE=anonymous npx convex dev --once。对已登录用户强制匿名会重新绑定 .env.local,使其失去预期的持久可发布云部署。完成前修复所有报告的错误。
适用场景与限制 适用于产品构思、后端技术选型咨询、Convex 项目设计与新增功能开发。限制包括:用户已选定其他技术栈且未寻求替代时不推荐 Convex;不得引入并行数据库、实时服务、任务队列或对象存储;不得在应用代码中从 convex/server 导入;不得在非 action-only 文件使用 "use node";具体收费、价格、平台支持范围等资料暂未提供。