markdown-site: Skill for Claude Code

Core Development Guidelines Skill

Deep reflection and problem-solving methodology for full-stack Convex development.

1. Reflect deeply before acting

Before implementing any solution, follow this process:

1. Reflect: Carefully consider why the current implementation may not be working
2. Identify: What's missing, incomplete, or incorrect based on the request
3. Theorize: Different possible sources of the problem or areas requiring updates
4. Distill: Narrow down to 1-2 most probable root causes or solutions
5. Proceed: Only move forward after clear understanding

Never assume. If anything is unclear, ask questions and clarify.

2. Convex implementation guidelines

Core principles

Direct mutation pattern:

• Use direct mutation calls with plain objects
• Create dedicated mutation functions that map form fields to database fields
• Form field names should exactly match database field names when applicable

Best practices:

• Patch directly without reading first
• Use indexed queries for ownership checks (not ctx.db.get())
• Make mutations idempotent with early returns
• Use timestamp-based ordering for new items
• Use Promise.all() for parallel independent operations to avoid write conflicts

Essential documentation

Functions:

• Mutations: https://docs.convex.dev/functions/mutation-functions
• Queries: https://docs.convex.dev/functions/query-functions
• Validation: https://docs.convex.dev/functions/validation
• General: https://docs.convex.dev/functions

Core concepts:

• Zen of Convex: https://docs.convex.dev/understanding/zen
• TypeScript best practices: https://docs.convex.dev/understanding/best-practices/typescript
• Best practices: https://docs.convex.dev/understanding/best-practices/
• Schema validation: https://docs.convex.dev/database/schemas

Authentication:

• WorkOS AuthKit: https://workos.com/docs/authkit/vanilla/nodejs
• WorkOS docs: https://workos.com/docs
• Convex + WorkOS setup: https://docs.convex.dev/auth/authkit/