序章:測試驗收的盲區
2026 年 5 月,一個以 Phaser + TypeScript 開發的俯視角躲避球遊戲完成部署。12 個 Phase 線性開發,歷經 11 個月;所有單元測試通過;E2E 自動化測試 100% 覆蓋;兩輪人工 Smoke Test 核准;老闆拿到可部署的遊戲。
老闆打開遊戲,玩了 30 秒。
遊戲立刻停止。列出三個致命問題:
- 場上球幾乎全在敵方手中,我方無法有效控制球權
- 我的隊友沒有任何行動——螢幕上有三個友方角色,全都站著不動
- 看不到任何角色的血量
這些都是核心遊戲機制。這些都應該在 Phase 4(Classes, Skills & HUD)完成時就被發現。
或者至少在 Phase 5(Enemy AI)時被發現。
或者至遲在 Phase 11 發布前被發現。
但它們都沒有被發現。一個分布式的問題,在測試的每一層都通過了,直到一雙人類的眼睛看著遊戲玩起來才暴露。
這篇文章要回答:錯誤最早在哪裡發生?為什麼沒被中途發現?如何避免?
第一段:Spec 撰寫期的隱形決策
所有故事始於一份文件。
spec.md 是以 GDD(Game Design Document)風格撰寫的。它回答了 Game Design 的問題:「這個遊戲有什麼功能?」
- 角色有血量,血量歸零時死亡
- 玩家可以撿起球、投向敵人或隊友
- 未被操控的角色由 AI 自動行動
- 每個技能都有冷卻時間和效果判定邏輯
但它沒有回答 Product Requirements 的問題:「玩家坐在螢幕前應該看到什麼、感受到什麼?」
GDD 說「血條系統(玩家 & 敵人)」。
PRD 應該說:
玩家在任何時刻都能看到所有存活角色的 HP,以紅色血條呈現,位置在角色頭上方 20px,寬度 50px,血條末端繪製百分比數字(純白色、14pt),受擊後 0.1 秒內更新;血量歸零時血條消失,角色播放死亡動畫。
兩者看起來說的是同一件事。但前者是函數簽名,後者是使用者體驗規格。前者告訴工程師「實現這個功能」,後者告訴工程師「去驗證玩家能看到什麼」。
沒有人在 spec 定稿後問:「這份文件的讀者是誰?」
GDD 被默默當成了 PRD。這個決策沒有被 explicitly 做出,只是默認發生了。
另一個隱形結構化問題:spec.md 的 Key Mechanics Checklist 有 20 個項目。格式上它們看起來像驗收標準:
- [ ] 血條系統(玩家 & 敵人)
- [ ] 球的物理與碰撞判定
- [ ] 角色 AI(敵人)
- [ ] ...Checkbox 格式自帶「驗收清單」的視覺暗示。但措辭全是功能名稱(feature list),不是驗收條件(acceptance criteria)。
一份有 checkbox 的清單,讀起來就像可以被 tick off 的標準。實際上每一個都是模糊的。這個視覺欺騙在後續的 impl-plan 設計中造成了漣漪。
第三個遺漏:關於我方隊友 AI,整份 spec 只有一句話:
未被操控的角色由 AI 自動行動
藏在「Character Switching」的說明段落裡,沒有進入 Key Mechanics Checklist,沒有任何行為規格定義。沒有人規定 AI 應該在什麼時機移動、什麼時機投球、如何決定目標。
這就像在建築規格裡說「房子應該是安全的」然後假設結構工程師會自動推導出梁的規格。
第二段:impl-plan 的結構化失敗
impl-plan.md 本應修正 spec 的缺陷,但它反而強化了問題。
HTML Overlay 與測試橋接層的邊界模糊
impl-plan 詳細定義了一套「HTML Overlay」系統,作為 Playwright E2E 測試與遊戲邏輯的橋接層:
<div class="overlay-item" data-testid="char-hp-{id}" data-value="75" data-max="100"></div>
<div class="overlay-item" data-testid="skill-cooldown-{id}" data-value="3000"></div>規範裡列了 15 個 data-attribute 的契約,每一個都清晰定義了:存在條件、值的單位、更新時機。這是優秀的測試規範。
但規範裡沒有說明:這是測試橋接層,不是 HUD 實作。
結果:
GameScene.ts的createOverlayElements()方法產生了這些<div>,但沒有寬度、高度、背景色、邊框GameUIScene.ts只有一行佔位符文字this.add.text(640, 20, 'HUD', ...),沒有任何具體的血條、冷卻指示、分數顯示- 這些空殼通過了所有 Playwright E2E 測試
為什麼能通過?因為 Playwright 測試只驗證了 data-attribute 是否存在,值是否正確:
await expect(page.locator('[data-testid="char-hp-0"]')).toHaveAttribute('data-value', '75');這測試了資料——沒有測試呈現。
impl-plan 在列出「HTML Overlay 規範」時,應該加上一行警語:
本規範定義資料層契約,供測試驗證邏輯正確性。HTML Overlay 不等於 HUD 實作。HUD 實作應在 GameUIScene 中將這些資料值轉化為玩家可見的視覺元素(血條、冷卻條、分數面板)。測試通過 ≠ UI 完整。
沒有人寫這一行。Playwright 測試綠了,每個人都認為「HUD 完成」了。
Phase 線性排列的可玩性危機
impl-plan 定義了 12 個 Phase(Phase 0–11),嚴格線性依賴。可玩性所需的核心元素分散在多個 Phase 中:
| Phase | 內容 | 可玩性影響 |
|---|---|---|
| 2 | Basic Game Loop | 角色能移動 |
| 3 | Ball System | 能撿球 |
| 4 | Classes, Skills & HUD | 應該看到血條 |
| 5 | Enemy AI | 敵人會移動 |
| 6 | Game Flow | 有勝負判定 |
Phase 4 完成後,理論上遊戲應該「第一次可玩」——能移動、能投球、能看到傷害、能看到血條。
但 impl-plan 沒有定義任何一個 Phase 為「最小可玩里程碑」。每個 Phase 的 DoD(Definition of Done)都是獨立的工程指標,沒有一個要求「此時遊戲必須完整可玩」。
結果:Phase 4 完成時,遊戲在工程意義上是「完成」的(所有邏輯通過測試),但在玩家意義上是「殘廢」的(看不到血條)。
沒有任何地方說「這不算完成」。
DoD 設計為工具清單
每個 Phase 的統一 DoD:
npm run typecheck通過npm run test:unit通過,覆蓋率 > 80%npm run test:e2e通過npm run build通過- 人工 Smoke Test
前四項都是工程工具的輸出。第五項「人工 Smoke Test」沒有對應清單——就一個空的類別。
這就像一個飯店的清潔 checklist:
- 廁所刷子掃過沒有(機械驗證)
- 地板吸塵過沒有(機械驗證)
- 床鋪整理過沒有(機械驗證)
- 人工檢查(……檢查什麼?)
如果「人工檢查」沒有明確的項目清單,它實際上沒有約束力。檢查人員可以走進房間、看一眼、打個勾,從沒讀任何清單項。
第三段:Phase 4 的失落機會
Phase 4(Classes, Skills & HUD)是遊戲開發中第一次「應該有 UI」的時刻。
交付物列表:
CharacterClass.ts✅Skill.ts和五個具體技能類別 ✅GameUIScene.ts骨架 ✅- HTML Overlay 的
data-attribute✅ - Playwright E2E 測試 60+ 條 ✅
Code Review 通過,所有測試綠燈。PR 被 Merge。
沒有人問:「現在打開遊戲,能看到血條嗎?」
如果有人問,答案會是「不能」。GameUIScene.ts 只有一行佔位符。
但沒有人問。因為 Smoke Test 沒有一條明確說「驗證血條可見」。
為什麼沒人問?
工程師本能上信任自動化測試。Playwright 測試驗證了 data-testid="char-hp-0" 存在,且值正確;邏輯層面 HP 運作正常。從工程角度,「HUD 完成」這個說法沒有邏輯漏洞。
只是漏洞不在邏輯層,在呈現層。
呈現層的驗證不能自動化到「寫一行程式碼就完成」的程度——必須有人實際看著遊戲,用眼睛確認有視覺反饋。這件事不能被 checklist 化、不能被工具化、不能在 CI pipeline 中執行。
所以它被遺漏了。
第四段:Phase 5 的第二個隱形決策
Phase 5(Enemy AI & Level 1 + Bot API)埋下了第二個核心問題。
AISystem 的架構邊界
GameScene.ts 的初始化代碼:
this.aiSystem = new AISystem();
// ...
this.aiSystem.update(delta, this.enemies, this.combatSystem.balls, this.players, this.combatSystem);this.enemies 進入 AI 邏輯;this.players 只作為「目標資訊」傳入。沒有任何地方對 this.players 執行 AI 決策。
AISystem 的類名和結構,從設計上就只是「敵人 AI」。我方隊友 AI 沒有對應的系統實現。
為什麼?資源排擠
Phase 5 同時引入了「Bot API」——一套 window.__debug.bot 的自動化接口,讓 Playwright E2E 測試可以「玩遊戲」:
await page.evaluate(() => {
window.__debug.bot.selectCharacter(0);
window.__debug.bot.moveTowards({ x: 100, y: 100 });
window.__debug.bot.pickupBall();
window.__debug.bot.throwBallAt({ x: 200, y: 200 });
});Bot API 的工程投入——設計 API 介面、實現每一個操作的邏輯、整合進遊戲迴圈——大約佔用了 Phase 5 工期的 60%。
我方隊友 AI 的實作被往後推遲。然後在往後推遲的過程中,逐漸被遺忘。Phase 6–11 沒有任何 Phase 明確要求「實現我方隊友 AI」。它不在 Checklist 裡,不在 DoD 裡。
資源競爭默默發生。沒有人在規劃會議上說「我們決定優先做 Bot API,把隊友 AI 往後推」。它只是發生了。
Bot 勝利 ≠ 遊戲可玩
Phase 5 完成時,Bot 能從頭玩到尾,贏得遊戲。所有 E2E 測試通過,讓人們認為「遊戲工作正常」。
但 Bot 不需要看血條——它直接讀取 data-attribute。Bot 不需要隊友支持——它自己控制了我方的兩個其他角色。Bot 不需要任何視覺反饋——它按照邏輯序列操作。
Bot 贏了遊戲,這在工程上意味著:邏輯層完整。
但這 ≠ 遊戲可玩。
第五段:Phase 6–11 的問題積累
每個後續 Phase 都在既有的缺陷基礎上疊加。
| Phase | 名稱 | 新增功能 | 遺留問題 |
|---|---|---|---|
| 6 | Game Flow | 場景切換、勝負判定 | 玩家仍看不到 HUD;敵人單方面優勢 |
| 7 | Progression | 升級系統、角色進度 | 進度條看不見;隊友仍不動 |
| 8 | Advanced Content | Boss、Level 2–4 | AI 失衡加倍;新敵人更容易贏 |
| 9 | UI Polish | 「UI 優化」 | 實際優化的是 data-testid 準確度,不是可見 UI |
| 10 | Settings & i18n | 設定菜單、多語系 | 新增可見菜單,但遊戲本體仍殘廢 |
| 11 | Co-op & Deployment | 雙人模式、上線 | 整個有缺陷的遊戲被部署上線 |
每個 Phase 完成時,開發團隊看到的是 ✅ ✅ ✅ 的檢查清單。每一個都綠燈。
這些綠燈有麻痹作用。
當第 6 個、第 7 個、第 8 個 Phase 都通過時,人們開始相信「系統運作」。懷疑開始消退。對既有問題的警惕性開始下降——「如果這個真的有問題,早就會被前面的 Phase 抓出來」。
技術債被測試綠燈覆蓋。測試綠燈讓人不再質疑。
Phase 9 的視覺欺騙
Phase 9 的名稱是「UI Polish」。這聽起來像「我們現在要優化已有的 UI」。
實際上,此時遊戲根本沒有可見的 UI——只有被 data-attribute 標記的空白 div。Phase 9 「優化」的是什麼?
Playwright 測試對 data-attribute 的驗證更加嚴格。HTML Overlay 的更新邏輯被重構,以確保 data 值總是同步。
看起來像 UI 優化,實際上是測試合規性的提升。
沒有人說「我們實際上還沒有可見 UI」。
第六段:為什麼直到試玩才被發現
完全的一致性在於:整個開發週期中,「玩遊戲」從來不是正式的驗收動作。
Vercel 部署通過 ✅ 所有 Pipeline 檢查通過 ✅ Smoke Test 簽名確認 ✅ 一個月的線性開發,每個 Phase 都過了 ✅
直到有人——不是開發者、不是 QA、只是一個沒有背景知識的遊戲玩家——打開遊戲。
這個人用對待一般遊戲的方式對待它:玩。
30 秒內三個問題浮出。
根因分析:10 點
實作與流程層面
1. 測試契約被誤認為 UI 實作
HTML data-attribute overlay 是測試橋接層。它存在的目的是讓 Playwright 有一個穩定的 hook 來讀取遊戲狀態。但在 impl-plan 中,它與「HUD 實作」沒有清晰邊界。
結果:Playwright 能讀到血量值 = HUD 完成 ✅
這個等式在工程邏輯上清晰,但在使用者體驗上是錯誤的。
2. DoD 缺乏玩家視角的驗收標準
五項統一 DoD,全部以工程工具結果為準。沒有任何一項說「玩家應該能看到 X」。
「人工 Smoke Test」唯一提到玩家視角,但沒有對應的檢查清單。它看起來像約束,實際上是開放的。
3. AISystem 設計邊界只涵蓋敵人
我方隊友 AI 從未被任何 Phase 的 DoD 明確要求。它不是執行疏失,是架構設計的邊界設定。AISystem 的名稱和實現,都指向「敵人 AI 系統」。
4. Phase 線性排列,可玩性被推遲到末端
可玩性必要元素(移動、投球、傷害、血量、勝負、視覺反饋、隊友協助)分散在 Phase 2–6。沒有任何一個 Phase 的 DoD 要求「此時遊戲必須完整可玩」。
可玩性變成了一個涌現特性(emergent property),而不是一個明確的需求。涌現特性沒有被設計,沒有被驗收。
5. Event Bus 的訂閱端沒有測試覆蓋
許多遊戲機制通過 Event 實現。例如 Taunt 技能發射 SKILL_ACTIVATED 事件,應該有音效訂閱、動畫訂閱、HUD 訂閱。
發射端有單元測試覆蓋。訂閱端沒有。
如果沒有訂閱者,事件進入虛空,無聲失敗。測試不會告訴你「沒人監聽」。
6. Bot API 投入排擠了隊友 AI 的實作資源
資源有限。Phase 5 選擇投入 Bot API 而不是隊友 AI,這是一個策略決定。但決定沒有被明確討論,沒有被紀錄。
兩個系統的優先序只是默默地被 Phase 時程排成了顯著的差異。
Spec 層面
7. GDD 被直接當作 PRD,缺少需求轉譯步驟
「遊戲有血條」(GDD 層面的事實)需要轉譯為「玩家看到紅色血條,位置在角色頭上,實時更新」(PRD 層面的可驗證需求)。
這個轉譯步驟沒有發生。工程師收到 GDD,直接開始實作。缺少的那一步,正好是「視覺呈現需求」和「AI 行為規格」落空的地方。
8. Spec 對「呈現層」與「邏輯層」未做區分
Key Mechanics Checklist 全是功能描述。沒有一項明確指向呈現層。
「血條系統」VS.「血條系統 + 玩家可見的血條視覺呈現」——兩句話說的同一件事,但後者把前者清楚地劈成了兩層。
Spec 沒有做這個劈分。實作就沒有明確的目標。
9. Key Mechanics Checklist 的格式造成誤導
Checkbox 列表看起來像驗收清單。但措辭是模糊的(feature list),不是明確的(acceptance criteria)。
讀 spec 的人看到 20 個 checkbox,本能上認為它們代表了 20 個驗收標準。實際上,每一個都需要被細化。
這個細化沒有發生。checkbox 被直接當成了實作指導。
10. AI 行為規格的缺失是 Spec 層面的範疇遺漏
「未被操控的角色由 AI 自動行動」——整份 spec 只有這一句關於我方隊友 AI。而且藏在 Switching 的說明段落裡。
沒有:什麼時機移動、什麼時機投球、如何選擇目標、冷卻時間、優先序。
這不是工程疏失,是規格的本體缺陷。工程師沒有源頭需求,所以什麼都實作不了。
完整根因鏈
GDD 未轉譯為 PRD(根因 7)
↓
呈現層需求 & AI 行為規格缺席(根因 8、10)
↓
impl-plan 的 DoD 設計者無明確依據定義玩家視角的驗收標準(根因 2、3、9)
↓
測試只覆蓋邏輯層,呈現層與 AI 行為沒有測試鉤點(根因 1、5)
↓
視覺呈現與隊友 AI 被系統性地遺漏(根因 4、6)
↓
所有自動化檢查通過,直到人類玩家看一眼
預防機制
第一優先(高影響、低成本)
1.1 Spec 完成後強制進行「工程讀寫對齊」
PM + 架構師,對照一遍 spec。具體流程:
- PM 說一個功能:「角色有血條系統」
- 架構師回問:「玩家看到什麼?在哪裡?什麼條件更新?」
- PM 說出詳細需求,或意識到自己沒有想清楚
- 結果記錄在「需求理解差異表」
上限 2 小時,通常 1 小時足夠。成本極低,影響極高。
1.2 Spec 加入固定區塊:呈現層需求清單 & AI 行為規格清單
呈現層需求清單:
## 呈現層需求
- HP Bar:所有存活角色頭上 20px,紅色,寬 50px,實時反映血量百分比;數字顯示右側
- Skill Cooldown:HUD 左下角,四個技能圖標排列,灰色遮罩表示冷卻中,覆蓋百分比
- ...AI 行為規格清單:
## 我方隊友 AI 行為規格
- 移動目標:靠近距離自己最近的球,或如果無球,靠近距離隊友最遠的敵人
- 投球目標:視線範圍內距離最近的敵人,如無敵人則不投
- ...強制這兩個區塊存在,將「呈現」和「行為」從模糊的 GDD 明確化。
1.3 Key Mechanics Checklist 改格式
從:
- [ ] 血條系統(玩家 & 敵人)改為:
- [ ] 血條系統|驗收:場上每名存活角色頭頂可見紅色血條,受擊後 0.1s 內實時更新;歸零時消失驗收條件要么說「玩家能看到 X」,要么說「邏輯驗證 X」。Checklist 從 feature list 變成 acceptance criteria。
第二優先(高影響、需紀律)
2.1 impl-plan 強制設立「最小可玩性里程碑 Phase」
一個明確的 Phase(例如 Phase 4a),DoD 包括:
- 角色能移動
- 能撿起球
- 能投向敵人
- 敵人受擊並失血
- 玩家能看到敵人血量變化
- 勝負判定(最後一人存活)
六件事同時成立。人工試玩 5 分鐘,確認遊戲能完整玩一局。
這會讓「可玩性」從涌現特性變成顯式需求。
2.2 每個 Phase 的 DoD 加入「玩家感知驗收清單」
3–5 條清單,格式統一:「以玩家身份、不開 DevTools,能否觀察到 X?」
例如 Phase 4 的 DoD 加上:
- [ ] 人工試玩 3 分鐘:確認能看到敵人血量即時變化
- [ ] 人工試玩 3 分鐘:確認能看到技能冷卻倒數
- [ ] 人工試玩:確認被击中時有清晰的視覺或音效反饋這些項目無法自動化,必須有人執行。但明確列出,就不能被遺漏。
2.3 HTML Overlay 規範明確標注層級
impl-plan 的 HTML Overlay 章節加入警語:
## HTML Overlay 規範
⚠️ **本規範定義資料層契約,供測試驗證遊戲邏輯。**
**HTML Overlay 元素本身不可見;這些資料需在 GameUIScene 中轉化為玩家可見的視覺元素。**
測試通過 data-attribute ✅ ≠ UI 實作完成 ❌
[具體 data-attribute 規格...]這一行能防止「HTML Overlay = HUD」的誤解。
第三優先(可漸進建立)
3.1 Event Bus 規範:emit 必須配套訂閱測試
每個事件定義時,強制說明預期訂閱者及其行為:
/**
* 技能發動事件
* @event SKILL_ACTIVATED
* @param skillId - 技能 ID
*
* 訂閱者:
* - CombatSystem:處理傷害計算
* - AudioSystem:播放技能音效
* - AnimationSystem:播放技能動畫
* - HUDSystem:更新冷卻顯示
*/
this.events.emit('SKILL_ACTIVATED', skillId);每個訂閱者都對應一條測試,測試命題為「given 事件 X 被發射,then 目標系統狀態應為 Y」。
3.2 Phase 規劃時資源分配顯性化
開發計劃會議上,功能實作與測試輔助工具(如 Bot API)的資源競爭要被顯性討論:
Phase 5:Enemy AI & Level 1 + Bot API
時程分配:
- 敵人 AI 實現:40% (2.4 days)
- Level 1 設計與資源:20% (1.2 days)
- Bot API:40% (2.4 days)
決策:優先完成 Bot API,因為它能加速後續 Phase 的 E2E 測試編寫。
隊友 AI 推遲至 Phase 6–7。
後續追蹤:確保隊友 AI 被排入相應 Phase 的 DoD。資源競爭不會消失,但至少能被明確討論、記錄、追蹤。
長期方向
將 GDD 和 PRD 分成兩份文件
GDD.md:遊戲有什麼功能PRD.md:玩家體驗是什麼、如何驗收
中間有一次正式的「需求細化會議」作為轉換節點。
引入定期 Playtest
每完成一個重要 Phase(例如 4、6、8),邀請非開發成員(PM、設計、朋友)花 30 分鐘實際操作遊戲。不要求他們給出結構性反饋,只要求記錄「第一印象問題」。
第一印象是最誠實的使用者體驗信號。
核心教訓
測試驗收的對象決定了什麼問題會被發現。
驗收標準的隱性讀者是 CI 系統。
CI 系統看不到的東西就不會被驗收。
具體來說:
- 資料正確 ≠ 資訊可見 — 資料層可以通過所有邏輯測試,但呈現層可以保持空白
- 資訊可見 ≠ 體驗成立 — 血條存在,但位置、尺寸、更新頻率可能讓玩家無法快速反應
- Bot 能完成遊戲 ≠ 人類玩家能享受 — 自動化腳本不需要視覺反饋、不需要隊友協助、不需要任何人類直覺
- 「所有測試通過」和「遊戲好玩」是完全不同的命題 — 一個在工程空間中(邏輯層),一個在使用者空間中(感知層)
Dodgeball Game 的故事就是這個邊界的一個完美案例。工程上滿分,使用者上不及格。
在兩個空間都要通過,需要有意識地在需求層面做出區分,在驗收標準中都有對應。
後記
這不是一篇譴責故事。每一個失誤點都是合理的局部決策:
- GDD 本身沒有問題,問題是拿它當了 PRD
- HTML Overlay 規範很有用,問題是沒說清楚它的邊界
- Bot API 的投入是值得的,問題是排擠隊友 AI 的決策沒被明確化
- Phase 線性開發很常見,問題是沒有一個里程碑強制「遊戲必須可玩」
局部合理,全局失敗。這是複雜系統常見的失敗模式。
預防機制也都不複雜——幾個會議、幾個文件區塊、一個 Playtest 環節。都在成本承受範圍內。
但實施需要一個關鍵的轉變:把驗收的地點從 CI pipeline 移到人類的眼睛和手指。
讓 CI 保留它最擅長的事:邏輯驗證。
留出明確的空間給:呈現層驗證、體驗驗證、直觀感受。
兩層都要綠燈,遊戲才算完成。