ourbreak
工程紀律 × AI Agent
如何避免 vibe
出一堆垃圾
用一套工程框架馴服 coding agent —— 以 ourbreak 這款海灘破壞遊戲為例。
ourbreak · 第一人稱海灘破壞遊戲01 / 15
命題
agent 沒規格、沒記憶、沒驗證，
於是自信地生出一堆垃圾。
沒規格 → 自己編需求沒記憶 → 重蹈覆轍沒驗證 → 壞了也不知道
解法不是換更強的模型 ——
是把 agent 關進工程框架，讓它只能交出好東西。
為什麼會 vibe 出垃圾02 / 15
01 — 設計架構
先把「要做什麼」
說清楚，agent 才不會自己編。
GDD 說玩法 · TDD 說技術 · AGENTS.md 說家規 · OpenSpec 把每件事先寫成規格。
01 · 設計架構04 / 15
設計架構 · 給 agent「怎麼動手」
AGENTS.md — 規範寫死，agent 不臨場發明
CLAUDE.md 只是 symlink，真正內容一份就好：環境、指令、編碼規範全講死。
Common commands
bash · 一切都在 nix develop 裡dev shell$ nix develop # 先進 dev shell
$ ./gradlew build # 編譯
$ ./gradlew test # 必須全綠 0 fail
$ ./gradlew clean # 清掉 build/
$ ./gradlew test --tests "*DifficultyCurveTest"
Code conventions
langJava 21 —— records · sealed · pattern matching · text block
pkg根套件統一 com.ourbreak
style4-space 縮排 · K&R 大括號 · 行長 ≤120
naming類別 UpperCamel · 方法 lowerCamel · 常數 UPPER_SNAKE
null可空回傳用 Optional<T>，public API 不回 null
testJUnit 5 · 一類一 *Test · Arrange–Act–Assert
設計架構 · AGENTS.md（規範）07 / 15
設計架構 · agent 的家規
Agent 守則 —— 8 條硬規則
不是建議，是 pre-commit hook 會擋下的硬規則。違反就 commit 不了。
env一律在 nix develop 裡跑，不賭系統 Java / Gradle
test./gradlew test 全綠才算完成，0 fail / 0 error
commitConventional Commits，一律走 /commit skill
devlog每個 commit 附一篇 devlog，hook 強制
flakeflake.lock 釘死工具鏈，不問不動 flake.nix
deps加依賴先問，優先標準庫 / 知名庫
progress每 commit 更新 milestone 表，跟程式同包
artefactsbuild/ · *.class · *.jar 一律不進 git
.claude/hooks/pre-commit 雙閘 —— test gate + devlog gate，靠機制把關，不靠 agent 自覺。
設計架構 · AGENTS.md（守則）08 / 15
設計架構 · 反 vibe 招牌動作
OpenSpec — Spec-Driven Design
寫 code 前先寫 spec。一個 change = 一整包文件，用 SDD 取代 plan mode。
openspec/changes/2026-06-16-shell-splitting/├─ proposal.md # 為什麼要做
├─ design.md # 怎麼做
├─ tasks.md # 拆成可勾選步驟
└─ specs/
├─ weapon-damage/spec.md
└─ shell-splitting/spec.md
→先規格、後實作
需求與行為先成文，agent 照 spec 寫、不自由發揮
→一個 change 一包
proposal + design + tasks + specs/ 綁在一起 review
12+changes/archive/
已累積十多包歸檔的 change，每包都可回溯
設計架構 · OpenSpec (SDD)09 / 15
成果檢驗 · 過不了就 commit 不了
自動測試 ‖ 手動測試
AUTO · 20 個 JUnit
Headless 邏輯測試
·DifficultyCurveTest — 鎖死難度永遠遞增、不暴衝
·VillageGeneratorTest — 種子可重現、受預算上限
·VictorySystemTest — 清光進關 / 逾時 Game Over
·不開視窗、不依賴 render thread，CI 可跑
MANUAL · 人在迴圈
手感與體驗
·實機 playtest：手感、節奏、視覺破壞回饋
·跨平台：原生 Windows 捕獲式 FPS、WSLg workaround
·錄影留證：每版 gameplay demo 存檔對照
·自動測不到的「好不好玩」由人來判
pre-commit test gate：./gradlew test 零失敗才進得了 commit —— 壞掉的程式碼根本進不了 repo。
成果檢驗 · Auto + Manual12 / 15
實機錄影
crab-village 圍城、太陽 / 陰影 / god rays 光影，與第一人稱手持武器 —— 框架接住，agent 才做得出來。
WASD 移動1 劍 · 2 槍 · 3 無人機清光進關 · 逾時 Game Over
github.com/iceice666/ourbreak
Q&A
Demo → Q&A15 / 15