Convex Guidelines

This skill covers the current Convex docs surface. Start with the most relevant local guide below. If the task touches a newer platform area that is not mirrored in references/ yet, consult the linked live docs from https://docs.convex.dev/llms-full.txt before making changes.

Core rules

1. Prefer a single exported Convex function per file unless the surrounding codebase already uses another pattern. Small private helpers in the same file are fine.
2. Use precise validators when they improve safety, generated API types, OpenAPI output, or static codegen. Do not claim that args or returns validators are mandatory in every Convex function; when omitted, Convex falls back to v.any().
3. Treat v.any() as an intentional escape hatch for genuinely dynamic payloads or trusted external webhook payloads, not as the default choice for normal application data.
4. Choose the runtime deliberately. Queries and mutations stay transactional around ctx.db; actions are for external I/O and Node-only work; vector search is action-only.
5. Prefer indexes and schema design over broad filtering. If a query shape matters for correctness or scale, verify the relevant index strategy.

Use local reference guides first

Function Guidelines

Read when: Writing or modifying Convex functions, setting up HTTP endpoints, defining validators, registering functions, designing API structure, handling pagination, or choosing between query, mutation, action, internal function, and HTTP action.

Validator Guidelines

Read when: Defining argument or return validators, especially for integers, records, unions, or dynamic payloads. Keep in mind that validators are recommended for stronger types, but not universally required by Convex.