convex-development

Original：🇺🇸 English

Translated

1 scriptsChecked / no sensitive code detected

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.

1installs

Sourcephrazzld/claude-config

Added on2026-02-08

NPX Install

npx skill4agent add phrazzld/claude-config convex-development

SKILL.md Content

View Translation Comparison →

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.

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

Critical Rules

ALWAYS commit
convex/_generated/
- Required for type-checking, CI/CD, team productivity
Index what you query -
```
.withIndex()
```
not
```
.filter()
```
for efficient queries
Compound indexes for multi-field filters - If querying
```
userId + status
```
, create index
```
["userId", "status"]
```
to filter at index level, not post-fetch
Paginate everything - Never unbounded
```
.collect()
```
on user-facing queries
Trust
ctx.auth
only - Never user-provided auth data

Quick Reference

Need	Use
Read data reactively	`query`
Write to database	`mutation`
External APIs, vector search	`action`
Scheduled tasks	`internalMutation` / `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.