AgentSkillsCN

convex-review

针对生产就绪性，制定全面的Convex代码审查清单。适用于在部署前审计Convex代码库、审查Pull Request，或在Convex函数中排查安全与性能问题时使用。

SKILL.md
--- frontmatter
name: convex-review
description: Comprehensive Convex code review checklist for production readiness. Use when auditing a Convex codebase before deployment, reviewing pull requests, or checking for security and performance issues in Convex functions.

Convex Code Review

Security Checklist

1. Argument AND Return Validators

  • • All public query, mutation, action have args validators
  • • All functions have returns validators
  • • No v.any() for sensitive data
  • • HTTP actions validate request body (Zod recommended)

Search: query({, mutation({, action({ - check each has args: AND returns:

2. Error Handling

  • • Uses ConvexError for user-facing errors (not plain Error)
  • • Error codes are structured: { code: "NOT_FOUND", message: "..." }
  • • No sensitive info leaked in error messages

Search: throw new Error should be throw new ConvexError

3. Access Control

  • • All public functions check ctx.auth.getUserIdentity() where needed
  • • Uses auth helpers (requireAuth, requireRole)
  • • No client-provided email/username for authorization
  • • Row-level access verified (ownership checks)

Search: ctx.auth.getUserIdentity should appear in most public functions

4. Internal Functions

  • • ctx.runQuery, ctx.runMutation, ctx.runAction use internal.* not api.*
  • • ctx.scheduler.runAfter uses internal.* not api.*
  • • Crons in crons.ts use internal.* not api.*

Search: api. in convex directory - should not be used for scheduling/running

5. Table Names in DB Calls

  • • All ctx.db.get, patch, replace, delete include table name as first arg

Search: db.get(, db.patch( - first arg should be quoted string

Performance Checklist

6. Database Queries

  • • No .filter() on queries (use .withIndex() or filter in code)
  • • .collect() only with bounded results (<1000 docs)
  • • Pagination for large result sets

Search: \.filter\(\(?q, \.collect\(

7. Indexes

  • • No redundant indexes (by_foo + by_foo_and_bar)
  • • All filtered queries use .withIndex()
  • • Index names include all fields

Review: schema.ts index definitions

8. Date.now() in Queries

  • • No Date.now() in query functions
  • • Time filtering uses boolean fields or client-passed timestamps

9. Promise Handling

  • • All promises awaited (ctx.scheduler, ctx.db.*)

ESLint: no-floating-promises

Architecture Checklist

10. Action Usage

  • • Actions have "use node"; if using Node.js APIs
  • • ctx.runAction only when switching runtimes
  • • No sequential ctx.runMutation/ctx.runQuery (combine for consistency)

11. Code Organization

  • • Business logic in helper functions (convex/model/)
  • • Public API handlers are thin wrappers
  • • Auth helpers in convex/lib/auth.ts

12. Transaction Consistency

  • • Related reads in same query/mutation
  • • Batch operations in single mutation
  • • Mutations are idempotent

Quick Regex Searches

IssueRegexFix
.filter()\.filter\(\(?qUse .withIndex()
Missing returnshandler:.*async without returns:Add returns:
Plain Errorthrow new Error\(Use ConvexError
Missing table namedb\.(get|patch)\([^"']Add table name
Date.now() in queryDate\.now\(\)Remove from queries
api.* schedulingapi\.[a-z]Use internal.*

Production Readiness

  1. •Security: Validators + ConvexError + Auth checks + Internal functions
  2. •Performance: Indexes + Bounded queries + No Date.now()
  3. •Architecture: Helper functions + Proper action usage + "use node"
  4. •Code Quality: Awaited promises + Table names + Return validators