Convex Agent Guidelines

When working with Convex, it's crucial that AI agents understand the specific API patterns and best practices, as these can sometimes differ from the generalized React or Node.js knowledge the AI was trained on.

The Guidelines File

Convex automatically generates an AI guidelines file at packages/backend/convex/_generated/ai/guidelines.md. This file contains the latest rules for interacting with the Convex APIs, overriding any outdated information the AI might have.

Key Instructions for AI

Agents are explicitly instructed via AGENTS.md to read this generated file before making any modifications to Convex code. This ensures they know how to:

• Properly define queries, mutations, and actions.
• Use the correct syntax for the schema definition.
• Handle data validation and typing correctly.
• Understand the security and permission models specific to your Convex implementation.

Updating Guidelines

You can ensure your AI has the most up-to-date Convex knowledge by running the update command:

bunx convex ai-files update

This command updates the guidelines.md and installs any available Convex-specific agent skills.