Mike Cann

4 days ago

6 Tips for improving your Cursor Composer and Convex Workflow

Lately I have been diving deep into Cursor’s Composer in an attempt to divine the perfect workflow for using its agent mode and Convex together.

I'm not sure I have all the answers yet but I thought it would be worth sharing what I have discovered, what works, what doesn't given that this is likely to be an incredibly hot topic as we enter 2025.

Cursor

If you're not familiar with Cursor, it's part of a new breed of "AI First" IDEs. It's essentially a VSCode fork with numerous built-in plugins and enhancements.

Composer (Agent Mode)

Composer is one of the headline features of Cursor that allows you to make changes to your code in multiple steps.

Make sure you toggle it to use the “agent” mode this gives it more autonomy allowing it to pull context, run terminal commands etc.

Cursor Settings

Its certainly worth taking some time to go through the Cursor Settings yourself but here some some of the more important parts

Rules for AI

One of the most powerful ways to customize Cursor is through its "Rules for AI" setting. This acts as your personal system prompt, which Cursor automatically includes with every interaction.

It's not yet clear how much content should be included here. For now, I've focused on personal stylistic preferences that remain consistent across my projects. If you're curious, here's what my current setup looks like.

As I say, it's not yet clear what the best format or length should be for this, as you can tell, mine is fairly long. I also came across this tweet from one of the Cursor developers that suggests using a shorter version without examples.

I think this is something we'll have to experiment with more. I'm keen to hear your thoughts and experimental results!

Yolo Mode

Depending on your feelings about Skynet you may or may not wish to enable yolo mode. This allows the agent to run terminal commands and delete files without your explicit confirmation first.

I personally welcome our robotic overloads 🤖♥️ and have this enabled.

Docs

This section is especially important for Convex developers. Since we'll be using Claude exclusively for agentic composer, we're limited by the model's training set. While Claude knows about Convex, its knowledge can be patchy or outdated, so we need to give it a helping hand.

One effective way to do this I have found is by adding a custom “doc” for Convex.

If you click “Add new doc” then choose the root of the Convex docs then Cursor will then go ahead and index all the sub-pages from the Convex docs.

After indexing, the agent can perform vector searches to find the most relevant, up-to-date documentation based on your prompts. I'll explain how to use this feature later in this post.

The Project

To explore the best practices for using agentic composer with Convex, I built a low-medium complexity project that initially used only local state. I then used composer to upgrade the project to Convex.

To make this process more rigorous, I repeatedly returned to the working local state version, making just one or two small changes before trying the upgrade process again.

The non-deterministic nature of LLMs made this challenging—running the same prompt multiple times without changing any variables produced different results each time.

Nevertheless, I eventually developed a general approach that proved fairly repeatable and effective.

The project itself is a tic-tac-toe clone called "tic-tac-convex" and its source code can be found here.

The video demonstrates how you can authenticate to create a user, create a new game, and challenge an AI opponent to play against you.

Attempts & Result

Over the course of the next several days I did some reading, ran many experiments and took copious notes as I tried to narrow down on the best way to integrate Convex into the project.

I won't bore you with all the mistakes and dead ends I encountered. Instead, I'll distill what I think are the most important lessons learned. While much of this may just be "good prompting" technique, I'll share it anyway in case you're not familiar.

The Tips

Context is king. LLMs are smart but are limited by context and as they are unable to know what they don't know then you have to give them as much context about your project and requirements as you can.

I would recommend watching this video which does a great job of explaining context and complexity with LLM agents and how that changes over the lifetime of a project: https://www.youtube.com/watch?v=z_7CLMYKwGs

1. Reference the Convex Docs

As mentioned in the section above you can “fine tune” on the latest Convex best practices by referencing the docs. You do this by adding a doc in the Cursor Settings called “Convex” then in your prompt type “@Convex” this then allows the agent to run a vector search against the Convex docs.

I found this to be really effective with improving the general convex knowledge of the agent.

2. Add a “convex_instructions.md”

While referencing the @Convex docs is helpful, I found the agent still made occasional basic Convex-related mistakes. To prevent these frustrating errors, I created a document containing common issues and key excerpts from the Convex docs. This approach proved effective at reducing simple mistakes.

