0 Set up your tools Cài đặt công cụ

One-time setup. You need a place to store code, a way to read it, and an AI coding agent.

Setup một lần, dùng mãi. Bạn cần: nơi lưu code, cách đọc code đó, và một AI coding agent.

• Create a GitHub accountTạo tài khoản GitHub and a new public repository. và một repository public mới. This stores every step so you can compare, roll back, and host the game for free later. Lưu từng bước đi, cho phép bạn so sánh, rollback, và host game miễn phí sau này.
• Install GitHub DesktopCài GitHub Desktop and clone the repo to your machine. và clone repo về máy. A friendly UI for commits — you won't need the command line. Giao diện thân thiện cho việc commit — không cần đụng command line.
• Install Visual Studio CodeCài Visual Studio Code with a Markdown preview extension. kèm extension preview Markdown. To read the code the AI writes and make tiny tweaks yourself — faster than asking the AI. Để đọc code AI viết và tự chỉnh sửa những thứ nhỏ — nhanh hơn nhiều so với nhờ AI làm.
• Pick and install ONE AI coding agentChọn và cài MỘT AI coding agent (desktop app). See the comparison below. (desktop app). Xem bảng so sánh bên dưới. The workflow is nearly identical across all three. Workflow gần như giống hệt nhau với cả ba lựa chọn.
• Pick ONE chat AIChọn MỘT chat AI for design discussion (can be the same provider). để thảo luận thiết kế (có thể cùng provider). Used for brainstorming and writing the design docs before any code. Dùng cho việc brainstorm và viết design docs trước khi code bất cứ thứ gì.

Roughly $20/month (~500K VND) for the Plus/Pro tier of any one of them; a team can share a single account for a month. Quick take for mid-2026: Gemini gives the best value for most people. Pick Claude if your use case is purely code/writing/agent work that demands the highest accuracy. ChatGPT is worth grabbing especially when there's a free Plus month. For this prototype workflow, the choice barely matters — the steps below are nearly identical across all three.

Khoảng $20/tháng (~500K VND) cho gói Plus/Pro của bất kỳ công cụ nào; một nhóm có thể dùng chung một tài khoản cả tháng. Nhận xét nhanh giữa 2026: Gemini có giá trị tốt nhất cho hầu hết mọi người. Chọn Claude nếu use case của bạn thiên về code/writing/agent và đòi hỏi độ chính xác cao nhất. ChatGPT đáng thử — đặc biệt khi có tháng Plus miễn phí. Với workflow prototype này, lựa chọn gần như không quan trọng — các bước bên dưới gần như giống nhau với cả ba.

1 Find the idea Tìm ý tưởng

Use the chat AI as a thinking partner. Make it ask you questions — the best idea still comes from you. Pick whichever prompt matches your situation: an open brainstorm, or one anchored to a specific theme.

Dùng chat AI như một đối tác tư duy. Bắt nó hỏi-ngược lại bạn — ý tưởng hay nhất vẫn phải xuất phát từ bạn. Chọn prompt phù hợp với tình huống: brainstorm mở hoàn toàn, hoặc gắn với một theme cụ thể.

• Use a creative (mid-tier) modelDùng model sáng tạo (mid-tier) , in English if you can., bằng tiếng Anh nếu có thể. Saves tokens and improves quality. Tiết kiệm token và cải thiện chất lượng đầu ra.
• State who the players areXác định rõ người chơi là ai — both prompts ask for it, because a game for kids and a game for puzzle fans lead to very different ideas. — cả hai prompt đều hỏi điều này, vì game cho trẻ em và game cho puzzle fan sẽ ra ý tưởng rất khác nhau.
• Make the AI ask you clarifying questionsBắt AI hỏi-ngược bạn những câu làm rõ before it proposes anything. trước khi nó đề xuất bất cứ thứ gì.
• Demand a comparison tableYêu cầu một bảng so sánh of 10+ ideas scored on clear criteria, so you can choose objectively. 10+ ý tưởng được chấm điểm theo tiêu chí rõ ràng, để bạn chọn lựa một cách khách quan.
• Pick a few ideas you like. Or ask for more. Discuss back and forth with AI until you have a clear favorite. Chọn vài ý tưởng bạn thích. Hoặc yêu cầu thêm. Thảo luận qua lại với AI đến khi bạn có một lựa chọn rõ ràng.

Version A — open brainstorm (no fixed theme)

