Cursor Advanced Techniques and Troubleshooting

Author: Programmer NEO Original Link

As a practitioner in the AI field and a deep user of AI-assisted programming.

The following few sentences are what I believe you need to know the most and will be most helpful to you. Even if you don't look at the techniques below, I recommend you take a few seconds to read this.

1. The context of LLM is limited, and the more context there is, the harder it is for it to capture your intent.
2. The output of LLM is severely limited, with the current common maximum being 8192 Tokens.
3. Whether it is Cursor, Windsurf, Copilot, or Cline, they are all just your assistants. Please participate fully and maintain control and decision-making authority throughout.

The current latest version of Cursor is 0.44.10.

Cursor Usage Tips

Agent Mode Usage Tips

Search Instead of Specify

• Remove context specification to trigger automatic search in agent mode.

As shown in the image above, the context specification is empty, triggering automatic search in agent mode.

At the same time, change to providing in the description:

• Clear method names
• Key class names
• Related variable names
• Specific functionality descriptions

Let me give you an example:

请帮我实现一个方法，功能是将一个字符串转换为大写，方法名为 `toUpperCase`，类名为 `StringUtils`，字符串变量名为 `str`。

Document Processing

Reason: Documents are additional information; please only retain the most critical directive and guiding information in CHAT. Excessive information can interfere with the model's understanding of your needs.

Functional Module: Cursor Settings -> Features -> Docs:

Avoid Direct Pasting:

• Do not add large amounts of documents directly in the editing box; instead, add the documents to the document configuration and then use the @ symbol in the editing box to trigger the document configuration.

• Use the document configuration feature.

Document Specification:

• Only share necessary data for the project, rather than sharing all documents of every project.
• It is recommended to only add content that cannot be covered by training data, such as: newer library documentation, development interface documentation, etc.
• It is best to write the documents yourself (the requirement is to be concise and have a strong personal coding style), providing only method usage tutorials and brief text descriptions for easy slicing and indexing.

Document Link Configuration Method:

https://github.com/username/repo/blob/main/docs/doc.md

• Use GitHub repositories to store documentation for easy management and updates.
• You can also use cloud storage services (such as Alibaba Cloud OSS).

To specify local documents, enable local documents in Cursor Settings -> Beta -> Notepads:

Add documents in the Notepads section at the bottom of the left sidebar:

Context Management

Reason: Cursor is an assistant, not a decision-making expert. Sometimes, a human's ability to think and make a decision is beyond its reach.

• Avoid providing excessive documentation that leads to context overflow.
• Ensure that critical instructions are not overlooked.
• Prioritize providing necessary contextual information rather than all information.
• Do not fantasize that a single CHAT can solve all problems; learn to break down problems and use one CHAT for each issue.

Lint Configuration

Reason: Some projects may lead to unnecessary corrections, wasting time. In most cases, a human can quickly identify the problem at a glance.

• It is recommended to disable automatic linting.
• Use @lint to manually trigger when needed, avoiding interference from excessive automation.

Notes for Frontend Developers

When you struggle to argue with it about UI bugs, it might be more effective to just throw it a screenshot of the interface; you may discover unexpected insights.

Cursor Rule

• Make good use of Cursor Rule; you can create a .cursorrules file in the project root directory, which Cursor will reference in chat/composer.
• Specify all libraries used in the project (as necessary), UI styles, coding standards, project module definitions, etc., in the cursor rule.

There are many rules available for reference at https://cursor.directory/, and you can also define your own.

Common Problem Handling

What to do if garbled characters appear? Error example (from a friend's chat screenshot):

Please use global utf-8.

Mixed Chinese, English, and Japanese text; modified 46 instances, with no garbled characters.

Attached is a screenshot of the given garbled text and its automatic correction to the correct content.

Inaccurate Search:

• Provide more precise keywords and avoid vague descriptions.
• Use complete method names/class names/variable names, etc.

How to use agent mode?

If your version supports it, there will be options (normal and agent) at the bottom right corner of the chat box on the composer page or popup. When agent is selected, it will be white, and hovering over it will prompt that you are using agent mode.

• Checkpoints will not roll back?

Next to each checkpoint, there is a restore button. Clicking it will return to that state.

What if there are too many checkpoints and I don't know which one to roll back to? Is this applicable to versions without checkpoints or restore buttons?

If you send message A, and the cursor helps you do tasks 1, 2, and 3, which you no longer want to care about. Then you just need to double-click message A, click submit again, and a popup will remind you as shown above. Select continue and revert, and then the cursor will resend the request based on your message A. If you don't need it, just click cancel in the interface.

How to configure a custom model for the composer (providing your own Key)?

Yes, but only with an official Key.

What about non-official keys and relay stations? There is no way.

The cursor's composer will not use user-configured custom endpoints. If you have this requirement, please try Cline, which is a very useful agent (disadvantage: no checkpoints, row-level processing leads to an inability to undo all at once with ctrl + z, which means there will be many dirty versions left in the timeline during the modification process; this is the aspect I dislike the most).

Implementing new features, but the code is scattered across multiple files?

You do not need to provide context; just provide the file names and necessary interface descriptions along with the new feature description in the chat box under agent mode (please do not specify context unnecessarily, especially when files are hundreds or thousands of lines long).

If I want AI to summarize a project and generate a development guide but do not want it to modify the code, what should I do?

• First, we need to clarify that LLM context and output are limited, so the usual Chat mode cannot be used because you cannot provide all the code at once; it also cannot generate tens of thousands of lines of development guides for you.
• Therefore, we need to use tools with agent functionality, such as the agent mode in cursor compose or the cline tool. These tools essentially consist of a decision-maker and multiple executors. The decision-maker is responsible for formulating the steps required to complete the task, which are then executed by the executors. Both decision-making and execution are conducted in separate Chat sessions.

The approach is quite simple.

1. Obtain the project file directory interface, and have the decision-maker generate a reading guide, which is akin to your leader teaching you how to read the project.
2. Have the executors read each file according to the reading guide generated by the decision-maker and generate summaries of file contents and function interfaces. The reading results should be preserved in md files under the same structure in the /docs directory (e.g., src/hello/prompt.py (providing some prompt constants) => docs/src/hello/prompt.md, src/hello/fillPrompt.py (providing some utility functions to manipulate variables and information defined in the prompt) => docs/src/hello/fillPrompt.md).
3. After all executors have finished reading, the results are handed over to the thinker, who will summarize and consolidate each folder (for example, if there are prompt.md and fillPrompt.md under docs/src/hello/, aligning and summarizing will yield docs/src/hello.md). This process continues recursively until we obtain the final docs.md, which is the project development guide we need.
4. Implementation: (To be continued, as there is quite a bit of content; further writing will be done as needed.) If you are using cline, please create an MCP tool to obtain the project directory and file structure, and it should be able to annotate and retrieve files that have already been browsed and summarized.