這是我第一個大量使用 AI 完整執行專案的經驗記錄。

龐大的 JSP → Spring Boot 翻新專案。聽起來普通，但有幾個特別麻煩的條件：

  • 沒有 SA 文件
  • 上百支 JSP
  • 邏輯藏在 Oracle PL/SQL 裡
  • 舊系統無法啟動

以前有寫過其他金融業的人事案翻新，照那個人天來計算的話，根本趕不上時程，而且可能還會因為人工閱讀而漏掉重要邏輯。 而若使用以前使用 AI 協作的方式，只是依賴 side chat box，讓 AI 幫我「做了一些事」，但沒有人知道做了什麼、對不對、下次能不能重複，估計也會是一團亂。

第一次嘗試的失敗：AI 做了事，但沒人知道做了什麼

最初的做法，就是直接開一個 AI Agent，請它分析並開發一個功能的 API。

確實有做出成果，但很快發現根本的問題：

  • 我不知道這個功能到底在做什麼
  • 沒有任何紀錄說明翻新邏輯
  • 下一個功能，能保證是一樣的風格與規範嗎？
  • 憑什麼說這個功能是「對的」？

說白了：AI 幫我「做了一些事」，但沒有人知道做了什麼、對不對、下次能不能重複。

我想要的不是「快一點」，是「可以信任的自動化」。

CLAUDE.md

解決方案的第一步，是建立 CLAUDE.md。

這份檔案的定位是：專案開始就要建立、整個過程中持續維護的核心規範檔。把對 AI 的所有要求都寫進去，讓每次對話不用從頭解釋。

裡面寫了什麼

  • 技術選用：Java 17、Spring Boot 3.x、SQL Server——AI 就不會用 Oracle 語法或舊版寫法
  • 環境限制：舊系統無法啟動、此專案不需要 Unit Test
  • 關鍵檔案路徑：新系統、舊系統、DDL、規格書在哪——省去每次告訴 AI 去哪找東西或是大量浪費 token 去大範圍搜尋
  • MCP 工具清單：讓 AI 知道手上有哪些工具
  • 翻新標準化工作流程：每個功能要照什麼步驟走
  • 對話與文件規範：用繁體中文、Swagger 要填中文說明

有了這份合約，AI 一開對話就知道邊界在哪，減少「自由發揮」的空間。

Skill：把技能、先備知識、做法寫成文件

有了 CLAUDE.md 之後，基本行為穩定了，但又浮現另一個問題：工作流程有很多「固定步驟」，每次都要打一大段 prompt，一不小心漏說什麼，AI 就可能跳過某個環節。

解法是定義 Skill——把每個固定步驟需要的技能、知識、做法都寫成結構化文件。

九步工作流

1. 分析舊系統 JSP 與 Java 程式碼
2. 分析舊系統 SQL 與 Oracle DB Function（商業邏輯的核心藏在這裡）
3. 根據分析產出規格書(到可以讓 AI agent 實作的詳細程度)
4. 驗證規格書與舊系統邏輯一致
5. 依規格書開發 Spring Boot 程式碼
6. 比較新舊系統商業邏輯
7. 使用 DB 現有資料進行 API 測試
8. 修正錯誤並重新比對（循環直到通過）
9. 產出前端可用的 API 文件

每一步對應一份 SKILL.md，明確定義這步要做什麼、怎麼做、產出什麼格式、需要的先備知識。

Command：用指令簡化 Skill 的呼叫

定義好 skill 之後，下一步是建立 Command——用 / 開頭的指令來簡化對這些 skill 的呼叫，省掉每次都要詳細説明做法的麻煩。

指令對應 Skill

/analyze MOD-001     ← 呼叫 analyze skill，分析舊系統 JSP，產出規格書
/design  MOD-001     ← 呼叫 design skill，根據規格書設計架構文件
/code    MOD-001     ← 呼叫 code skill，依設計文件產出 Java 程式碼
/validate MOD-001    ← 呼叫 validate skill，驗證邏輯正確性 + 新舊行為比對
/fix     MOD-001     ← 呼叫 fix skill，修正差異（自動循環驗證直到通過）
/testprep MOD-001    ← 呼叫 testprep skill，確認測試資料存在 DB
/apitest  MOD-001    ← 呼叫 apitest skill，執行 API 測試（自動找錯修正直到全過）
/apidoc   MOD-001    ← 呼叫 apidoc skill，產出前端可用的 API 測試文件

