剛開始使用 Codex 時，我常會期待它像一位很能幹的工程師：只要交代一句需求，它就自己找到檔案、完成修改，最後回報可以了。但實際使用一段時間後，會發現「程式改好了」和「整件事完成了」是兩回事。畫面可能還沒有測過，登入流程可能完全沒驗證，甚至連原本的錯誤原因都還沒有找清楚。
這篇文章將整理我目前和 Codex 一起開發時，從接到需求、開始修改，到最後交付的完整流程，與大家一同分享交流。
我會用在 Veggie Finder 專案實際處理過的「行程規劃與手機分享」問題來進行案例說明：使用者直接打開一個分享的行程網址時，按返回不一定回得去上一頁；在手機上，行程底部的分享、匯出和儲存按鈕也可能被螢幕底部遮住。看起來只是幾個畫面問題，實際上同時牽涉瀏覽器歷史、行程資料、手機版面和測試。下面每個步驟，都用這個需求一起走一次。
※ Veggie Finder 是一個幫助使用者尋找蔬食餐廳的 Web App，可以用地圖搜尋、篩選與比較餐廳、查看詳細資訊、AI 推薦餐廳，也能把幾間餐廳排成一趟行程。完整開發背景可以參考：如何用 Google Antigravity 從零打造全端 App？ 5 個步驟完成「Veggie Finder：AI 素食地圖 App」開發與部署 (完整實戰經驗分享)
讀者優惠｜想降低訂閱開銷？透過共享服務平台 Premlogin，你可以和他人分攤 ChatGPT、Claude、Netflix、YouTube Premium 等常用服務的費用。以 ChatGPT 三人共享方案為例，最低只要 US$9.07／月。
輸入優惠碼 ysjblog 還能再享優惠，請參考 Premlogin 官網以獲取最新價格與服務！
兩個貫穿全程的原則
再分享實際的開發流程之前，我目前有兩個從頭到尾都不變的開發原則：主要負責人要對整個任務負責，Hooks 要在工作前後看守必要的安全與完成條件。
主要負責人一路追到最後
主要負責人（主要 agent）會從需求理解、問題調查、工作分配，一路追蹤到整合、驗證和回報。其他協作者（subagent）可以幫忙，但不能因為其中一個人說「這一段完成了」，就直接對使用者宣布整件事完成。
我過去曾嘗試把不同開發階段直接以交接方式接力傳遞給不同 agent 繼續開發，希望減少每個對話需要攜帶的背景資料（Context）；但實際執行後，我發現交接就算設計的再嚴謹以及結構化，仍然很容易遺漏資訊，導致後面的 agent 可能只按照表面結果繼續，最後每個階段都完成了，整體方向卻已經偏離我當初的要求。
因此目前改成由一個主要負責人掌握完整背景。只有工作真的能切成互不影響的小塊時，才啟用協作者；而且協作者只拿到完成自己工作所需要的資料，而不載入主要 agent 的 context，也不能自行提交程式、發布到線上，或再找下一個協作者。
Hooks 看守工作前後
Hooks 可以想成工作場所的護欄：它不負責做決定，而是在工作開始、使用工具前後和準備收尾時提醒、檢查，必要時才阻擋危險動作或不完整的完成宣告。
想看這兩個原則和各個工具名稱的對照，可跳到下方的名詞與實際設定總表。
從需求進來，到最後交付的完整過程
我把整個開發流程拆成幾個清楚的關卡，具體而言，先讓 Codex 讀懂專案規則、確認需求和風險，再依序完成調查、規劃、修改、驗證與回報。這套流程的重點不是讓 AI 做更多事，而是避免它把「程式改完」誤報成「整件事完成」。
1. 先確認現況，不急著動手
每次進入專案，主要負責人會先做一次開工檢查，確認：
- 現在在哪個專案和資料夾。
- 目前有哪些未完成的修改。
- 有沒有規格文件、測試或錯誤紀錄可以參考。
- 這次需求會碰到哪些檔案和功能。
這不是靠主要負責人每次「記得」才做，而是先執行一段開工檢查（bootstrap）。它會確認是不是 Git 專案、盤點目前的修改、叫出工作開始時的檢查，並找出規格、現況總覽和進行中的變更。多花一點時間，能避免一開始就在錯的地方動手。
接著先讀專案的 AGENTS.md。它就像工作場所的規定，會說明哪些地方不能碰、哪些資料不能提交，以及完成前需要做哪些檢查。
如果專案有 MASTER.md，主要負責人也會在這時候讀，這是整個專案的現況總覽和規格地圖：目前有哪些功能、哪一份規格是現行版本，以及接下來應該去哪裡找更完整的說明。
主要負責人也會讀 lessons.md 或同類型的踩雷紀錄，避免以前犯的錯再犯一次。
接著才判斷這次要不要深入讀 OpenSpec。OpenSpec 可以把它想成「開工前的施工圖」：先把需求、設計、修改範圍和完成條件寫清楚，才開始動手。如果只是改文字或修一個已知的小錯誤，不需要把所有規格資料夾全部讀完；如果需求會改變既有功能，或分流後需要走 OpenSpec，以下是我使用 OpenSpec 的方式：
| 名稱 | 白話意思 | 在流程中的位置 |
|---|---|---|
（檔案）Proposal／Delta Spec／Design／Tasks | OpenSpec 裡的四種文件：為什麼做、行為改什麼、怎麼做、要做哪些事 | 實作前建立，實作中追蹤，收尾時逐項對照 |
（路徑）openspec/specs/ | 目前真的成立的完整功能規格 | 實作、驗證和下一次開工時的現況依據 |
（路徑）openspec/changes/ | 正在提議或進行中的變更 | 放這次變更的規劃和任務，讓實作前後都對著同一份施工圖 |
（路徑）openspec/changes/archive/ | 已完成變更的歷史記錄 | 收尾時保留完整 Change，不是刪除或只留一份摘要 |
先確認現況很重要，因為一個專案不可能永遠只有一個對話。每當開啟新的對話時，主要 agent 都要先知道專案目前的狀態：原本的修改做到哪裡、這次是要繼續往下，還是要開始實作新功能。如果搞不清楚狀況就直接修改，很容易讓整個專案越做越亂。
案例情境： 先分清楚「這次是在修正行程分享和手機操作」和「資料夾裡剛好有其他尚未完成的地圖、聊天或餐廳功能」。後者不是這次需求的一部分，就不能因為看到了問題而順手一起整理。
這一步會用到（查看完整 Skill、Hook 和 Prompt 總表）：
- 開工檢查（不是 Skill）｜
codex-project-bootstrap.sh：確認專案位置、Git 修改、工作規則和規格入口，讓主要 agent 不會在錯的專案或不完整的背景下開始工作。 - Hook｜
SessionStart：在新工作開始時載入專案提示與開工提醒。 - 文件｜
AGENTS.md管工作規則，MASTER.md做規格地圖，lessons.md保存過去的踩坑紀錄。
2. 接著判斷這件事需要多嚴謹
主要負責人不會讓每個需求都走同樣厚重的流程，而是先看它的影響範圍：
| 工作類型 | 常見例子 | 主要負責人怎麼做 |
|---|---|---|
| 小修改 | 改文字、修已知的顯示錯誤 | 同一個主要工作者完成修改與基本檢查 |
| 中型功能 | 新增一個完整功能，牽涉多個畫面或資料 | 先寫清楚目標、行為和完成條件 |
| 高風險工作 | 登入、權限、付款、密鑰、刪除資料、正式環境 | 增加安全檢查、獨立驗證，必要時要求使用者確認 |
簡單來說就是出錯的代價越高，交付前就要有越多證據。
案例情境： 這不只是改一個按鈕。它會同時修改行程頁、返回邏輯、手機底部操作列，以及儲存行程後的資料更新方式，所以主要負責人會把它視為中型修改，先寫清楚影響範圍，再補手機版和回歸檢查。
這一步會用（查看完整 Skill、Hook 和 Prompt 總表）：
- Skill｜
phase-gated-task-router：按照修改範圍和風險，判斷這次只需基本檢查，還是要加入規格、安全檢查和獨立驗證。 - Hook｜ OWNER-SPEC-REMINDER：在可能需要規格的工作開始前提醒主要負責人先做分流，不會因為看到提示就自動替工作建立一套規格。
3. 遇到問題時，先找原因再修
如果是錯誤、測試失敗、畫面壞掉或同一個問題反覆出現，AI 應該要先調查：
- 使用者實際看到什麼問題？
- 這個問題能不能穩定重現？
- 從輸入到錯誤，中間經過了哪些地方？
- 真正出錯的是哪個環節？
- 修改後要怎麼證明它真的好了？
案例情境： 按返回沒有反應時，原因可能不是行程頁本身壞掉，而是使用者從分享網址直接進入，瀏覽器根本沒有上一頁可以回去；手機按鈕被遮住，也可能是整頁在捲動，而不是按鈕位置單純下移。先把原因分清楚，才知道要修返回備援、頁面容器，還是底部安全距離。
這一步會用到（查看完整 Skill、Hook 和 Prompt 總表）
- Skill｜
root-cause-debugging：先重現問題、追蹤問題經過的路徑，再判斷真正該修改的地方，避免只看到畫面症狀就亂改。 - Hook｜
PreToolUse、PostToolUse：分別在使用工具前後提醒主要 agent 確認操作範圍、消化執行結果，必要時補做檢查。
讀者優惠｜想降低訂閱開銷？透過共享服務平台 Premlogin，你可以和他人分攤 ChatGPT、Claude、Netflix、YouTube Premium 等常用服務的費用。以 ChatGPT 三人共享方案為例，最低只要 US$9.07／月。
輸入優惠碼 ysjblog 還能再享優惠，請參考 Premlogin 官網以獲取最新價格與服務！
4. 功能比較大時，先畫施工圖
如果是新增完整功能，主要負責人會利用前面提到的 OpenSpec 先寫規格文件，再開始改程式。這份文件至少要回答四件事：
- 使用者為什麼需要這個功能？
- 使用者會看到什麼？
- 程式和資料要怎麼配合？
- 完成後要怎麼檢查？
當然，小修正不需要硬做完整規格。工作大小和風險，決定文件要寫到什麼程度。
案例情境： 先把施工圖寫清楚，像是直接打開分享連結時返回要去哪裡、手機版哪些區域可以捲動、底部操作列要避開多少空間，以及新增或修改行程後是否需要重新讀取整份行程資料。如此一來可以避免「新增一個按鈕」做到一半，才發現後面還牽涉資料欄位、權限規則、錯誤畫面和回復方式。
這一步會用到（查看完整 Skill、Hook 和 Prompt 總表）
- Skill｜
openspec：把需求、使用者會看到的行為、修改範圍和完成條件寫成施工圖；spec-review-router則在開始修改前，確認這張施工圖和目前專案對得上。若測試分流判定這次需要測試，tdd-workflow會在實作前先寫好測試情境、測試案例和完成條件；可行時先讓測試失敗，再開始修改。 - Hook｜ OWNER-SPEC-REMINDER、DELTA-CHECK：前者提醒需要規格時先走正確分流，後者在收尾前對照現行規格、變更文件和專案索引，避免新舊文件各自變成一套說法。
5. 用不同角度確認結果
修改完成後，主要負責人會依照需求檢查幾個層次：
- 程式能不能正常建置。
- 基本格式和型別有沒有問題。
- 最短的使用流程能不能跑通。
- 如果是畫面，實際看到的內容和大小是否正確。
- 如果是重要流程，是否需要另一個人只從使用者角度重新操作，以 Black-box QA 的方式驗證，也就是請另一個 agent 在沒有任何跟程式相關的 context，直接請他假裝自己是使用者，以人類使用實際的方法重新走一次流程。
案例情境： 即使改 code 的 agent 自己改考程式碼並回報「手機版修好了」，主要負責人也不能只看這一句話就向我回報完成。缺少必要的畫面或操作證據時，收尾 Hook 會擋住完成宣告；一般提醒型 Hook 則會提醒主要負責人補做檢查，像是實機操作或是截圖。必要時，主要負責人還會安排獨立驗證者重新操作，也就是 Black-box QA。
這一步會用到（查看完整 Skill、Hook 和 Prompt 總表）
- Skill｜
test-depth-router：先判斷這次修改需要哪一層測試；verification-loop：最後重新檢查建置、格式、安全、基本流程和差異；qa-black-box-verification：必要時由另一個驗證者只站在使用者角度重走流程。前面由tdd-workflow先寫好的測試案例，會在這一步拿來對照實際結果。 - Hook｜ OWNER-REMINDER：提醒主要負責人消化 agent 的檢查結果並重跑必要驗證；UI-CHECK、UI-VERIFY-REQUIRED：畫面有變更時提醒實際操作與截圖，缺少必要畫面證據時阻擋完成宣告。
6. 最後才整理版本和交付
檢查都完成，而且可以清楚分開這次的修改後，主要負責人才會建立版本紀錄。只放入這次確認過的檔案，不把使用者原本的半成品一起放進去。此外提交、合併、推送、發布、刪除或對外寫入，對資料造成的影響不同。比較不可逆的動作，要另外得到使用者同意。
最後主要負責人會固定照這個順序向我回報：
- 這次實際完成了什麼。
- 對使用者來說，現在可以做什麼。
- 還有哪些事情沒有驗證，或目前還做不到。
- 下一步是什麼，以及是否需要使用者決定。
案例情境： 本機測試、型別檢查、畫面操作和手機尺寸都通過，和「所有使用情境都已經驗證」是兩件不同的事。這次雖然可以證明行程分享返回和手機操作列的主要情境，但如果還有其他正在實作的功能，例如需要登入的美食足跡頁，仍不能只靠未登入的瀏覽器測試宣稱完全通過；主要負責人只能回報已完成的範圍，不能把局部修正說成整個網站都驗證完成。
這一步會用到（查看完整 Skill、Hook 和 Prompt 總表）
- 前一步的驗證結果｜ 第 5 步已完成實作後、交付前的必要檢查；第 6 步不會固定重複同一套檢查，而是確認這些證據確實對應目前這次修改。若收尾前又修改檔案，或建立版本紀錄後改變了版本，就要重跑受影響的檢查。
- Hook／收尾提醒｜
Stop、SESSION-CHECKLIST：收尾時逐項確認完成證據、尚未驗證的部分和授權界線；UI-VERIFY-REQUIRED 若發現 UI 缺少有效截圖，則不能宣稱畫面修改完成。 - 有走 OpenSpec 時，文件也要收尾：
- 先確認驗證證據是新的。 第 5 步的
verification-loop已經檢查目前版本；如果驗證後又改了檔案，或建立版本紀錄後內容又變了，就要重跑受影響的檢查。 - 確認 Change 可以收尾。 先跑嚴格的規格檢查和作者預檢查，確認 Proposal、Delta Spec、Design、Tasks 都和實作及測試結果對得上，Tasks 也真的完成。
- 把變更正式封存。 使用
openspec archive <change> --yes，把完整 Change 移到openspec/changes/archive/，並把已完成的 Delta 同步進openspec/specs/。對行為變更來說，不能只把資料夾移走，或用跳過規格同步的方式假裝完成。 - 更新
MASTER.md。 把現行規格、還在進行的 Change、限制和延後處理的事項重新對上；它是地圖，不需要把整份規格再複製一次。 - 更新
lessons.md。 只有這次真的發現新的坑、規則漏洞或更好的防呆方式才補記，但一旦補記，就要讓下一次開工能讀到。 - 最後才整理版本和交付。 主要負責人檢查差異範圍，只放入已驗證的檔案；合併、推送、發布或對外寫入仍要另外確認授權。
- 先確認驗證證據是新的。 第 5 步的
專案文件、Skill、Hook的比較
| 名稱 | 白話意思 | 在流程中的位置 |
|---|---|---|
AGENTS.md | 專案工作守則 | 一開始先讀，決定哪些事能做、哪些事不能做 |
MASTER.md | 專案規格地圖 | 索引現行規格、進行中的變更、限制與入口；它是索引，不是第二份完整規格 |
lessons.md | 過去踩坑的紀錄 | 開工前先讀；若這次發現新錯誤或新護欄，收尾時補記 |
| OpenSpec | 把較大的功能變更寫成施工圖的規格流程 | 分流判定需要時才使用，完成後要同步現行規格與歷史 |
| Skill | 某一類工作的說明書 | 需要調查、規劃、測試或驗證時使用 |
| Hook | 自動護欄 | 在工作前後提醒、檢查或阻止危險動作 |
目前實際使用的 Skill、Hook
Hooks
| 時機 | 實際設定 | 它做了什麼 |
|---|---|---|
| 進入或切換專案 | 開工檢查（bootstrap） | 確認目前專案、分支、未完成修改、規格入口和踩坑紀錄；不會擅自清掉原有工作 |
| 開始工作 | SessionStart Hook | 提醒主要負責人讀 AGENTS.md、MASTER.md、lessons.md 和這次相關的規格 |
| 使用工具前 | PreToolUse Hook | 檢查即將執行的動作是否碰到機密、外部寫入、破壞性操作或協作者禁止做的事 |
| 使用工具後 | PostToolUse Hook | 留下檢查結果，並在需要時提醒測試、畫面驗證或清理暫存證據 |
| Commit／Closeout 前 | [HOOK:DELTA-CHECK] | 對帳 active Change、archive、現行規格和 MASTER.md，避免新舊文件各自變成真相 |
| 準備收尾 | Stop＋[CODEX:SESSION-CHECKLIST] | 逐項確認驗證證據、尚未驗證的範圍、授權界線和最後回報內容 |
Skills
| 類型 | 設定名稱 | 作用 |
|---|---|---|
| 分流 | phase-gated-task-router | 判斷工作規模和風險；Registry 以 Owner workflow router 盤點 |
| 找原因 | root-cause-debugging | 先找真正原因再修改 |
| 測試分流 | test-depth-router | 先判斷這次修改需要哪一層測試 |
| 測試準備 | tdd-workflow | 在實作前先寫好測試情境、測試案例和完成條件；可行時先讓測試失敗，再開始修改 |
| 規格 | openspec | 先把需求、行為和設計寫清楚 |
| 安全 | security-review | 遇到登入、密鑰、輸入或敏感資料時檢查風險 |
| 規格審查 | spec-review-router | 實作前確認規格和目前程式對得上 |
| 驗證 | verification-loop | 交付前重新檢查建置、格式、安全和基本流程 |
| 獨立檢查 | qa-black-box-verification | 從使用者角度重新確認功能 |
結語
在我密集使用 AI 的這半年間，我認為 AI 最容易讓人產生錯覺的地方，是它很快就能給出一個看似完整的答案。程式碼改好了、畫面打得開、回覆也寫著「完成」，但這些只代表某些事情發生過，不代表原本的需求已經完整被滿足，或是你明明指教他改 A，但他連 BCD 都給改了。
真正可靠的流程，不是讓 AI 跑越多工具，也不是把每一個決定都交給 AI，而是讓每次工作都留下三個清楚的答案：
- 這次到底要改什麼？哪些事情不在範圍內？
- 用什麼實際證據，知道它真的改對了？
- 還有哪些地方沒有驗證？誰需要知道這個限制？
當這三個問題都能回答時，Codex 才不只是快速修改檔案的工具，而是可以被管理、被檢查的協作者。
讀者優惠｜想降低訂閱開銷？透過共享服務平台 Premlogin，你可以和他人分攤 ChatGPT、Claude、Netflix、YouTube Premium 等常用服務的費用。以 ChatGPT 三人共享方案為例，最低只要 US$9.07／月。
輸入優惠碼 ysjblog 還能再享優惠，請參考 Premlogin 官網以獲取最新價格與服務！
常見問題
Q1：每次改一個小地方，都要跑完整套流程嗎？
不用。改一段文字或修一個已知的小錯誤，通常由同一個主要負責人完成基本檢查即可；只有牽涉多個功能、重要資料或高風險操作時，才需要增加規劃和獨立驗證。
Q2：Codex 說「完成」後，使用者還需要自己檢查嗎？
需要，但不一定要重新看每一行程式。比較有效的做法是確認它提供了哪些證據，再依需求走一次最重要的使用流程；如果是登入、付款或資料權限，更不能只相信文字回報。
Q3：一般人需要記住這些 Skill、Hook 和 Prompt 的名字嗎？
不需要。一般使用者只要知道：先看專案規則、先找原因、修改後要驗證、最後要說清楚限制；英文名稱主要是方便流程維護。