昨天 Day 04 的五個步驟裡，最後一步是「把遊戲的架構寫進 README.md」。

當時我直接把規格放進 README，是因為它本身就是 Markdown 文件，而且放在 GitHub 上之後，也能直接當成專案首頁的說明。

不過規格其實可以是任意檔名：

AI 需要的是一份明確的規格文件，檔名不一定非得叫 README.md。

也可以叫 project_specs.md、game_design.md，甚至拆成好幾份文件。只要在 CLAUDE.md 裡告訴 Claude Code 到哪裡找就可以。

所以今天真正要拆開看的，是：一份給 AI 看的規格，到底應該寫什麼？

一、AI 每天都在失憶

我昨天跟 Gemini 討論了很多遊戲規則、卡牌和目錄結構。
但如果隔天開一個新的對話，新的 AI 並不知道我們昨天討論過什麼。
這不是 Bug，而是對話工作的特性。每個新對話都有自己的上下文，而上下文又是有限的。
那能不能把昨天的聊天記錄整份貼給 AI？
可以，但實際上不太好用。

因為聊天記錄裡面會有很多我們討論過、但最後沒有採用的想法，也會有來回修改的過程。
例如：

「要不要加職業？」
「好像可以。」
「但是這樣會不會太複雜？」
「那先不要。」
「那是不是改成單一牌組比較簡單？」

如果把整段對話丟給新的 AI，它還得重新判斷哪些是最後決定、哪些只是討論過的想法。
所以我需要的是一份整理好的結論，而不是把整段過程重新丟給 AI。
這就是 Markdown 文件存在的原因。

二、我的 README 長什麼樣？

這是 Gemini 從五百多行對話壓縮出來的，我一個字都沒改就用了。
整份 README 大致分成五個區塊，每一個區塊都在回答 AI 接下來工作時需要知道的事情。

1. 這是一款什麼遊戲？

開發初期，我先暫時把遊戲取名為：

黑曜石之試煉 (Obsidian Trial)

README 當時的描述是：

一款極簡風格的 Roguelike 卡牌 RPG 遊戲。
玩家將經歷 9 次事件抉擇構築牌組，最終迎戰黑曜石魔王！

這個名字後來又改過。
最後正式使用的名稱是 《異世界救援》。
所以這裡看到的「黑曜石之試煉」，代表的是開發初期的暫定名稱，不是最後的遊戲名稱。
名稱只是第一步，對 AI 來說，更重要的是先知道這是一款什麼樣的遊戲，以及它有哪些核心規則。
「Roguelike 卡牌」也能先讓 AI 知道這是一類什麼樣的遊戲，再往下看具體規則。

2. 核心遊戲機制

遊戲流程：
- 共 10 個階段
- 第 1-9 關：隨機事件，三選一張卡牌/升級
- 第 10 關：最終 Boss 戰

核心數值：
- HP：生命值
- Armor：護甲值，優先吸收傷害
- Attack：攻擊力

這一段很重要。
例如「護甲值：優先吸收傷害」不是單純列出一個數字，而是在說明數值之間怎麼互動。
這類規則可以成為 AI 實作時的依據。
所以寫規格的時候，我發現「數值之間怎麼互動」比單純列出「有哪些數值」更重要。

3. 卡牌種類

初始牌組：
- 斬擊 × 2
- 招架 × 2

護甲流：
- 舉盾
- 盾牌衝鋒

狂暴流：
- 戰意高漲
- 賣血狂暴

破甲/效果：
- 重擊
- 破甲打擊

這裡讓 AI 知道目前有哪些卡牌，以及大致的設計方向。
當然，實際遊戲後面還會繼續增加卡牌。
而像「盾牌衝鋒」這種卡牌，括號裡如果再寫上「護甲 → 傷害」之類的說明，對 AI 來說就是更直接的實作提示。

4. 目錄結構

assets/
├── images/
└── audio/

scenes/
├── Card.tscn
├── RewardScene.tscn
└── BattleScene.tscn

scripts/
├── Global.gd
├── Card.gd
├── RewardScene.gd
└── BattleScene.gd

README.md

這一段的作用，是讓 AI 知道檔案應該放在哪裡。
如果沒有先講清楚，AI 就可能自己決定目錄和檔案名稱。
有了這份結構，後面建立檔案時就有一個共同的基準。

5. 開發 Roadmap

最後是開發階段。

Phase 1：MVP

