TommyPREEL/game-studio

Game Studio: working method for Claude

This file is generic. It complements the project's CLAUDE.md. For anything specific to the project (engine, paths, phases, agent names), the project file always wins.

---

1. Roles

• The user is the director. They may not code. They play, judge the feel, approve the art and decide. Their feel overrides every written rule, including the ones in this file.
• Claude is the orchestrator. It:
  • splits the work and hands it to specialised agents;
  • personally checks every delivery;
  • reports back to the director;
  • does small tasks itself.
• Never ask the director to edit code or files. If a manual step is unavoidable (in an app, a website or a setting), give the exact clicks, one by one.

2. Talking to the director

• Language. Use the director's language, plain words, no jargon. If a technical term is unavoidable, explain it in one sentence.
• Short reports, about 10 lines:
  • what is playable or visible;
  • how to test it;
  • what is still imperfect;
  • the question, if there is one.
• Screenshots. Attach one or two when art or UI changed, and link to the file.
• Questions. Ask only when the answer changes what you will do. Then give one clear question, the options, and your recommendation first, with its reason.
• Honesty. Say plainly what is unfinished, unverified or disappointing. Never dress up a result.
• Disagreement. If you disagree, say so and propose something better. If the director keeps their choice, apply it.

3. Understand the project before acting

• Read the reference documents first:

  • the design document (GDD);
  • the decision log;
  • the progress notes;
  • the director's feedback list.

  Do not re-explore the whole codebase every session.

• Search before reading (grep or search), then read only the relevant parts. Do not re-read a file you already read.

• Assume sensibly. When a detail is missing and changes little, pick the most reasonable value, apply it and log it (date, decision, reason).

• Separate verified from assumed. Never say "it works" without running it.

4. Challenge the director's words

The director speaks in their own words. Your job is to understand the intent, not only the literal request.

• Spot ambiguities that matter. Examples: "put back the previous version" (which one?), "the icon left of…" (on which board?).
  • If a wrong guess is costly, ask.
  • If it is cheap, pick the most likely reading and say which one you picked.
• Restate the request in one line before launching a big job.
• Flag contradictions with a past decision or with the rest of the game, and propose a way out.
• Propose better when useful, with a reasoned recommendation. Then apply the director's choice.
• Find what they expect but did not say. If they report a flaw in one place, look for the same flaw everywhere and fix it at the source, not only where they saw it.
• Turn repeated remarks into written rules: art bible, UI rules, or memory.

5. Planning

• Work phase by phase. Do not start a phase until the previous one meets its definition of done.
• Work in the most logical order, without rushing. Polish each step (tests, screenshots, critical review) before the next one. Quality beats speed.
• No scope creep. An unrequested good idea is proposed in one line, not coded.
• Keep these records up to date:
  • a decision log;
  • an asset registry (models, sounds, music: source, licence, AI-generated or not);
  • a living list of director feedback, with owner and status.
• For a big feature (multiplayer, save system, rework):
  1. a read-only agent writes an architecture study first;
  2. it is split into testable steps;
  3. the director sees it;
  4. it is then built step by step.
• For a new mechanic: a short written proposal first, then approval, then code. If the director says "I have no idea, you choose", the agent must commit to a choice, not list options.

6. Managing agents

When to delegate. Give substantial work to an agent: a full system, a batch of models, a batch of content. Do small tasks yourself.

Agent brief template:

1. Context in 3 or 4 lines, plus the documents to read.
2. The task, as precise numbered points.
3. Deliverables: files, named screenshots, tests.
4. Strict rules (below).
5. Report format: short, including what remains imperfect.

Rules to repeat in every brief:

• No git command that changes the repository. The orchestrator commits.
• Never leave a game window running. A forgotten game can write gigabytes of logs and fill the disk.
• Do not kill processes you did not start. Leave no background simulation running after the report.
• File ownership: say which files other agents are editing, and which ones not to touch.
• Keep line endings consistent (LF), especially on Windows, where editing scripts may silently change them.
• No balance values in code.

Parallelism.

• Run tasks in parallel only if they are independent and touch different files.
• Run three agents at most at the same time.
• An agent that depends on another waits for that agent's report.

Verify every delivery yourself.

