> For the complete documentation index, see [llms.txt](https://studio-docs.sandbox.game/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://studio-docs.sandbox.game/working-efficiently-with-ai/writing-effective-prompts.md).

# Writing effective prompts

## **The Principle**

Cursor can already see your entire Sandbox Studio project: the file tree, the engine source, every existing class and pattern. What it needs from you is direction, not description. The most effective prompts are specific about intent and explicit about where to look.

## **What an Effective Prompt Contains**

### **Your goal**

What you are building and why it exists in the game. One or two sentences. "A pickup node that adds ammo to the player inventory when the player overlaps it."

### **Where to look**

Name the closest existing file as a reference and identify which engine system is involved. Cursor will read those files and use them as its pattern. "Look at HealthPickup.ts for the overlap pattern. The inventory system is in InventoryComponent.ts."

When you want Cursor to use a specific engine pattern, tell it to check the .engine folder. "Check the engine source for how SceneNode attachment works before implementing this" gives Cursor access to the authoritative reference rather than a guess.

### **What to create or modify**

Be explicit about whether this is a new class or an addition to something that already exists, and which file to change or create.

### **What to leave alone**

Name anything that should not be touched. Cursor can see every file in your project, so it needs to know what is in scope and what is not. "Do not modify InventoryComponent.ts directly. Only call its public methods."

## **Using @ References**

When you reference a file using @filename, Cursor brings that file into active context. It is not just aware the file exists; it is reading it as part of the current task. This is the most reliable way to anchor Cursor to the exact pattern you want it to follow.

@PlayerPawn.ts in your prompt means Cursor is working from the actual code, not a general understanding of what a player Pawn might look like. Use this whenever pattern accuracy matters.

{% hint style="warning" %}
*NOTE: Naming a file in prose and using @filename are not the same thing. An @ reference actively loads the file into the current context window. When pattern accuracy matters, always use an explicit @ reference.*
{% endhint %}

## **Plan Before You Build**

For any feature that involves multiple systems or new classes, ask Cursor to plan before it builds. "Before writing any code, explore the relevant files and outline how you will structure this" produces a plan grounded in the real project rather than a generic one.

Review the plan. Check that the classes it names exist, that the files it intends to modify are the right ones, and that the engine patterns it references match what is in .engine. This is the moment to catch a wrong assumption before it becomes wrong code.

{% hint style="info" %}
*TIP: After Cursor produces a plan, ask it to verify: "Confirm your planned approach matches the pattern in the engine source." Catching a discrepancy here saves a full round of correction.*
{% endhint %}

## **Practical Guidance**

* Point Cursor at an existing file that uses the pattern you want. Let it read the pattern rather than describing it yourself.
* Use @file references to bring the most relevant files into active context at the start of the prompt.
* Tell Cursor to check the .engine folder when you want it to verify engine behaviour before implementing.
* Structure every prompt around four things: goal, where to look, what to change, what to leave alone.
* For complex features, ask for a plan first and ask Cursor to ground it in the actual project files.
* State what is out of scope explicitly. Cursor can see every file and needs to know which ones are not part of this task.

## **Common Mistakes**

| Mistake                                                                  | What to do instead                                                                        |
| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
| Writing long explanations of how the engine works                        | Point Cursor at the engine source or a relevant existing file. It can read the real thing |
| Giving no file references and expecting Cursor to find the right pattern | Name the closest existing file as a reference in the prompt                               |
| Forgetting to name what is out of scope                                  | Explicitly state which files or systems should not be modified                            |
| Asking for implementation without a plan on complex features             | Ask for a plan grounded in the actual project files first                                 |
| Naming files in prose instead of using @ references                      | Use @filename to actively load the file into context, not just mention it                 |
| Not asking Cursor to verify its plan against the engine source           | Add "verify against .engine" as a step before implementation begins                       |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://studio-docs.sandbox.game/working-efficiently-with-ai/writing-effective-prompts.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.