• [x] Global.gd
• [x] Card.tscn
• [x] RewardScene
• [x] BattleScene
• [x] 勝利 / 失敗流程

Phase 2：美術與 UI

• [ ] 使用 Itch.io / Kenney 的免費 2D UI 素材
• [ ] 將文字按鈕換成卡牌框架與圖片
• [ ] 加入 TextureProgressBar
• [ ] Boss 圖片 / 地城背景

Phase 3：打磨

• [ ] 音效
• [ ] 飄字傷害 / 畫面震動
• [ ] 增加 5-10 張卡牌
• [ ] 增加一個額外事件

這些勾選框對 AI 來說很方便。
新的對話開始時，可以快速知道哪些東西已經完成，接下來應該做什麼。

三、驗收：AI 真的照著規格設計了嗎？

規格寫完之後，等 Claude Code 說「完成了」。我就把 README 裡的內容，和實際建立的專案檔案一項一項對照。

結果如下：

實際對照後，README 裡列出的檔名都有出現在專案裡，後續開發過程也沒有另外修改這些檔名。

之後卡牌越來越多，AI 把原本放在 Global 裡的卡牌資料獨立出來，認為這樣比較適合管理，於是自行建立了 CardDatabase.gd。它修改專案結構的同時，也同步更新了 README 裡的目錄，讓程式和規格保持一致。

後來實際測試遊戲時，我發現視窗太小，就把解析度從 1280 × 720 改成 1920 × 1080。

README 記的是目前有效的決策和規格，不是每一次修改的歷史。
所以最後的規格記在 README，中間的討論和修改過程，則留在 Git 紀錄或開發日誌裡。

四、該寫什麼，不該寫什麼？

這次整理 README，我慢慢整理出三個原則。

1. 寫規則，不要只寫名詞

例如：

❌ 三個數值：

HP
Armor
Attack

✅ 寫清楚它們怎麼互動：

Armor 優先吸收傷害，剩餘傷害才扣除 HP。

AI 需要的是可以拿來實作的規則。

2. 寫決策，不寫過程

例如我曾經考慮過「加入職業系統」，最後為了控制規模把它砍掉。
這件事情對開發日誌很有價值，但沒有必要放進目前的規格裡。
因為現在真正有效的決定就是：

本遊戲沒有職業系統。
所有玩家使用同一套牌組。

我後來會用一個很簡單的方式判斷：

這句話會不會影響 AI 下一步要寫的程式？

如果不會，它可能比較適合放在開發日誌，而不是規格文件。

3. 寫目前有效的狀態，不要塞進開發歷史

如果解析度從 1280 × 720 改成 1920 × 1080，那 README 更新成現在的設定就好。

不需要寫：

原本是 1280 × 720
後來改成 1920 × 1080

這種歷史可以交給 Git。
README 要讓下一次進入專案的 AI，很快知道：

現在這個專案到底是什麼狀態？

五、README.md 只是其中一種選擇

這次我把規格放在 README，是因為它有兩個用途。

• 第一，可以讓 AI 找到專案的規則和結構。
• 第二，README 放在 GitHub repository 裡，可以直接成為專案首頁，讓其他人看到這個遊戲是什麼、怎麼玩、做到哪裡。

但如果是其他專案，我也可以把詳細規格放在：

project_specs.md

或：

game_design.md

甚至拆成：

docs/
├── game_design.md
├── card_rules.md
└── architecture.md

然後在 CLAUDE.md 裡告訴 Claude Code：

## 專案規格

遊戲規格請參考：
- project_specs.md
- docs/card_rules.md

所以不一定要叫 README.md。

重要的是把目前有效的規則、決策和專案結構寫下來，而且讓 AI 找得到。

這次只是剛好把它放在 README，也能讓 GitHub 首頁直接看到這些內容。

六、今日小結

今天主要做了三件事：

1. 請 Gemini 把遊戲發想的討論，整理成一份 Claude Code 可以直接使用的 Markdown 規格。
2. 實際比對 README 和 Claude Code 建立的專案檔案，確認場景、Script、卡牌等內容都有照著建立。
3. 確認 README 記錄目前有效的規格和決策，開發過程則另外留在 Devlog.md。

到今天為止，第一階段結束了：

心法、雙 AI 分工、企劃收斂、環境搭建、專案地基。

遊戲核心規則確定，開發環境也都裝好了。
明天 Day 06 開始正式動手。

第一件事就是 Git：
當 Claude Code 說要執行git init時，我沒有直接按下 Allow，而是先停了一下。