Skip to content
vibespell

.cursor/rules/project.mdc

Cursor rules for Godot

Cursor rules are a markdown file with a short frontmatter header. Cursor attaches them to the agent so it stops guessing how this repo builds, tests, and styles code. This copy is written for a Godot project. This repository is a Godot 4 project. Scenes compose nodes, GDScript is statically typed where the file already types it, and gameplay reacts to signals instead of polling.

The example uses a balanced, readable style, pragmatic tests, and comments only where the intent is not obvious. Open the generator to make the agent stricter, switch to test-first, quiet the comments, or pick a different file.

The example assumes Godot 4 and GDScript. It does not assume C# or a third-party framework. If the repo is a Godot 3 project, do not use Godot 4-only APIs.

Customize in the generatorBrowse the library

Example file

Balanced strictness, readable style, pragmatic tests. Download name: project.mdc. Legacy path: .cursorrules

---
description: "Working rules for a Godot repository"
globs: "**/*"
alwaysApply: true
---

# Project rules

Follow these rules on every task in this Godot repository.
If the project still uses a root `.cursorrules` file, keep the same rules there.

## Stack

This repository is a Godot 4 project. Scenes compose nodes, GDScript is statically typed where the file already types it, and gameplay reacts to signals instead of polling.

## Layout

- Scenes (`.tscn`) and their scripts sit together in the feature folder the project already uses.
- Autoloads are rare. Do not add a new autoload for state a scene can own.
- Shared resources (`.tres`) hold data. Do not bury tuning numbers in `_ready`.

## Commands

- Editor: `Open the project in Godot 4`
- Script check: `Use the editor's script error list before you finish`
- Play: `Run the scene you changed (F6) or the main scene (F5)`

Use the script the repo already defines when it differs from the command above.

## Conventions

- Prefer signals instead of polling. Connect them in the editor or once in `_ready`.
- Use `@export` for designer-facing values and `@onready` for node references you need up front.
- Type new variables and function signatures when the surrounding script is typed.
- Call down, signal up. A child does not reach across the scene tree to poke a sibling.
- Use `await` for signals and timers the engine already provides. Do not busy-loop.
- Keep `_process` and `_physics_process` small. Move one-off work to a signal or a method.

## Testing

Add or update tests when behavior changes.

If the project already uses GdUnit4 or another runner, add a test for the pure logic. Otherwise keep the rule in a plain function and say how you ran the scene.

## Style

- Optimize for the next reader over the shortest diff.
- Comment only when the why is non-obvious.
- Name things the way neighboring files already do.
- Do not reformat code you did not change.

## Errors

- Fail at the boundary. Do not swallow errors.
- Use `push_error` for a broken setup and return early. Do not `assert` on a situation a missing export can cause in the editor.

## Scope

- Do the requested task. Do not refactor unrelated code.
- Match the rigor already in the repo. Fix what you touch.
- Ask one clarifying question only when the task cannot be finished without it. Otherwise state the assumption and continue.

## Avoid

- Do not call `get_node` every frame.
- Do not use Godot 3 yields, `export var`, or string-based `connect` in new Godot 4 scripts.
- Do not store node references across a scene change unless the node is an autoload.
- Do not edit `.tscn` files by hand when the editor can make the change.

## Done when

- The requested behavior works.
- The script has no parser errors, and the scene you changed runs without a red error in the debugger.
- The diff stays inside the task.
- You list anything you could not run.

Add it to the project

  1. 01

    Copy a starting file

    Copy the example Cursor rules on this page, or open the generator if you want different testing, strictness, or comment rules.

  2. 02

    Save it at .cursor/rules/project.mdc

    Save it at `.cursor/rules/project.mdc` in the Godot repo and create the folders if they are missing. If the project still uses one root rules file, save the body as `.cursorrules`.

  3. 03

    Start a fresh agent session

    Rules files are read when a session starts. A chat that is already open may still be using the old instructions.

  4. 04

    Give it one small task

    Ask for one change a Godot agent often gets wrong, such as a node that connects a signal in code instead of checking a flag inside _process. If it ignores the file, confirm the path and start a new session.

Questions about this file

Where do I put Cursor rules in a Godot repo?

Save it at `.cursor/rules/project.mdc` in the Godot repo and create the folders if they are missing. If the project still uses one root rules file, save the body as `.cursorrules`.

Which tools read this Cursor rules?

Cursor reads `.cursor/rules/*.mdc` and, on older setups, a root `.cursorrules` file. Other tools ignore the frontmatter, so use AGENTS.md when more than one agent edits the repo.

What does the Godot example assume?

The example assumes Godot 4 and GDScript. It does not assume C# or a third-party framework. If the repo is a Godot 3 project, do not use Godot 4-only APIs.

Does VibeSpell upload my repository?

No. Recipe pages are static, and the generator builds the file in your browser from the options you pick. Your source code never leaves the machine.

Other files for Godot

Cursor rules for other stacks