我只要說功能代號，不用解釋這步要做什麼，AI 就知道去讀哪份對應的 SKILL.md 並執行。

自動循環：讓 /fix 和 /apitest 自己跑完

這是整個流程最省事的部分。

最初我以為 validate 完就做完了：AI 說「有三個差異」，我說「幫我 fix」，fix 完再說「再 validate 一次」，又發現「還有一個」……每個功能光 fix 就要手動轉四五輪，我一直在當傳話筒。

後來在每個 skill 裡加了「完成條件」與「失敗時下一步是什麼」，才讓循環真正跑起來。

/fix 的循環邏輯

/fix 指令背後定義的 fix skill 串了兩個子技能：

  1. fix-plan-writer skill：讀 validate 輸出，逐條查新舊程式碼取得行號佐證，產出「修改計劃書」——先寫清楚「改什麼、為什麼、改前改後長怎樣」，不直接動手
  2. plan-executor skill：照計劃書逐條執行，改完回報

改完後不停在這裡——自動觸發 /validate 重跑。如果還有差異，再循環：fix-plan-writer → plan-executor → validate，直到通過為止。

關鍵設計：fix-plan-writer skill 被強制要求先查證才能提出修改，每條差異必須附上舊新系統的檔案路徑與行號，確認差異真的存在才寫進計劃書。這樣不會改到沒問題的地方。

/apitest 的循環邏輯

跑所有測試案例 → 標記通過/失敗
  ↓ 發現失敗
讀 application log 最後幾百行（不靠猜測）
  ↓ 判斷根因
程式邏輯問題 → 召喚 fix-plan-writer + plan-executor → 重測
測試資料不夠 → 產出 INSERT SQL 補資料 → 重測
JWT 過期    → 重新產生 token → 重測
  ↓ 全部通過
完成

同一個案例連續失敗超過三次，AI 會停下來告訴我「這個我修不好，需要你介入」——避免無限自旋。

MCP：給 AI 一雙手

直連資料庫

做測試需要知道 DB 裡有什麼資料。最早的做法：

  1. 請 AI 給我一段 SQL
  2. 打開 IDE 手動執行
  3. 截圖/複製結果貼回給 AI
  4. AI 才看得到資料

幾輪下來，一個測試情境可能耗掉半小時。

後來直接建了一個 MCP 工具，讓 AI 直接連 SQL Server，自己下 query、自己看結果。效果立竿見影——以前要人工來回五六輪的資料確認，現在幾秒完成。

引入 OpenAI Codex 做邏輯比對

用 Claude 做新舊系統邏輯比對時，一致性不夠穩定：同樣的程式碼，這次說「沒問題」，下次再問又發現差異。

後來改用 OpenAI Codex 來做 review，一致性明顯提升。雖然每次要等 15–20 分鐘，但結果可信。

同樣建了一個 Codex MCP，結合對應的 review skill，需要新舊比對時就呼叫這個組合。

但我還是非常困惑是什麼原因導致這麼大的差異——是模型本身的理解能力？還是 prompt 的表達方式？還是對話歷史的影響？

如果我不能瞭解其中的原因，那我以後怎麼選擇該使用什麼工具?

讓 Review 結果可信的五個設計

換了工具還不夠，是花時間把 review skill 本身重新整理，Codex 才能正確比對。

1. 強制附上行號佐證

沒有舊、新兩邊的檔案路徑 + 行號，不可以說「一致」。被迫先找到兩個地方的程式碼才能下結論。找不到就說「不確定，需要確認」，不能自己猜。

2. 拆成六個面向，缺一不可

  • API 完整性：新系統 API 數量跟舊系統對上了嗎？
  • Request body：入參欄位、驗證規則一致嗎？
  • Response body：回傳格式、欄位、錯誤碼正確嗎？
  • 商業邏輯：分支條件、計算公式、預設值有沒有改到？
  • 商業流程：步驟順序有沒有被搬動？
  • DB 讀寫：查詢條件、transaction 邊界、INSERT/UPDATE 哪些欄位

