AgentSkillsCN

convex-development

运用 Convex 数据库的最佳实践，从成本优化、性能提升、安全保障到架构设计全方位发力。 适用场景：构建 Convex 后端、优化查询、处理嵌入式向量搜索、审查 Convex 代码、设计数据模型、规划迁移方案，或就 Convex 架构展开深入探讨。 关键词：Convex、实时数据库、查询、变更操作、动作、索引、分页、向量搜索、嵌入式表示、数据模型、迁移、ctx.auth、convex-helpers、带宽。

SKILL.md
--- frontmatter
name: convex-development
description: |
  Apply Convex database best practices for cost optimization, performance, security, and architecture.
  Use when: building Convex backends, optimizing queries, handling embeddings/vector search,
  reviewing Convex code, designing schemas, planning migrations, or discussing Convex architecture.
  Keywords: Convex, real-time database, queries, mutations, actions, indexes, pagination,
  vector search, embeddings, schema, migrations, ctx.auth, convex-helpers, bandwidth.

Convex Development

Best practices for robust, secure, performant, cost-effective Convex backends.

Core Principle

Deep modules via the convex/model/ pattern. Most logic should be plain TypeScript; query/mutation wrappers should be thin.

code
convex/
  _generated/         # MUST commit to git!
  model/              # Business logic (testable, reusable)
  users.ts            # Public API (thin wrappers)
  schema.ts

Critical Rules

  1. •ALWAYS commit convex/_generated/ - Required for type-checking, CI/CD, team productivity
  2. •Index what you query - .withIndex() not .filter() for efficient queries
  3. •Paginate everything - Never unbounded .collect() on user-facing queries
  4. •Trust ctx.auth only - Never user-provided auth data

Quick Reference

NeedUse
Read data reactivelyquery
Write to databasemutation
External APIs, vector searchaction
Scheduled tasksinternalMutation / internalAction

Anti-Patterns Scanner

Run scripts/anti_patterns_scanner.py ./convex to detect common issues.

Detailed References

For comprehensive guidance, see:

  • •references/cost-mitigation.md - Bandwidth optimization, indexing, pagination
  • •references/embeddings-vectors.md - Vector search patterns, co-location decisions
  • •references/query-performance.md - Compound indexes, query segmentation, caching
  • •references/security-access.md - Auth patterns, RLS, RBAC, convex-helpers
  • •references/schema-migrations.md - Expand/Contract pattern, environment management
  • •references/architectural-patterns.md - File organization, state machines, naming

Philosophy

  • •Cost First: Bandwidth is often the largest cost. Index aggressively, paginate everything.
  • •Security First: Never trust client input. Always use ctx.auth.
  • •Reactivity is Power: Use useQuery for real-time updates; don't forfeit with one-off fetches.
  • •Type Safety End-to-End: Leverage Convex's full type chain from database to UI.