Godot 4 rules for AI coding agents
Full stack: Godot 4 (GDScript)
Ready-to-commit rules for Godot 4 (GDScript) in every major format: AGENTS.md (Codex, Cursor, Copilot), CLAUDE.md (Claude Code), Cursor .mdc project rules, legacy .cursorrules, Copilot instructions, Windsurf rules and GEMINI.md. A Godot 4 game in statically typed GDScript.
Last reviewed 2026-10-21 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md
The mistake agents make most on this stack
Agents write Godot 3 syntax (`export var`, `yield`) that does not compile in Godot 4.
Generated files
AGENTS.md
# AGENTS.md - this project
Instructions for AI coding agents working in this repository.
## Project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
## Reference docs
- [Godot docs](https://docs.godotengine.org/en/stable/)
CLAUDE.md
# CLAUDE.md - this project
Project instructions for Claude Code.
## Project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
## Reference docs
- [Godot docs](https://docs.godotengine.org/en/stable/)
.cursor/rules/project.mdc
---
description: "Core rules for this project"
alwaysApply: true
---
# this project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.cursor/rules/godot.mdc
---
description: "Godot 4 (GDScript) conventions: Godot 4 game with statically typed GDScript."
globs: **/*.gd
alwaysApply: false
---
# Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
Docs: https://docs.godotengine.org/en/stable/
.cursorrules
# Cursor rules - this project
You are an expert Godot 4 (GDScript) engineer working on this codebase. Follow these rules.
## Project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
## Reference docs
- [Godot docs](https://docs.godotengine.org/en/stable/)
.github/copilot-instructions.md
# Copilot instructions - this project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.github/instructions/godot.instructions.md
---
applyTo: "**/*.gd"
---
# Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
.windsurf/rules/project.md
---
trigger: always_on
---
# this project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.windsurf/rules/godot.md
---
trigger: glob
globs: **/*.gd
---
# Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
GEMINI.md
# GEMINI.md - this project
Project context for Gemini CLI.
## Project
A Godot 4 (GDScript) project.
Stack: Godot 4 (GDScript).
## Commands
- Run project: `godot --path .`
- Headless import/check: `godot --headless --path . --import`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Godot 4 (GDScript)
- Use Godot 4 GDScript syntax (`@export`, `@onready`, `signal`, `super()`). No Godot 3 syntax such as `export var` or `yield`.
- Use static typing everywhere: `var speed: float = 200.0`, typed function signatures and return types.
- Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in `_physics_process(delta)`; visuals in `_process(delta)`.
- Reference child nodes with `@onready var x: Type = $Path` or `%UniqueName`, not repeated `get_node()` calls.
- Avoid hand-editing `.tscn` / `.tres` files beyond trivial changes; describe Editor steps to the user instead.
## Reference docs
- [Godot docs](https://docs.godotengine.org/en/stable/)
Commands your agent should run
| Task | Command |
|---|---|
| Run project | godot --path . |
| Headless import/check | godot --headless --path . --import |
What the rules cover
Godot 4 (GDScript)
Godot 4 game with statically typed GDScript. Scoped to **/*.gd in Cursor, Copilot and Windsurf.
- Use Godot 4 GDScript syntax (
@export,@onready,signal,super()). No Godot 3 syntax such asexport varoryield. - Use static typing everywhere:
var speed: float = 200.0, typed function signatures and return types. - Prefer composition: small scenes with one responsibility, combined in the scene tree.
- Communicate upward with signals and downward with method calls ("call down, signal up").
- Physics and movement go in
_physics_process(delta); visuals in_process(delta). - Reference child nodes with
@onready var x: Type = $Pathor%UniqueName, not repeatedget_node()calls. - Avoid hand-editing
.tscn/.tresfiles beyond trivial changes; describe Editor steps to the user instead.
Source docs: Godot docs
How to install
- Copy
AGENTS.mdto your repo root. That covers Codex, Cursor, GitHub Copilot and most other agents. - Using Claude Code? Add a
CLAUDE.mdwith the single line@AGENTS.md, or use the standalone CLAUDE.md tab above. - Want rules that only load for certain files in Cursor? Add the
.cursor/rules/*.mdcfiles. - Commit the files so your whole team (and every agent) shares them.
FAQ
Where do I put the AGENTS.md for Godot 4 (GDScript)?
Save it as AGENTS.md in the root of your repository, next to your main config file. Codex, Cursor and GitHub Copilot pick it up automatically. For Claude Code, add a CLAUDE.md containing @AGENTS.md (or use the standalone CLAUDE.md on this page).
What is the most common mistake AI agents make with Godot 4 (GDScript)?
Agents write Godot 3 syntax (export var, yield) that does not compile in Godot 4.
Which commands should the agent run to check its work?
For this stack: godot --path ., godot --headless --path . --import. They are listed in the generated files so the agent runs them before finishing a task.
Do these Godot 4 (GDScript) rules work with Cursor and Claude Code?
Yes. This page includes the same rules as AGENTS.md, CLAUDE.md, Cursor .mdc project rules, a legacy .cursorrules file, GitHub Copilot instructions, Windsurf rules and GEMINI.md.
Can I customise these rules?
Yes. Open this stack in the generator to add or remove libraries, set your project name and package manager, switch beginner explanations on, and download everything as a zip.
Related stacks
Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation
The default vibe-coding SaaS stack: Next.js App Router, Supabase for auth and Postgres, Tailwind and shadcn/ui for the interface.
Next.js (App Router) + Tailwind CSS v4
A plain Next.js + TypeScript + Tailwind v4 starter, the most common front-end setup in 2026.
Next.js (App Router) + Tailwind CSS v4 + Prisma + Stripe payments + Zod validation
A paid SaaS on Next.js with Prisma and Stripe subscriptions.
Next.js (App Router) + Tailwind CSS v4 + Drizzle ORM + Clerk auth + Zod validation
Next.js with Clerk for auth and Drizzle ORM on Postgres: fast to build, type-safe end to end.
Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Vercel AI SDK + Zod validation
Build an AI chat app or agent UI with Next.js and the Vercel AI SDK.
Next.js (App Router) + Tailwind CSS v4 + Supabase + Stripe payments + Zod validation + Vitest
The full indie-hacker SaaS kit: auth, database, payments and tests.