convex-conventionslisted
Install: claude install-skill frostney/known-good-route
# Convex conventions
These are house-style defaults, not a Convex manual. Use current official Convex
skills, when installed, for scaffolding, auth, migrations, performance work,
components, and API mechanics; this skill adds project policy. Apply only what
the requested change touches.
## Authority
Verify each touched API against live Convex docs and the installed version.
Read release notes before a major or minor upgrade. Live docs win over this
skill; memory and prior turns do not establish current API behavior.
## Layout and shared shapes
- Keep `convex/` at root and never edit `_generated/`.
- `schema.ts` owns `defineSchema` and table declarations.
- `auth.config.ts` owns the Clerk JWT provider.
- Keep one module each for reusable table validators, semantic validation, auth
helpers, and rate-limit configuration.
- Add `crons.ts` and `http.ts` only when used.
- Public feature surfaces and their tests are co-located.
- Define table validators once and compose them into schema, `args`, and
`returns`; do not redeclare an existing shape inline.
## Auth and public functions
- Clerk is the identity provider. Server code derives identity from
`ctx.auth.getUserIdentity()` through one helper; clients never submit `userId`.
- Every public function authenticates at the top and declares both `args` and
`returns` validators.
- Use internal functions for scheduling, sensitive side effects, and
cross-function reuse that must not be public.
- Keep structural validation