I now include these instructions as a reference in my Convex-related prompts.

I suspect this file would need to be updated over time as you work on different projects and encounter other “silly” Convex mistakes from the agent but if you are interested in a good starting point this is the one I found effective for this project: https://github.com/get-convex/tic-tac-convex/blob/98ade9998b0845816e8511abf24b2ba08dacee29/instructions/convex_instructions.md

3. Update your README.md

The agent needs context about your project. While it can infer some details from the files it reads, this becomes more challenging as your project grows. Providing general information about your project gives the agent a helpful head start.

Rather than including this information in each prompt, it's better to write a comprehensive README.md file in your project root and reference it.

Some people advocate for using a more complex Product Requirements Document (PRD), though I found this unnecessary for a project of this size, the concept remains the same.

4. Install and run Convex yourself

I tried multiple times to have the agent install and set up Convex, but it was often frustrating and unreliable. The main issue was that it would run npx convex dev immediately, which would trap it in the CLI development loop.

Instead, I found it simpler to handle the setup manually by running bun install convex and bun convex dev in a separate terminal window.

Keeping Convex running is crucial because it automatically generates the client-side types. Without this, the agent can get stuck in a linting loop since it can't access the queries and mutations it created on the server.

5. Schema then Functions then React then Tidy

Although this tic-tac-convex project is relatively simple, I found it invaluable to break the Convex upgrade into distinct steps, verifying everything worked after each phase.

These steps were:

1. Generate the schema
2. Create the Convex queries, mutations, and actions
3. Update the React code to use these new Convex functions
4. Clean up redundant code, organize files, and improve maintainability

Attempting all these changes at once led to inevitable mistakes or omissions of previously discussed requirements.

The final cleanup step revealed an unexpected strength of the AI. I would test its capabilities with prompts I thought would fail, like:

This React component is getting too large lets break it up into logical chunks to make it easier to reason about

To my delight, it consistently made intelligent decisions about component boundaries. This suggests exciting possibilities for a collection of specialized refactoring prompts in the future.

6. Copy-paste Typescript errors

Cursor has recently added linting support for Composer, which allows the agent to fix its mistakes right after generating changes:

This ability is phenomenal and solves 90% of code generation issues.

However, this feature only works on a per-file basis. If a change in one file causes another file to break due to changed references, the inline linter won't catch it.

To address these issues, I recommend keeping TypeScript running in a terminal window throughout your development. This helps monitor your code's overall health as Composer makes changes, and catches the remaining 10% of issues.

By copying the error messages from the terminal and pasting them into Composer with a simple "I have errors" prompt, the agent was typically able to resolve these issues.

This technique also works for runtime errors. Simply copying errors from the Chrome console and pasting them into Composer typically allowed it to fix the issue, at least for this project.

The Result

So after all that this was the final result that composer ended up with, a working Convex powered multiplayer tic-tac-toe game:

If you want to try it out a playable demo for this is available here: https://tic-tac-convex.vercel.app/

The model made a few visual changes from the initial version. While I'm not sure why these changes were made, it should be straightforward to prompt it to restore the original design.

Notepads vs .cursorrules vs instructions.md?

One of the latest features of Cursor is Notepads. This feature provides a referenceable location for important context such as:

• Project architecture decisions
• Development guidelines and standards
• Reusable code templates
• Documentation that needs to be referenced frequently
• Team-specific conventions and rules

While it's great that Notepads can contain file attachments and other references (except docs, oddly enough), they fall short compared to explicitly defined project files since they can't be shared with team members, they remain local to your personal Cursor instance.

In my view, Notepads feels like an incomplete feature. Cursor would be better off enhancing their existing .cursorrules files or custom instructions markdown files rather than introducing another way to add context.

Conclusion

It's still early days for agent-based text-to-code conversion. While there are rough edges in the development process, I believe these issues will eventually be resolved.

The future seems clear: "prompt-first" coding is poised to become one of the biggest programming trends of 2025, with Cursor's Composer leading this revolution.

I look forward to exploring more of these tools and techniques in the coming months!