> 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-with-ai-agents/planning-before-you-build.md).

# Planning before you build

## Opening: The Problem or Principle

Skipping the planning step feels like saving time. It isn’t. Without a clear target, the AI makes assumptions about what you want, and those assumptions compound. A misread requirement early can mean rebuilding a system later. The rework almost always takes longer than the plan would have.

In Sandbox Studio, planning is not a separate phase from making. It is the first build step: define the result, choose the smallest useful version, and decide what should stay unchanged.

## The Core Explanation

### A Plan Defines the Target

A useful plan describes the experience you want, not only the feature name. “Add an inventory” is a label. “Let the player collect three items, see them in a small HUD bar, and use one item with a key press” gives the work a target.

The target should include the current behavior, the desired behavior, and the conditions that prove the feature works. This gives the AI something concrete to build toward and gives you something concrete to review.

Good planning also names what should not change. If the existing player controller, camera, or scene setup must stay the same, say that before implementation starts.

### Context Comes Before Instructions

The AI needs project context before it can plan well. Give it the relevant nodes, scene setup, asset paths, errors, constraints, and user experience goals.

For Sandbox Studio, this can include the kind of game you are making, how the player moves, what UI already exists, which assets should be reused, and which engine patterns the feature should follow.

{% hint style="info" %}
*NOTE: Planning with missing context can produce a clean-looking plan that is wrong for the project. A short accurate context block is better than a long request with the important details missing.*
{% endhint %}

### The Smallest Useful Slice Comes First

Large ideas become easier to build when they are split into small, complete slices. A slice should produce visible progress that can be tested, even if it is not the final version.

For example, a full quest system may include dialogue, objectives, rewards, save data, UI, and editor setup. The first slice could be one character giving one objective and the player seeing that objective update on screen.

This approach keeps the work understandable. It also gives the AI fewer places to make assumptions and gives you faster feedback on whether the direction feels right.

### Use AI to Compare Approaches Before Choosing One

AI is useful during planning because it can surface options quickly. Ask for two or three approaches, the tradeoffs, and which files or systems each approach would touch.

Choose the approach before asking for implementation. If you skip that decision, the AI may choose for you, and the chosen path may not match your priorities.

The best plan is specific enough to guide the work but not so rigid that it ignores discoveries during implementation. If new information changes the approach, update the plan before continuing.

### A Plan Is a Working Agreement

Once you approve a plan, it becomes the reference point for the build. The AI should stay within that scope, and you should use the plan to judge whether the output did too.

Plan drift is easy to miss. It often looks like progress: a new helper function gets added, a secondary system gets refactored, the camera gets tweaked because it was in the way. Each change seems reasonable in isolation. By the end, the implementation has touched files it shouldn’t have and introduced decisions you didn’t review.

If the implementation starts changing unrelated systems or solving a different problem, return to the plan. Either narrow the work back to the approved scope or revise the plan deliberately before continuing.

## Practical Guidance

* Write the player or user outcome before naming the technical solution.
* Describe the current behavior and the desired behavior.
* List the systems, files, nodes, assets, or UI that matter to the feature.
* State what should remain unchanged.
* Give the AI project context before asking it to plan.
* Ask the AI for a plan before implementation when the task touches multiple systems.
* Build the smallest useful slice first.
* Review the plan for scope, risks, and missing context before approving it.
* Update the plan when new information changes the right approach.

## Common Mistakes

| Mistake                                               | What to do instead                                                     |
| ----------------------------------------------------- | ---------------------------------------------------------------------- |
| Planning from a feature name only                     | Describe the experience, behavior, and success condition.              |
| Building the full idea at once                        | Start with the smallest complete slice that can be tested.             |
| Letting the AI choose the architecture without review | Ask for options and tradeoffs, then choose the approach intentionally. |
| Leaving constraints unstated                          | Tell the AI what files, systems, or behavior should remain unchanged.  |
| Treating the plan as permanent                        | Revise the plan when implementation reveals better information.        |

<br>


---

# 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-with-ai-agents/planning-before-you-build.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.