前陣子寫過一篇關於 AI Sub-Agent 驗收的文章，結論是：Build Pass 不代表品質合格，因為 AI 不會主動讀專案規範。
這篇要講的是更前面的問題：如果你把 Issue 寫得夠詳細，AI 是不是就不會亂寫了？
答案是：對，但你要寫到一個讓人崩潰的程度。
從三行需求開始
事情是這樣的。我們在做一個製造業的 MES 系統，需要一個「工作生命週期」的前端介面。一開始的 Issue 大概長這樣：
Issue #4：MES 前端介面建置
建立 MES 工作生命週期的前端頁面，包含開工、暫停、完成等操作。
參考現有系統的 work-execution 模組。
看起來很合理對吧？給人類工程師的話，這個 Issue 加上口頭溝通就夠了。
但給 AI？完全不夠。
第一版：AI 寫了一個桌面 CRUD
Sub-Agent 拿到這個 Issue 後，按照它最熟悉的 pattern 寫了一個標準的桌面端 CRUD 頁面：查詢列表 + 表單 + 彈窗。
問題是：這個系統是給工廠現場用的，操作員拿的是平板。桌面端的精細操作（小按鈕、密集表格、多層彈窗）在平板上根本沒法用。
我自己也有錯。Issue 裡只寫了「參考現有系統的 work-execution 模組」，但沒有具體說明那個模組的 UI pattern 是什麼——Context Provider 管理狀態、Header/Content/Footer 三段式佈局、大按鈕操作導向。
AI 不會自己跑去讀「現有系統」的 source code 然後自動理解設計意圖。它需要你把意圖翻譯成具體的技術規格。
重寫：10 個章節、20K 字
後來我花了大概兩個小時重寫這個 Issue。最終版本有 10 個章節，將近 20,000 字。
大致結構是這樣的：
1. 功能概述
不只是「做一個頁面」，而是明確描述這個介面的使用情境：誰在用、在哪裡用、用什麼設備、操作頻率如何。
2. UI 架構
指定用 Context + Header/Content/Footer 模式，不是傳統的 Query + Table + Form。附上現有模組的檔案結構作為參考。
3. Header 規格
兩個下拉選單（工作中心 + 製程），選完才算定位到一個工位。右上角有選項菜單：上班人員管理、回到首頁、登出、返回。
4. Content 規格
工單列表的顯示方式、欄位定義、排序邏輯、狀態標示。
5. Footer 規格
三顆按鈕：開工（綠色）、暫停（紅色，展開子選單：除外/凍結）、完成（綠色）。每顆按鈕在不同狀態下的顯示/隱藏邏輯。
6. 狀態機
工單的狀態轉換：待開工 → 生產中 → 暫停 → 生產中 → 完成。凍結是特殊狀態，凍結後自動退回待開工畫面但保留工單佔用。
7. 解凍邏輯
開工按鈕在有凍結工單時動態變成「解凍」，點擊後開 Modal 讓操作員選擇要解凍哪一張。
8. 元件規範
指定使用哪些共用元件（FormFullModal vs InfoFullModal）、API 用 orval hooks、i18n 規則、權限控制。
9. 程式碼範例
直接貼出 Context Provider 的骨架、Header 元件的 props interface、Footer 按鈕的條件渲染邏輯。
10. 工作項目清單
拆成 12 個具體的 task，每個都有明確的完成標準。
為什麼要寫這麼多？
因為 AI 的「常識」跟人類不一樣。
人類工程師看到「MES 系統」會自動聯想到：工廠環境、平板操作、大按鈕、簡潔介面。他可能做過類似的系統，或至少看過。
AI 看到「MES 系統」只會聯想到訓練資料裡出現過的相關代碼。而訓練資料裡大部分的 React 範例都是桌面端的——因為桌面端的教學文章和開源專案遠比平板端多。
所以你不能假設 AI 有「領域常識」。你要把每一個隱含的假設都寫出來：
❌「參考 work-execution 模組」→ AI 不會自己去讀
✅「UI 採用 Context + Header/Content/Footer 三段式佈局，Header 放操作控制，Content 放工單列表，Footer 放動作按鈕」
❌「按鈕要大一點」→ 多大？
✅「Footer 按鈕高度 48px，文字 18px，間距 12px，全寬排列」
❌「暫停有兩種」→ 哪兩種？差別在哪？
✅「暫停展開子選單：除外（Exception）和凍結（Freeze）。除外 = 短暫離開可快速恢復；凍結 = 長時間擱置，自動退回待開工畫面，需手動解凍」
寫詳細 Issue 的 ROI
你可能會想：花兩小時寫 Issue，不如自己寫 code 算了。
但事情不是這樣算的：
- 這個 Issue 寫完之後，AI 產出的第一版就有 80% 以上的正確率
- Code review 只需要處理細節問題（i18n 漏掉、元件選錯），不用整個重寫
- 同樣的 Issue 格式可以複製到其他類似頁面，邊際成本遞減
- Issue 本身就是文件，新人（人類或 AI）看了就知道這個頁面在幹嘛
對比之下，如果 Issue 寫得模糊：
- AI 產出的第一版可能只有 30% 能用
- Code review 變成「幾乎重寫」等級的修改
- 來來回回三五輪，時間反而更長
- 而且每次修改都要重新解釋上下文
flowchart TD
A[模糊 Issue] --> B[AI 產出 v1]
B --> C[Review: 大量問題]
C --> D[來回修改 x3~5 輪]
D --> E[最終成品]
F[詳細 Issue] --> G[AI 產出 v1]
G --> H[Review: 細節微調]
H --> E
怎麼寫出好的 AI Issue
整理幾個原則：
講「為什麼」不只講「做什麼」
告訴 AI 這個功能的使用情境。「平板操作、工廠環境、操作員可能戴手套」這些資訊會影響 UI 設計決策。AI 不是不會推理，它只是缺少推理的前提。
貼程式碼比寫文字有效
與其寫「用 FormFullModal 元件」，不如直接貼一段範例 code 展示怎麼用。AI 對程式碼的理解比自然語言精確得多。
狀態機要畫清楚
任何涉及狀態轉換的功能，把所有合法的轉換路徑列出來。AI 最容易漏掉的就是邊界狀態（比如「凍結中能不能按完成？」）。
元件選型要明確指定
你的專案裡如果有封裝好的共用元件，一定要在 Issue 裡指名。AI 不會知道你有 FormFullModal 和 InfoFullModal 的區別，它只會用 antd 的原生 Modal。
拆成可驗證的 task
不要寫「完成前端介面」，要拆成「建立 Context Provider」「實作 Header 元件」「實作 Footer 狀態邏輯」⋯⋯每個 task 都有明確的完成標準。這樣 AI 做完一個就能驗一個，不用等全部做完才發現第一步就錯了。
一個意外的收穫
這個流程做下來，我發現一件事：寫給 AI 的 Issue，人類讀起來也更清楚。
以前寫給團隊的 Issue，很多細節是靠口頭溝通補的。現在被迫把所有假設都寫出來之後，反而減少了溝通成本。新進的工程師看 Issue 就能理解全貌，不用到處問人。
某種程度上，AI 逼我變成了一個更好的 PM。
結語
給 AI 寫 Issue 的黃金法則：如果你覺得「這應該不用特別說明」，那你就一定要說明。
AI 沒有你的領域經驗、沒有你的團隊脈絡、沒有你上週開會時聽到的那段討論。它有的只有你寫在 Issue 裡的文字。
20K 字的 Issue 看起來很誇張，但比起來回修改五輪的 code review，它其實是更省時間的選擇。而且這些文字不會浪費——它們就是你的技術文件。
下次開 Issue 的時候，試試看把字數寫到自己覺得「太囉唆了吧」的程度。對 AI 來說，那個程度剛剛好。