Day 28: 避坑指南：打造 AI 工作流最常踩的 5 個坑點與解決方案 (Five Pitfalls in AI Workflows)

本日核心價值 (Core Focus): 把前 27 天最常讓工作流失效的五個坑寫成可執行清單：非結構化輸出、沒有驗證／Sandbox、整庫當 Context、盲目執行 LLM 產生的 SQL／shell、以及 Prompt 沒有 eval。每個坑都對回本系列已出現過的解法。

概念說明與實戰情境 (Overview)
AI 工作流很少死在「模型不夠聰明」，而是死在輸出無法解析、改碼沒人跑、Context 被噪音填滿、生成的 SQL 直接打進正式庫，或 Prompt 改了卻沒有回歸。這五件事各自在 Day 03、05、02、10、16 出現過完整做法；本日改成對照表：症狀、修法、四行檢查清單。目的不是再教一次工具，而是讓團隊在 Code Review 時能用同一套語言擋下「看起來很自動化、實際上不可重現」的流程。

關鍵操作與範例 (Implementation & Example)

先看五坑與系列天數的對應，再逐項拆症狀與修法。

坑 1：非結構化輸出

症狀： ChatGPT 回「大致如下」加一段 Markdown，偶爾夾註解或尾隨解釋；程式用字串切 JSON，一週壞三次。Function Calling 的參數有時缺欄、有時多一個自然語言欄位。

修法： 契約先行。JSON Schema 或嚴格 Structured Output；解析失敗當錯誤，不要「盡力從散文裡撈」。Day 03 的原則不變：能被機器讀的輸出才進 Pipeline。

四行檢查清單：

• 是否有 schema（必填欄、型別、enum）？
• 解析失敗是否有明確 error，而不是 regex 補救？
• 模型是否被禁止在 JSON 外加說明文字？
• 契約變更是否有相容測試（舊 payload 仍能過）？

坑 2：沒有驗證、沒有 Sandbox

症狀： Agent 直接在開發者機器改檔、裝套件、連外網；PR 描述寫「AI 已測過」，CI 卻是第一次跑。失敗時無法重現，因為環境與權限每次不同。

修法： Codex 預設走 Sandbox（例如 workspace-write），測試在隔離環境跑；人負責核准出網與高風險指令。Day 05 的重點是「執行與驗證發生在受控範圍」，不是「模型說有跑過」。

四行檢查清單：

• 預設是否拒絕寫出工作區、拒絕任意網路？
• 測試指令是否寫在 AGENTS.md，而不是聊天紀錄？
• 沒有測試證據的 diff 能否合併？
• 需要更高權限時，是否有一次性核准而非關掉防護？

坑 3：把整個 repo 倒進 Context

症狀： 一次貼數萬行、或把無關服務的 log 全塞進去。模型開始引用不存在的檔案，或忽略真正的熱點函式。Token 成本上升，正確率下降（Day 22 的成本問題會一起爆發）。

修法： Day 02 的 Context 設計：目標檔、介面、錯誤訊息、最小重現。其餘用路徑清單與「需要時再讀」。Repo agent（Codex）應自己檢索，而不是由人預先傾倒。

四行檢查清單：

• 這次任務的必備檔是否少於一頁清單？
• 是否寫明「不要假設未提供的檔案存在」？
• 長 log 是否已截成 stack 頂端 + 關鍵 request id？
• 是否能量測這次 Prompt 的 token，而不是無限貼？

坑 4：盲目執行 LLM 產生的 SQL 或 shell

症狀： 「幫我清掉測試資料」得到 DELETE FROM orders;；「幫我看磁碟」得到 rm -rf。Day 10 若省略「先 EXPLAIN、先限 row、先讀副本」，資料庫工作流會從助手變成事故來源。

修法： 生成與執行分離。SQL 預設 EXPLAIN / LIMIT / 交易可回滾；shell 預設 dry-run 與允許清單。正式庫連線不要給模型所在的執行環境。人是執行閘門。