Phiên bản A — brainstorm mở (không có theme cố định)

I want to prototype a game. Help me find ONE creative, fun game idea worth building.

The game is for this audience (the people who'll play it): [DESCRIBE PLAYERS — e.g. "casual mobile players", "kids 8–12", "puzzle fans"].

Let's brainstorm together — ask me clarifying questions first if anything is vague, don't jump straight to answers.

Constraints for the idea:
- Must play well on BOTH desktop and mobile (fun with touch / tap / swipe)
- ONE interesting, reasonably innovative core mechanic — not a clone
- Small enough to prototype in a few hours (a vertical slice, not a full game)

My hobbies / interests to draw from (optional): [FILL IN — e.g. Poker, Pool, Piano, Origami — or delete this line]

When I say "ready", present at least 10 ideas in a TABLE, in an artifact, comparing them on:
Innovativeness | Mobile-first fit | Core mechanic clarity | Prototype feasibility (hours) | Appeal to my players.
Then recommend your top 3 with one line on why each is a strong, fun prototype for this audience.

Version B — themed brainstorm (AI researches the theme first)

Phiên bản B — brainstorm theo theme (AI nghiên cứu theme trước)

I want to prototype a game built around a specific theme. Help me find ONE creative, fun idea worth building.

The game is for this audience (the people who'll play it): [DESCRIBE PLAYERS — e.g. "casual mobile players", "fans of the theme", "kids 8–12"].

Theme: [STATE YOUR THEME — e.g. "Dragon Mania Legends", "Vietnamese folk tales", "outer space"].

First, RESEARCH the theme so the ideas feel authentic:
- Look up the theme's signature elements, characters, mechanics, tone, and visual identity.
- Summarize back to me, in a short list, the 5–8 most distinctive things about it that a game could build on.

Then brainstorm with me. Ask clarifying questions if needed. Each idea must:
- Stay true to the theme's identity
- Play well on BOTH desktop and mobile (fun with touch / tap / swipe)
- Have ONE interesting, reasonably innovative core mechanic — not a clone
- Be small enough to prototype in a few hours (a vertical slice)

When I say "ready", present at least 10 theme-based ideas in a TABLE, in an artifact, comparing them on:
Innovativeness | Mobile-first fit | Core mechanic clarity | Prototype feasibility (hours) | Theme authenticity | Appeal to my players.
Then recommend your top 3 with one line each on why they're a strong, fun prototype that fits the theme and this audience.

2 Lock the design — write the GDD Chốt thiết kế — viết GDD

Discuss the idea in chat until the core loop feels fun on paper, then write a lean Prototype GDD. This is the biggest scope-saver — nail the mechanic in plain words before any code exists.

Thảo luận ý tưởng trong chat đến khi core loop cảm giác fun trên giấy, rồi viết Prototype GDD gọn nhẹ. Đây là bước tiết kiệm scope nhiều nhất — nail mechanic bằng ngôn ngữ thông thường trước khi code tồn tại.

• The core mechanic is one sentenceCore mechanic là một câu you can say out loud. Keep refining until you can. bạn có thể nói to được. Tiếp tục tinh chỉnh cho đến khi làm được.
• Ask the AI for a labelled wireframeBảo AI phác một wireframe có chú thích of the main screen — shows layout problems before any code exists. của màn hình chính — sẽ lộ ra vấn đề layout trước khi code tồn tại.
• Define the vertical sliceXác định vertical slice — the smallest thing that proves the mechanic is fun. — thứ nhỏ nhất chứng minh được mechanic có fun hay không.
• Write the non-goals.Viết ra non-goals. What you won't build matters as much as what you will. Những thứ bạn sẽ KHÔNG xây dựng quan trọng không kém những thứ bạn sẽ xây dựng.
• GDD is design only, under ~2 pagesGDD chỉ là design, dưới ~2 trang — no file names, code, formulas, or configs (that's the TDD's job). — không có tên file, code, công thức, hay config (đó là việc của TDD).
• Every rule is implementable by a strangerMọi rule phải đủ rõ ràng để người lạ implement được — no "you know what I mean". — không có kiểu "bạn hiểu ý mình muốn nói chứ".
• Review the GDD in VS CodeXem lại GDD trong VS Code and fix small things yourself before moving on. và tự sửa những thứ nhỏ trước khi chuyển sang bước tiếp theo.

Let's lock the design for [GAME NAME / chosen idea]. Write a PROTOTYPE GDD as a Markdown file: gdd.md

Rules:
- This is a PROTOTYPE design doc, not a commercial GDD. Keep it lean — aim for under ~2 pages.
- Pure design only. NO technical content (no file names, no code, no formulas, no configs) — that goes in the TDD.
- Structure: Pitch · Design Pillars (2–4) · Core Mechanic · Core Loop · Rules · Controls (mobile + desktop) · UI layout/elements · UX flow · Win/Lose · In-Scope (vertical slice) · Non-Goals.
- Every rule must be unambiguous enough that a coder who never spoke to me could implement it.
- Where a number matters (turn limit, hand size, timing window), state it — but keep it in plain language, not code.

Also produce a VISUAL MOCKUP of the main gameplay screen: a clean labelled wireframe (inline SVG or simple HTML/CSS in an artifact) showing where the play area, controls, HUD/score, and key UI elements sit. Keep it schematic, not polished art.

Ask me up to 3 questions if anything is ambiguous BEFORE writing.

3 Write the TDD — with all the rules baked in Viết TDD — với tất cả quy tắc được nhúng vào trong

Don't ask for a "technical design document" generically — the AI will give you something bland. Hand it your exact engineering constraints. This prompt already contains all of them. Save the result as tdd.md.

Đừng hỏi AI "viết technical design document" một cách chung chung — nó sẽ cho bạn thứ gì đó nhạt nhẽo. Hãy đưa cho nó các ràng-buộc kỹ thuật cụ thể của bạn. Prompt này đã chứa tất cả rồi. Lưu kết quả với tên tdd.md.

• Centralized config + zero magic numbersCentralized config + không magic numbers so non-coders can tweak and playtest. để người không biết code vẫn có thể tinh chỉnh và playtest.
• Strict separation of concernsTách biệt rõ ràng các concerns (physics / render / rules) — keeps the AI from breaking everything on a refactor. (physics / render / rules) — giúp AI không phá vỡ mọi thứ khi refactor.
• Incremental edits + commit after every turnChỉnh sửa từng bước nhỏ + commit sau mỗi lượt with conventional messages. với commit message chuẩn.
• Logging, non-coder comments, and a test suiteLogging, comment cho người không code, và test suite run every turn. chạy mỗi lượt.
• Workspace & build health checksKiểm tra workspace & build before the AI reports success. trước khi AI báo xong.

Put on the Game Architect hat. Create tdd.md (Technical Design Document) for this prototype, based on gdd.md.

Move ALL technical content here: architecture, code conventions, math/formulas, and the full list of tunable configs.

The TDD MUST explicitly encode these requirements:
1. Single centralized configuration file. ALL mechanical, physical, and rules-based constants live in one dedicated config file (e.g. src/config.js) so non-coders can tweak and playtest.
2. Zero Magic Numbers. No pixel dimensions, speeds, friction, colors, or turn limits hardcoded in game loop, physics, or render files.
3. Self-documenting config. Every config key has a natural-language comment explaining what it changes and its recommended range.
4. Maximum separation of concerns — decoupled source files between game states, physics, ui, etc..
6. Commit after every turn. On completing a request: run a local compile/build check, and if it passes, do a Git commit with a clear conventional message (feat:/fix:/chore:/test:). If the build fails, fix it first.
7. Automated workspace diagnostics. Before reporting done, verify the local dev server is running; if not, start it. Note any sandbox limitation that blocks running the server/tests locally and tell me to run it on my machine instead.
8. Health & compilation check. Confirm the build compiles cleanly with no errors before reporting success.
9. Logging. Add log messages with essential info at all key interactions for easy debugging.
10. Comments for non-coders. Add enough code comments to guide a non-coder on how to modify important behavior.
11. Tests. Write a test suite for all logic-based code and run it every turn. Update tests for each new feature or design change.

IMPORTANT: The TDD should be concise, clear, but not too details. It should confirm the overall architecture, and is a doc written by senior developers as GUIDANCE for junior devs to implement, but do not go into actual implementation itself. Ask me about my game's specific layers/mechanic if you need to before finalizing.

4 Build plan — 3 milestones Kế hoạch build — 3 milestones

Three milestones, not five — but split them around your game's own mechanic, not a fixed template. The AI proposes the division and explains its reasoning; you sanity-check it. Each milestone ends in something you can actually play or test.

Ba milestones, không phải năm — nhưng chia dựa trên mechanic của chính game bạn, không theo template cố định. AI đề xuất cách chia và giải thích lý do; bạn kiểm tra lại. Mỗi milestone kết thúc bằng thứ gì đó bạn thực sự có thể chơi hoặc test.

• Exactly 3 functional milestonesĐúng 3 milestones thực chức năng , each building on the last. , mỗi cái build trên cái trước.
• Divided by what THIS game needsChia dựa trên những gì game NÀY cần — the mechanic drives the split, not a generic "setup / build / polish" template. — mechanic dẫn dắt cách chia, không phải template "setup / build / polish" chung chung.
• Every milestone delivers real functionality progression Mỗi milestone mang lại tiến triển chức năng thực sự
• Each milestone has a user-facing test checklist and a copy-paste agent prompt. Mỗi milestone có checklist test từ góc độ người dùng và prompt copy-paste cho agent.
• Sanity-check the planKiểm tra lại kế hoạch — have the AI summarize the 3 milestones and its reasoning back to you before building. — bảo AI tóm tắt lại 3 milestones và lý do chia như vậy trước khi bắt đầu build.

Put on the Tech Lead hat. Create plan.md — a build plan with EXACTLY 3 milestones (not more).

Important: the 3 milestones must be split MEANINGFULLY around THIS game's own mechanic — not a generic template. Read gdd.md and tdd.md, then divide the work into 3 functional layers that each build on the previous one and each end in something I can actually play or test. As a rough guide (adapt to the game):
- Milestone 1 is usually the static foundation: scaffold, centralized config, the scene/board/world laid out correctly, HUD placeholders, clean module boundaries. It runs and looks right; the core interaction isn't live yet.
- Milestone 2 is usually the core mechanic itself — the ONE thing that makes the game fun, working end-to-end (input → simulation/logic → feedback). This is the milestone that proves the idea.
- Milestone 3 is usually the rules, win/lose, and full game loop wrapped around that mechanic, plus a GitHub Pages deploy so it's shareable.
But you decide the actual split based on what this specific game needs — tell me your reasoning for the division before listing the details. Do NOT make milestone 3 a generic "polish" pass; this is a prototype, so every milestone must deliver real functionality.

Each milestone must include:
(a) a short scope paragraph,
(b) a checklist of things to test FROM THE END-USER's perspective,
(c) a single copy-paste prompt for the local AI coding agent — and that prompt must explicitly remind the user to run the test checklist.

Follow tdd.md for all conventions. Write plan.md now.

5 Build, milestone by milestone Build, từng milestone một

Initialize a git repo and commit all current files in this folder.

From now on, in ALL of our conversations: after each turn, run a build/compile check; if it passes, commit all changes with a clear, concise, conventional message (feat:/fix:/chore:/test:), and push to this repo: [PASTE YOUR GITHUB REPO LINK]

If the build fails, fix it before committing.

Switch to your AI coding agent (not chat) — it reads, writes, and runs files directly. One milestone per chat session to keep context clean. Start with the mid-level model; only escalate if you get stuck.

Chuyển sang AI coding agent (không phải chat) — nó đọc, viết, và chạy file trực tiếp. Một milestone mỗi chat session để giữ context gọn. Bắt đầu với model tầm trung; chỉ escalate khi bị bí.

• New session per milestone.Session mới cho mỗi milestone. Avoids context overflow and hallucination; easier to search later. Tránh tràn context và hallucination; dễ tìm lại sau này hơn.
• Run the milestone promptChạy milestone prompt (below), then do the test checklist from plan.md yourself. (bên dưới), sau đó tự thực hiện test checklist từ plan.md.
• Converse back and forth with the AI:Nói chuyện qua lại với AI: Talk as if you are talking to a dev: says what you need to change, and let the dev do it. Trao đổi như bạn đang nói chuyện với dev — nói những gì bạn cần thay đổi, và để dev làm.
• Make your own manual edits:Tự tay chỉnh sửa: open the folder in VS Code and tweak config file as needed. Perform text search across all files (Ctrl+Shift+F) and make text adjustments. Do any other code editing that you are confident to do faster/cheaper/more accurate than AI. mở folder trong VS Code và tinh chỉnh config file khi cần. Dùng text search toàn bộ file (Ctrl+Shift+F) để chỉnh sửa text. Làm bất kỳ việc chỉnh code nào mà bạn tự tin làm nhanh hơn/rẻ hơn/chính xác hơn AI.
• After a milestone, refresh the docsSau mỗi milestone, cập nhật lại docs (gdd/tdd/plan), then open a fresh session for the next. (gdd/tdd/plan), rồi mở session mới cho milestone tiếp theo.

We are building [GAME NAME]. Read gdd.md, tdd.md, and plan.md first.

Execute Milestone [1 / 2 / 3] from plan.md, following every convention in tdd.md (centralized config, zero magic numbers, separation of concerns, incremental edits, logging, comments, tests, commit-after-turn).

Work in small testable steps. When done, verify that the game is runnable and accessible via an URL, create and run tests on the logic parts, report the results.

After everything is done, show user both the URL to test the game AND the list of things to verify on their end, for this milestone.

Milestone [N] is complete and tested. Update gdd.md, tdd.md, and plan.md to reflect what we actually built and any decisions that changed. Commit the doc updates. Then summarize what's left so I can start the next milestone in a fresh session.

6 Fix bugs the smart way Sửa lỗi theo cách thông minh

Iteration is normal — even human devs never get it right in one shot. Give the AI the right evidence and it fixes fast.

Iteration là bình thường — ngay cả dev người thật cũng không bao giờ làm đúng ngay lần đầu. Cung cấp đúng bằng chứng cho AI và nó sẽ sửa nhanh thôi.

• Visual bug → attach a screenshot.Lỗi giao diện → đính kèm screenshot. Words alone rarely convey a layout problem. Chỉ dùng từ ngữ hiếm khi truyền đạt được vấn đề layout.
• Logic bug → open DevTools (F12) → Console → paste the full log. Lỗi logic → mở DevTools (F12) → Console → paste toàn bộ log.
• Watch the AI "think"Quan sát AI "suy nghĩ" — if it's heading the wrong way, stop it early to save time and tokens. — nếu nó đang đi sai hướng, dừng sớm để tiết kiệm thời gian và token.
• Stuck for a while? Start a fresh sessionBí một lúc rồi? Mở session mới and ask it to explain the feature's flow before fixing. và bảo nó giải thích flow của feature trước khi sửa.
• Tell it to add debug logsBảo nó thêm debug logs when a bug is hard to pin down. khi lỗi khó xác định nguồn gốc.

Here's a visual/UI bug. [ATTACH SCREENSHOT]

What's wrong: [DESCRIBE what you see vs. what you expect]

Find the cause, fix it via the centralized config or the render layer (not by hardcoding), keep the fix incremental, then tell me exactly what you changed and which config value I can tweak to adjust it further.

Here's a logic bug. Console output below. [PASTE the full console log from F12 → Console]

What happened: [DESCRIBE the wrong behavior]
What I expected: [DESCRIBE correct behavior]

Diagnose the root cause, add temporary debug logs if helpful, fix it incrementally, update the relevant test, and explain the fix in plain language.

We've been stuck on this bug for a while. Don't patch blindly.

First, review the relevant code end-to-end and explain to me, in plain language, the full flow of how [FEATURE] is supposed to work. Then point to where the flow breaks. Wait for my confirmation before changing anything.

7 Ship it — share a live link Ship — chia sẻ link chạy thật

For an HTML game this is easy. The agent writes the deploy workflow; you flip one setting in GitHub.

Với HTML game thì cực kỳ dễ. Agent viết deploy workflow; bạn chỉ cần bật một cài đặt trong GitHub.

• Have the AI prepare the GitHub Pages workflowĐể AI chuẩn bị GitHub Pages workflow and push it. và push lên.
• In GitHub → Settings → PagesTrong GitHub → Settings → Pages , set Source to "GitHub Actions". , đặt Source thành "GitHub Actions".
• Confirm the live URL worksXác nhận URL live hoạt động on both desktop and a real phone. trên cả desktop và điện thoại thật.
• Send the link to playtestersGửi link cho playtesters and collect feedback — the whole point of a prototype. và thu thập feedback — đó chính là mục đích của prototype.

Prepare this project for a GitHub Pages workflow that auto-publishes after every push to the main branch.

Do everything you can yourself (create the workflow file, set the correct build/base settings, commit, push). Then tell me exactly what I need to do on my side in the GitHub web UI, step by step.

One-glance recap

Tóm tắt