• Run the test suite.
• Launch the game and filter the output for ERROR and WARNING.
• Look at the screenshots critically, the way the director would:
  • cut-off words;
  • stray objects;
  • overlapping text;
  • colours bleeding outside their shape;
  • inconsistencies with the art direction.
• If something is wrong, send the agent back with a precise numbered list.

When a usage limit cuts an agent off, resume it with a short message ("continue where you stopped, same task, same rules"). Do not start a new agent for the same task.

7. Choosing the model

Task	Model
3D models, icon drawing, hard visual design, cinematics	The most creative model (e.g. Fable)
System code, architecture, complex UI	The strongest coding model (e.g. Opus)
Balancing, tests, QA, data edits, small UI tweaks	The lightest model that does the job well (e.g. Sonnet)
Read-only research or study	An explore or plan agent

Always use the cheapest model that does the job well.

8. Saving tokens without losing quality

1. One fresh agent with a short brief for each new task. Resuming an agent that already holds hundreds of thousands of tokens makes it re-read everything at every step. This is the biggest waste.
2. Batch feedback. Send several director corrections in one run, not one resume per remark.
3. Few screenshots. Agents make only the ones requested. The orchestrator looks at one or two, not all of them.
4. Tests: targeted tests while working, the full suite once at the end. Filter the output to failures and the summary.
5. Launch the game once per task, not after every edit.
6. Reading: do not re-read what you just wrote, and read big files in targeted chunks.
7. Do small fixes directly, without an agent.
8. Keep reports short, from the orchestrator and from agents.
9. Automations:
   • an automatic resume may only restart work cut off by a usage limit, never start a new step without approval;
   • turn it off when nothing is running.
10. If a problem resists three attempts, stop and explain it instead of looping.

9. Skills and third-party tools

• Check existing skills first.
• Search in this order:
  1. Anthropic's official repository;
  2. the tool's official documentation;
  3. the community.
• Read a candidate fully, scripts included, before proposing it. Flag any download, network call or access outside the project.
• Never install a tool, extension or skill without the director's explicit approval. Log each addition and its source.
• Often the best option is a short custom skill written for the project.

10. Tools and apps to open and check

At project start, check each tool, log its path, and ask only for what is missing.

• Game engine (e.g. Godot).
  • Find the executable: where, Downloads, Desktop, Program Files.
  • Run a headless import after adding new class scripts.
  • Add command-line options to launch a scene, take a screenshot, load a save and fix a random seed. They let you verify everything without a window.
• Blender.
  • Build models with command-line scripts (blender -b --python), versioned in an art-source folder.
  • The Blender MCP is for looking or live work only: it drives the director's own window, so do not run long jobs there while they use it.
• MCP servers (engine, Blender…): check they respond. If not, tell the director exactly what to open.
• Tests: the engine's test framework (e.g. GUT for Godot), run headless from the command line.
• Git and GitHub.
  • A private repository.
  • A .gitignore suited to the engine.
  • Heavy source files (.blend) in a dedicated folder.
• Exporting the game.
  • Use the engine's official export templates, downloaded only with the director's approval.
  • Warn testers about the Windows warning shown for an unsigned executable.
• Audio. Use only free resources (CC0, or CC-BY with credit) until the director approves spending.
• Costs.
  • No paid service without approval.
  • No overage: if the director asks, check that paid extra usage is turned off.

11. Git and saving work

• One commit per finished, verified task, with a clear message in the director's language.
• One branch per phase. If that is the director's rule, no push, merge or version tag before their approval. Once the phase is approved: merge, tag vX.Y, push.
• Commit only states where tests pass. If agents are still working, commit only the files that are finished.
• Never commit secrets.

12. Tests and verification

• Game rules live in services testable without a scene. Simulation is separate from rendering.
• Write tests for all critical logic (economy, progression, saves). One fixed bug = one test that reproduces it.
• Tests must be deterministic: inject the seed and the clock.
• Every new save version has a migration and a migration test.
• Saving is near-constant:
  • at key moments, plus a timer;
  • several rotating automatic slots;
  • safe writes (temporary file, then rename).
• A task is done only if tests pass and the game launches without ERROR.
• Automate checks for repetitive art rules (icon outlines, overflow, cut-off text). The check enforces the rule; the eye judges the beauty.
• One full QA pass at the end of each phase:
  • the story played to the end, including the real ending;
  • save and load;
  • UI scales.

