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>.

Use ← → keys, or drag on the screen with your finger

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.

Vibe coding

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.

Agentic engineering

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.

Picture it

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.

Context Engineering

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).

HOW METEOR DODGE’S NOTES ARE ORGANIZED

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.

WITHOUT NOTES VS WITH NOTES

No notesYesterday the screen was 480 wide, today it’s 800. The ship speed changes every time.

With notes“Screen is 480×320” is written down, so you get the same answer every time.

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.

Agentic Validation

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.

LEVEL 1 · TESTS

“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.

LEVEL 2 · READ THE RECORDS

“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

Run the checks to see the results here.

Not “it seems to work,” but “it works, and here’s the proof.”

Agentic Tooling

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.

WHEN THIS CHAT KEEPS HAPPENING, IT’S A SIGNAL

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.

BUILD THE BRIDGE: ONE COMMAND

/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.

Agentic Codebases

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.

BEFORE TIDYING

game/
├── ship_move.js
├── ship_move_old.js     ← which is real?
├── enemies/meteor.js
├── EnemyMissile.js      ← names all different
└── test_final_REAL_v2.js

AFTER TIDYING

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.

Compound Engineering

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.

OUR TEAM’S TOOLBOX

toolbox/
├── commands/   /new-stage  /add-scoreboard
├── checks/     hit-check  wall-check  score-check
├── templates/  GAME_NOTES_template.md
└── rules/      team_golden_rules.md

THE NEXT GAME IS MUCH FASTER

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 game
WHAT 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 GET
```
game.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 RESULT
```
AI: 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

Point to the notes“Read GAME_NOTES.md first” keeps every answer on the same rules.

Use real numbers“260 pixels per second” beats “kind of fast.” Numbers can be tested.

Ask for proof“Run the tests and show me the results” instead of “Does it work?”

Say what not to do“Don’t change the tests” and “ask before guessing” stop shortcuts.

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 /add-enemy command. The AI reads the game notes and rules first.
0 mix-ups
TueIII Tools
A search tool finds every place the meteor code is used, all at once.
1 hour → 10 minutes
WedIV Tidy code
enemies/missile.js is built in exactly the same shape as the meteor.
50% confusion → 0%
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?”

Behind the scenes

The prompts that made this page

This page was made with an AI too. Here are the real requests, in order (the first three were written in Korean):

Make a slide deck from this content, with lots of explanation. → a 42-slide deck on the 5 Pillars
Turn it into one web page that middle school students can understand. Using a simple game as the example would be great. → the Korean version of this page, with Meteor Dodge
Make it in English, and also show which prompts were used to build the app, step by step, with examples. → this page and the prompt walkthrough above

Notice the pattern: each request builds on the last one, and the AI already had the earlier content to work from. That’s Pillar I in action.

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.

I Design notesII Auto-checksIII Make toolsIV Tidy codeV Toolbox

Tag: Making game with ai

Agentic Engineering

Two ways to code with AI

Ask loosely, copy, paste

First, build a place where the AI can work well

Five pillars that hold up a solid game

Design notes: not more, just exactly enough

Auto-checks: when the AI says “Done!”, who checks?

“In this situation, this must happen”

“It didn’t crash” isn’t enough

Testing lab

Make tools: don’t carry it across the river, build a bridge

Tidy code: only one way to do each job

Toolbox: turn what you made into everyone’s building blocks

The prompts that build Meteor Dodge, step by step

The one-line prompt

Write the rules before any code

Build the first version from the notes

Ask for tests, and ask to see them run

Let the AI fix its own mistakes

Turn a repeated chore into a command

Clean up before adding something new

Save the good parts for next time

What makes these prompts good

Adding a missile to Meteor Dodge, Monday to Friday

Which pillar would you fix?

The prompts that made this page

When the AI fails, it’s a chance to prepare one more thing