四行檢查清單：

• 產出的 SQL／命令是否先以文字審查，而不是直接 pipe？
• 是否禁止無 WHERE 的 DELETE/UPDATE，並要求先 BEGIN？
• 執行身分是否為最小權限、非 superuser、非 production write？
• 是否留下可稽核的命令紀錄與影響列數？

最小護欄示例（審查通過前不要執行模型給的字串）：

public static void AssertReadOnlySql(string sql)
{
    var s = sql.TrimStart();
    if (!s.StartsWith("SELECT", StringComparison.OrdinalIgnoreCase)
        && !s.StartsWith("EXPLAIN", StringComparison.OrdinalIgnoreCase))
        throw new InvalidOperationException("Only SELECT/EXPLAIN allowed in auto-run.");
    if (s.Contains(';') && s.IndexOf(';') != s.Length - 1)
        throw new InvalidOperationException("Multiple statements are not allowed.");
}

坑 5：Prompt 沒有 eval、沒有回歸

症狀： 有人改了系統 Prompt「語氣更專業」，Structured Output 開始缺欄；Self-Correction Loop（Day 16）變成無限改碼，因為沒有定義紅燈何時停。沒有金樣例，就沒有辦法說新版本比較好。

修法： Prompt 當產品：固定 10–30 筆案例（含惡意輸入與空輸入）、每次變更跑同一組、失敗則擋合併。Codex 的自我修復必須有測試作為停止條件，否則只是昂貴的迴圈。

四行檢查清單：

• 是否有版本化的 Prompt 與金樣例（fixture）？
• 改 Prompt 是否跟改程式一樣走 PR？
• eval 是否涵蓋解析成功、工具參數、拒絕危險指令？
• Agent loop 是否有最大步數與「測試全過才結束」？

把五坑收成進 PR 範本的一小段，比再寫一份規範更有效：

## AI Workflow gates
- [ ] 輸出可被 schema 解析（Day 03）
- [ ] 測試在 Sandbox / CI 跑過（Day 05 / 16）
- [ ] Context 只含任務所需檔案（Day 02）
- [ ] SQL/shell 已經人審且非直接對 production 執行（Day 10）
- [ ] Prompt 變更附 eval 結果（Day 16）

注意事項與常見失敗 (Pitfalls)

• 只把避坑寫在 wiki、不寫進閘門： 沒有 CI 或 PR checklist，五天後會回到貼整庫。修法：把上表五格變成必填。
• 用「我們信任這個模型」跳過 Sandbox： 模型會變、Prompt 會變、套件會變。修法：信任測試與權限邊界，不信任單次對話。
• eval 只有快樂路徑： 漏掉空 JSON、超長輸入、Prompt Injection（Day 21）。修法：金樣例至少含一筆應拒絕的指令。
• SQL 護欄只做字串黑名單： DROP 可被編碼或註解繞過。修法：最小權限帳號 + 只允許連線到非正式庫 + 人工核准。
• Context 過嚴導致模型缺少介面定義： 修法：白名單「public API 檔 + 錯誤」而不是「零檔案」。

本日總結 (Takeaways)

• 五個坑對應五個已寫過的工作流，不需要新工具，需要閘門。
• 不能解析的輸出、沒跑過的測試、過大的 Context、未審查的 SQL／shell、未回歸的 Prompt，都不該進主線。
• 檢查清單每項四行，是為了在 PR 上能快速勾選，而不是再寫長文。
• Sandbox 與 eval 是讓 Agent 可停下來的條件；沒有停止條件就沒有工作流。
• 把閘門放進 repo（schema、AGENTS.md、CI、fixture），不要放進私人聊天。

明日預告 (Next)
明天做選型而不是再加一個坑：AI 工具鏈選型指南：ChatGPT vs. Codex vs. Claude vs. Local LLMs 比較。