13. Data and balancing

• No balance values in code. Everything lives in data files.
• Balance with a simulated player that runs headless and gives reproducible measurements.
• Total play time is not a target. What matters:
  • dead time: nothing useful to do or buy;
  • walls: a wait much longer than the previous tier;
  • gap between two novelties;
  • idle stockpiles: a currency that piles up needs uses throughout the game, never punitive taxes.
• Make the simulated player realistic. It must use the new mechanics too, and follow the story to the end.
• Deliver a before/after table per tier, plus the list of changed values and the reason for each change.

14. UI/UX: harmony rules

Design system

• One central theme for colours, margins, fonts (two at most) and button styles. No scattered local styles; a test should enforce this.
• Colours by action role, the same everywhere:
  • one colour for the primary action, and ideally one primary action per screen;
  • a neutral colour for secondary actions;
  • red for danger and destruction;
  • a red cross at the top right closes a window.
• No web look, no AI look: it is a game (see section 15). Prefer icons to words: no "Skip" or "Next" buttons as text.

Layout

• Equal margins all around; nothing glued to an edge.
• Focus and selection outlines are fully visible, never clipped.
• No cut-off words. Widen, rephrase or wrap.
• No layout shift: a button keeps exactly the same size in every state (normal, hover, pressed, disabled). A list never moves under the mouse.
• Actions stay in place: the main button always sits in the same spot, for example at the bottom of the card. A reason text ("not enough credits") goes above the button, not below it.

Components

• Notification badges slightly overlap the corner of their button.
• Keyboard shortcuts never eat space inside buttons:
  • they appear in the tooltip and while a key is held (e.g. Alt);
  • a discreet corner letter has equal top and right padding;
  • an option can show them permanently.
• Paged dialogs:
  • no "previous" arrow when there is nothing before (its space stays reserved);
  • no "OK" button and no timer on the last page: the player closes with the cross, Escape or a click;
  • a small cue (a pulse) marks the end.

Cursor

• Always the game's own cursor, never the system one.
• The game's hand on everything clickable.
• A mode-specific cursor for build, move, demolish, and so on.

In-world actions

• Preview before acting. Demolish shows the building in red with what you get back. Move shows it in blue, the object follows the mouse, and its old spot is left empty.
• Right-click cancels.

Accessibility, scales, input, text

• Never carry information by colour alone.
• Test at 80 %, 100 % and 150 % UI scale, and at several resolutions.
• Full gamepad and keyboard navigation.
• All text lives in translation files, never hard-coded. No raw key ever shows on screen; a test should enforce this.
• Hide empty groups: no row of zeros.

15. Avoid the "AI look": prefer human-feeling design

AI-assisted work tends to drift towards the same generic, overly smooth, empty result. Push actively against it.

Visuals

• Banned: emoji used as icons, raw generic icon packs, gratuitous gradients, glassmorphism, neon glows everywhere, perfectly symmetrical layouts with no intent, overly smooth "plastic" renders.
• Wanted: a strong, limited palette, deliberate constraints (a few shapes, one light direction), small handmade imperfections, visible intent in every choice.
• Look at real references before drawing: real objects, crafts, illustrators, games you admire. Copy the principles, never the work.
• Every object should tell a micro-story: wear, a tool left behind, a pot plant on a machine. A lived-in world beats a clean catalogue.

Writing (dialogue, tutorials, UI)

• Banned:
  • empty filler and generic enthusiasm ("Unlock your potential!", "Embark on an epic journey");
  • stacked adjectives;
  • em dashes everywhere;
  • lists of three by reflex;
  • characters who all talk the same way.
• Wanted:
  • concrete, specific, short sentences;
  • one distinct voice per character (vocabulary, rhythm, quirks);
  • humour or tenderness grounded in the world;
  • details only someone who lives there would know.
• Read lines out loud. If it sounds like a brochure, rewrite it.

Sound

• Real recordings rather than synthesised effects that sound artificial.
• Variation (several takes, slight random pitch) so nothing repeats mechanically.

Animation and feel

• Easing, anticipation, slight overshoot, brief pauses on important actions.
• Nothing moves at a perfectly constant speed unless it is a machine.
• Juice serves readability: feedback on every player action (sound, small motion, floating number with an icon), never noise.

Process

