Game-design notebook · for middle school
Building games with AI,
the right way
Is “make me a game” all you need to say to an AI? Try the Meteor Dodge game on the right and see for yourself. The same AI can build a great game or a broken one. What changes the result is how you set things up.
The game isn’t running here. WordPress removed this page’s game code (this happens on WordPress.com plans without plugins, and for non-admin accounts). Use the iframe method instead: upload the “standalone” file and embed it with an <iframe>.
Before we start
Two ways to code with AI
Grown-up programmers talk about this a lot right now. Asking an AI something quickly and pasting whatever code comes out is called vibe coding, as in “coding on vibes.” It started as an exciting idea, but today people use it to mean “not doing it properly.” The approach that replaced it is called agentic engineering. Let’s build the same game both ways.
Ask loosely, copy, paste
- 1Tell the AI: “Make me a meteor dodging game.”
- 2Copy the code and paste it in. Hey, it runs!
- 3Next day: “Add a score.” But the AI doesn’t remember yesterday’s chat. It writes the code in a totally different way.
- 4The two styles get mixed up and bugs appear. Meteors hit you and the game doesn’t end.
- 5Nobody understood the code when they pasted it, so nobody knows why it broke.
Result: a toy that sort of works. Hard to fix, hard to grow.
First, build a place where the AI can work well
- 1Write the game design notes first: screen size, ship speed, game rules.
- 2The AI reads these notes before every job. It never forgets the rules you agreed on.
- 3When the AI says “Done!”, automatic tests check whether that’s true.
- 4If a test fails, the AI reads the result and fixes it by itself.
- 5Useful commands and tools go into a shared toolbox for the next game.
Result: a real game you can trust and keep improving.
Vibe coding is cooking alone with no recipe, making it up as you go. Agentic engineering is a head chef who prepares recipe notes, a way to taste-test, and good tools, so that several assistant cooks (the AIs) can work well in that kitchen. Vibe coding lets anyone build something. Agentic engineering lets you go much further, and build things that last.
The big idea
Five pillars that hold up a solid game
Agentic engineering is made of five habits. We’ll look at each one using Meteor Dodge. The small labels show the names professionals use.
Design notes: not more, just exactly enough
An AI forgets everything when the chat ends. So important decisions must be written down in notes that it reads every time. But “then I’ll just give it everything!” is the wrong idea. If you ask a friend the way to school and they hand you a map of the whole city, you get more confused, not less. An AI works the same way: the more unrelated stuff you give it, the more random its answers get. So give it information that is fresh (up to date) and condensed (short).
GAME_NOTES.md ← the AI reads this first ├── rules.md touch = game over, 10 pts/sec ├── screen.md 480×320, ← → keys └── decisions/ ├── 001-screen-size.md └── 002-scoring.md
The first note works like a table of contents that points to the others. The AI only opens the notes it needs.
Always write down why you decided something too. Code only shows how; it never explains why.
A rule that lives only in your head doesn’t exist for the AI.
Auto-checks: when the AI says “Done!”, who checks?
If you ask an AI “Did you do a good job?”, it almost always says “Yes!” That’s like grading your own homework, so it’s hard to trust. The grading has to come from outside the AI: the computer runs set situations and checks the results. These are called automatic tests, and there are two levels.
“In this situation, this must happen”
Put a meteor right on the ship → check the game ends. Keep pushing the ship into the left wall → check it stays on screen.
“It didn’t crash” isn’t enough
The game can run perfectly and still hide a weird score that climbs 60 points per second. Look inside, not just at the outside.
Testing lab
This is connected to the game at the top. Run the checks, and if they fail, show the results to the AI and let it fix the code.
- waitLEVEL 1 TEST
When a meteor touches the ship, the game ends - waitLEVEL 1 TEST
The ship cannot leave the screen - waitLEVEL 2 RECORD CHECK
The score goes up about 10 points in 1 second
Not “it seems to work,” but “it works, and here’s the proof.”
Make tools: don’t carry it across the river, build a bridge
Sometimes the AI gets stuck, can’t do something on its own, and asks a person for help. That’s called friction. If you say “I’ll just do it for you,” today’s problem is solved, but next week it gets stuck in the exact same place. Instead, build a tool the AI can use by itself. Rather than carrying it across the river every time, you build a bridge once.
AIPlease put the meteor images for the new stage into the folder yourself.
You(Again? I did this last week…)
AIPlease also create the stage settings file by hand.
/new-stage 3 → create the stage folder → copy the meteor images → fill in the settings file → run the tests
Now the AI uses this command and finishes the whole job alone. Typed commands (a CLI, command-line interface) are the easiest kind of bridge for an AI.
People choose the direction. Tools do the repeating work.
Tidy code: only one way to do each job
Imagine your game folder has both ship_move.js and ship_move_old.js. The AI can’t tell which one is real, so it has a 50% chance of picking the wrong one. When lots of choices like that pile up, the results become a mess, and we say “Why is the AI so random?” It’s not really the AI’s fault. It’s the messy folder’s fault.
game/ ├── ship_move.js ├── ship_move_old.js ← which is real? ├── enemies/meteor.js ├── EnemyMissile.js ← names all different └── test_final_REAL_v2.js
game/
├── ship/move.js
└── enemies/
├── meteor.js all written the same way
├── missile.js
└── bird.js
Every enemy is written in exactly the same shape. Then the AI can look at the meteor code and build a missile the same way. Even if some code repeats, being consistent matters more.
Today, code gets read and run by AIs more often than it gets read by people.
Toolbox: turn what you made into everyone’s building blocks
A trick only you know can only help you. But if you put your best notes, checks, and tools into a shared team toolbox, everyone can use them. And as the blocks pile up, the number of combinations grows much faster. With 10 blocks you can make 45 different pairs; with 30 blocks you can make 435. That’s the power of things adding up like interest in a bank.
toolbox/
├── commands/ /new-stage /add-scoreboard
├── checks/ hit-check wall-check score-check
├── templates/ GAME_NOTES_template.md
└── rules/ team_golden_rules.md
Want to build Brick Breaker next? Pull out the hit-check, score-check, the notes template, and the scoreboard command as they are. The only new part you really need to write is the bouncing ball.
But the blocks only fit if the folder is tidy. Tidy code (IV) × toolbox (V) is a multiplication: if one is zero, the result is zero.
It’s not about one person being good. It’s about everyone getting faster together.
Try it yourself
The prompts that build Meteor Dodge, step by step
A prompt is the message you type to the AI. Here is the full set of prompts you could use with an AI coding assistant to build the game at the top of this page. Step 0 is the vibe-coding way, for comparison. Steps 1–7 are the agentic way. Each step shows what you type, what the AI does, and an example of what you might get back.
-
0
Vibe coding · don’t do this
The one-line prompt
YOU TYPEmake me a meteor dodging gameWHAT THE AI DOES- Guesses the screen size, speed and scoring
- Writes everything in one big file
- Says “Here’s your game!” without checking anything
WHAT YOU GETgame.html (1 file, 300 lines) ✗ meteors pass through the ship ✗ ship flies off the screen ✗ score: 60 points per second
-
1
Pillar I · Design notes
Write the rules before any code
YOU TYPEBefore writing any code, create GAME_NOTES.md for a meteor dodging game. Rules: – Canvas is 480×320 pixels. – The ship moves left/right at 260 pixels per second and must stay on screen. – Meteors fall from the top and get a little faster over time. – If a meteor touches the ship, the game is over. – Score goes up 10 points per second. Add a “Why we decided this” section for each rule.WHAT THE AI DOES- Creates the notes file, no game code yet
- Writes each rule with exact numbers
- Adds a reason under every rule
EXAMPLE RESULT+ GAME_NOTES.md ## Scoring +10 points per second survived. Why: time-based, so the score is the same on fast and slow computers.
-
2
Pillar I · Design notes
Build the first version from the notes
YOU TYPERead GAME_NOTES.md and build the game in game.js. Follow every rule exactly. Put the ship, the meteors and the scoring in separate functions. If anything in the notes is unclear, ask me before guessing.WHAT THE AI DOES- Reads the notes first
- Writes small, clearly named functions
- Asks questions instead of guessing
EXAMPLE RESULT+ game.js moveShip() // rule: stay on screen dropMeteors() checkHit() // rule: touch = game over addScore() // rule: 10 pts/sec AI: Should the ship wrap around or stop at the edge? The notes say "stay on screen," so I made it stop.
-
3
Pillar II · Auto-checks
Ask for tests, and ask to see them run
YOU TYPEWrite automatic tests for the rules in GAME_NOTES.md: 1. A meteor touching the ship ends the game. 2. Holding left for 1 second keeps the ship on screen. 3. After exactly 1 second, the score is about 10. Run the tests and show me the real results. Don’t just tell me they pass.WHAT THE AI DOES- Turns each rule into a test
- Actually runs the tests
- Reports passes and failures honestly
EXAMPLE RESULT$ npm test PASS wall: ship stays on screen FAIL hit: game did not end FAIL score: got 60, expected ~10 2 failed, 1 passed
-
4
Pillar II · Auto-checks
Let the AI fix its own mistakes
YOU TYPETwo tests failed. Read the failure messages, find the cause, fix game.js, and run the tests again. Repeat until all tests pass. Do not change the tests to make them pass.WHAT THE AI DOES- Reads each failure message
- Fixes the code, not the test
- Loops: fix → test → fix → test
EXAMPLE RESULTAI: checkHit() only matched the exact centre. Using the ship's full size now. AI: addScore() added 1 per frame. Changed to 10 × seconds passed. $ npm test 3 passed, 0 failed
-
5
Pillar III · Make tools
Turn a repeated chore into a command
YOU TYPEEvery new stage needs the same setup, and you keep asking me to do it by hand. Make a command called /new-stage that takes a stage number, creates the stage folder, copies the meteor images, fills in settings.json, and then runs the tests. Use it to create stage 2.WHAT THE AI DOES- Writes a small script for the chore
- Saves it as a reusable command
- Uses it right away to prove it works
EXAMPLE RESULT$ /new-stage 2 + stages/2/settings.json + stages/2/meteor.png running tests… 3 passed
-
6
Pillar IV · Tidy code
Clean up before adding something new
YOU TYPEBefore we add a missile enemy: find any files that do the same job (like ship_move.js and ship_move_old.js), keep the one we use and delete the other. Then make missile.js follow exactly the same shape as meteor.js. Add a “One way to do each job” rule to GAME_NOTES.md.WHAT THE AI DOES- Finds and removes duplicate files
- Copies the meteor pattern for the missile
- Writes the new rule into the notes
EXAMPLE RESULT- ship_move_old.js + enemies/missile.js (same shape as meteor.js) ~ GAME_NOTES.md (+1 rule) $ npm test 4 passed
-
7
Pillar V · Toolbox
Save the good parts for next time
YOU TYPEOur next game will be Brick Breaker. Move the parts that would help any game (the hit and score tests, /new-stage, and a blank GAME_NOTES template) into a toolbox/ folder, and write a short README for each one explaining when to use it.WHAT THE AI DOES- Makes the parts general, not Meteor-only
- Puts them in one shared place
- Writes a how-to for each part
EXAMPLE RESULT+ toolbox/checks/hit-check.js + toolbox/checks/score-check.js + toolbox/commands/new-stage + toolbox/templates/GAME_NOTES.md Brick Breaker setup: 3 days → 1 day
What makes these prompts good
All five pillars working together
Adding a missile to Meteor Dodge, Monday to Friday
The five pillars aren’t a cake you build one layer at a time. They’re woven together like a net, and whichever pillar is needed jumps in. That’s why the order below goes I, III, IV, II, V.
- MonI Design notes
Start with the
0 mix-ups/add-enemycommand. The AI reads the game notes and rules first. - TueIII Tools
A search tool finds every place the meteor code is used, all at once.
1 hour → 10 minutes - WedIV Tidy code
50% confusion → 0%enemies/missile.jsis built in exactly the same shape as the meteor. - ThuII Auto-checks
Hit and wall tests, plus the score record check. If anything fails, the AI fixes it.
0 times a human stepped in - FriV Toolbox
The new command and checks are made general and saved in the toolbox.
Next enemy: 3 days → 1 day
Quiz · 0 / 5
Which pillar would you fix?
When the AI fails, it’s tempting to just fix the code yourself. Then the same failure happens again next week. Instead, ask: “Which of the five pillars needs more preparation?”
Today in one line
When the AI fails, it’s a chance to prepare one more thing
A great developer isn’t someone who types code instead of the AI. It’s someone who designs a place where the AI can do great work. One more line of notes, one more check, one more tool, and your game grows faster and stronger every time.