3. 明確列出「可以忽略」的差異

舊系統是 JSP + Servlet，新系統是 Spring Boot，架構本來不同。手動 JDBC 事務 vs @Transactional、JSP forward vs REST 回傳格式——這些是正常框架遷移，不算差異。事先說清楚，結果只剩真正有問題的地方。

4. 預先文件化已知的 DB 改動

這個專案有幾張表在遷移過程中同步進行了結構調整——表名更名、主鍵欄位新增，查詢邏輯也要跟著對應調整。這份對照表寫進了 dba-expert skill，review skill 引用它，讓 AI 知道哪些差異是「預期內的改動」，不是 bug，但仍然要驗證新系統的實作是否符合改動後的規格。

5. 品質門檻聲明

每份 review skill 結尾加了一段：「若沒有達到以上標準（雙邊佐證、六個面向都比到），視為無效結論，必須重新執行。」確保 AI 不接受「應該一致」這種說法，只接受「有證據的一致」。

Hook：讓 AI 自己跑完整個流程

(這裡先說一下，這個 hook 不是指 claude 中的 hook，那是用來強制執行流程或指令的機制。這裡的 hook 是指在每個 skill 定義裡加入「完成條件」和「下一步觸發規則」，讓流程能夠自動推進。)

到這個階段，review-fix 循環還是需要我手動切換 command。每次看到 AI 說「review 完了，有 X 個差異」，我說「好，幫我 fix」，fix 完再說「再 review 一次」……

這明明可以讓他自己跑，為什麼需要我在旁邊當傳話筒？

Hook 的做法：在每個 skill 定義裡加入「完成條件」和「下一步觸發規則」：

  • review skill 通過 → 自動觸發下一個 command
  • review skill 有差異 → 自動觸發 /fix command，再觸發 re-review，循環直到通過
  • 全部通過 → 自動推進測試

另外加了 /dev {代號} 入口，讓 AI 自己偵測這個功能目前做到哪裡，告訴我「現在應該做什麼」。我不用記進度，也不用搞清楚現在要呼叫哪個 command。

現在的流程

我說：/dev MOD-007

AI 自動：
  1. 偵測目前進度（有沒有規格書、設計文件、程式碼？）
  2. 告訴我現在做到哪一步
  3. 自動執行下一步的 skill
  4. review/fix 循環自己跑到通過為止
  5. 全部通過後，產出 API 文件

我要做的事，變成：確認每個重要節點的產出是否認同，給個 yes，讓它繼續。

還有什麼不完美

誠實說，不是所有問題都解決了。

  • Codex review 的黑箱感：我選擇信任它，但無法完全驗證它的比對邏輯
  • 偶爾的脫軌：AI 有時候還是會做出規格書裡沒說的事，CLAUDE.md 只能降低頻率，無法完全避免
  • 複雜邏輯的限制：涉及多個 DB Function 的計算，AI 有時轉換得不夠準確。為了維持邏輯一致，有時用了 JdbcTemplate 搭配 Java 字串串接去複製 PL/SQL 行為，雖然邏輯對，但可讀性和維護性很差
  • 流程調整成本：skill 建好之後若要修改，要確保每個呼叫點都跟著調整，有點像維護程式碼本身

結語

這套流程讓我從「不知道 AI 在做什麼」，走到了「AI 幫我執行，我負責確認重要節點」的狀態。

幾個關鍵心得：

  1. CLAUDE.md 是基礎，沒有它，每次 AI 都在亂發揮
  2. Skill 讓流程可重複，把技能和先備知識文件化才能確保一致性
  3. Command 簡化呼叫，用指令代替長串 prompt 才能讓 AI 穩定執行
  4. 強制佐證是 review 品質的關鍵，「應該一致」不算 review
  5. MCP 增強協作能力，讓 AI 真的能自己完成工作
  6. 循環機制把人從傳話筒解放出來，但要設好退出條件，避免無限自旋

這個方向是對的——不是讓 AI 快一點，而是讓 AI 的產出可信、可重複、可驗證。