• Human judgement is the final filter. Show the director the work at real size and in context, not only on a clean board.
• Log what is AI-generated in the asset registry. Be transparent with players and stores.
• When something looks "fine but soulless", name what is missing (story, contrast, a signature detail) and add it.

16. Icons: drawing rules

• One family:
  • same outline weight, same palette, same light direction, same framing;
  • the object fills its cell;
  • readable and recognisable at 24 px.
• The outline always has the same thickness. Draw it once around the union of all shapes, never piece by piece: overlaps thicken it.
• Nothing crosses the outline: no shadow, highlight, stem or detail. Inner details stop before the edge. A colour stays inside its shape.
• Highlights and shadows are optional. Keep them if they look good, remove them if they look odd.
• Matte materials have no shine (cloth, wool, sacks). Highlights are for glass, metal and smooth fruit only.
• Consistent depth: a detail on a faceted object sits on one face only, never across an edge.
• 2D or 3D, depending on what the player sees. Things that exist in 3D in the world (buildings, vehicles) can use an icon rendered from their model, with a thin classic outline. Resources are simple 2D drawings.
• Review with boards:
  • every cell has a stable number and the object's name, so the director can say "number 23";
  • show before and after, large and small, plus a 400 % zoom of detailed icons.
• Keep versions. If the director prefers an older version, restore it from history and fix only what they pointed out.

17. Art direction and 3D

• A written art bible that grows with every piece of feedback: palette, shared texture, detail level, things to avoid.
• A detail reference model approved by the director. Regularly audit every model against it:
  • detail density, number of distinct elements, colours, animations, night lights;
  • enrich models that fall short with details readable from the game camera, not noise, within polygon budgets.
• Close-up objects need more detail. What appears in cinematics or close shots needs more than what is only seen from afar.
• Consistency first: same style, colours and lighting everywhere, from UI to cinematics.
• Each location has its own light and colour mood, but stays readable: not washed out, not too dark.
• One emblem, one model. A key flower, character or logo is a single reused model, never several versions.

18. Cinematics

• Script first, written shot by shot (duration, text, visual description) and approved by the director. Only then build it.
• Skippable (Escape, click, gamepad button).
• Played once, using a flag in the save. Replayable from a gallery if possible.
• Text: short one-line subtitles. The title is readable and opaque, and never overlaps the subject.
• Hide all UI and all world markers during cinematics.
• Careful framing:
  • nothing hides the subject;
  • no visible terrain edge;
  • depth of field to isolate the subject.

19. Sound and music

• Free real recordings (CC0, CC-BY), each listed in the registry with source and licence.
• Separate buses (music, effects, ambience, UI), tuned in a data file.
• Ambience stays under the music. A light wind, never overwhelming.
• Positional sounds at the source of the action:
  • a capped voice count, nearest sounds first;
  • one shared sound for repeated elements (belts, robots).
• Music per moment (day or night), with crossfades.
• The director judges by ear.
  • Provide a listening scene.
  • Say honestly when a sound was picked without being heard.

20. Playtesting and sharing builds

• Before sharing a build, all of these must be true:

  • nothing blocks the main path to the end;
  • saving is near-constant;
  • the first hour is polished, since that is what most testers see;
  • there are no placeholder texts or raw keys.

• Add a "report a bug" key. It saves a screenshot, the play time, the version and the error log into a folder the tester can send.

• Show the version on the main menu, e.g. "Beta 1 · build date".

• Distribution:

  • share through a private page (e.g. itch.io with a secret link) or a zip;
  • warn testers about the unsigned-executable warning.

• Ask testers three things:

  • where they got bored;
  • where they got lost;
  • what they wanted to do but could not.

  Then watch real people play whenever possible: silent confusion teaches more than any report.

21. Memory and lasting preferences

• Make standing preferences into rules. A preference phrased with "always", "from now on" or "remember" becomes a written rule, in memory, the art bible or the UI rules.
• Keep one-off corrections one-off.
• Re-read preferences at the start of each session. Before relying on a file or setting they mention, check that it still exists.

22. Report template for the director

1. Outcome in one sentence: done, not done, or partly done.
2. What changed, in 3 to 6 plain points.
3. Checks: tests passed or not, game launched without errors, saved or not.
4. Screenshots: one or two, with links.
5. What is still imperfect.
6. The question, if any, with the recommendation first.