實戰演練:用 Codex 加一個功能、修一個 bug 的完整流程

前四課我們把地基打完了:第 1 課認識 Codex、第 2 課搞懂核准模式、第 3 課練習編輯工作流、第 4 課用 AGENTS.md 把專案規矩寫給它看。但觀念看再多,不真的坐下來改一次專案,手還是不會動。這堂課就是「動真格」——我們挑兩個每個人都會遇到的任務:加一個功能 和 修一個 bug,各走一遍完整流程,把前面學的東西全部串起來。

每一步我都會給你確切該下的指令、該貼的 prompt,以及背後為什麼這樣做。跟著做完一遍,之後你就能把同一套節奏套到自己任何一個專案上。

這堂課適合誰適合:已經裝好 Codex、想真的拿它來改自己專案,但「打開終端機後不知道第一句話該說什麼」的人(本課屬工程師實戰專區)。需要基礎:會用終端機、專案已是 git 倉庫、Node 專案能跑起來。前置課:第 1～4 課,尤其第 2 課(核准/sandbox)與第 4 課(AGENTS.md)。

這堂學什麼

一套可以套用到任何任務的「黃金五步循環」:偵察 → 計畫 → 對齊 → 動手 → 驗證
加功能實戰:從零把一個「深色模式切換」加進現有專案
修 bug 實戰:定位、解釋根因、修正、補測試的完整順序
每一步該用哪個 --sandbox 模式、什麼時候該放手、什麼時候該收緊
用 /review 讓 Codex 自審 diff、用 codex exec 把重複任務自動化、用 codex resume 續接對話
三個新手最常踩的坑,含真實錯誤訊息與解法

觀念:所有任務都是同一個循環

在下任何指令之前,先把這張圖記進腦子。不管是加功能還是修 bug,好的 Codex 工作流永遠是同一個循環:

用 Codex 改專案的黃金五步循環:偵察、計畫、對齊、動手、驗證,不對就回頭重來

新手最容易犯的錯,是打開終端機劈頭就說「幫我加深色模式」然後按 Enter 放它去跑。這樣做十次有八次會歪:它不了解你專案的結構、不知道你的取捨,只能照自己的猜測亂改一通,最後你 review 到崩潰。

正確的節奏是先對齊、再動手:先讓它偵察(讀懂專案)、列出計畫,你確認方向後才放行編輯,改完自己驗證。前面多花兩分鐘對齊,省下的是後面十分鐘的來回拉扯。這一課的兩個實戰,骨架都是這五步。

動手前:選對 sandbox 模式

第 2 課講過核准與 sandbox,這裡快速複習,因為接下來每一步都要用到:

sandbox 決定 Codex 能碰什麼:read-only 只能讀、workspace-write 可改工作目錄、danger-full-access 全開

實務上的分工很單純:偵察和計畫階段用 --sandbox read-only(它只能讀、不能亂動,你可以安心讓它到處看);真的要它改的時候切到 --sandbox workspace-write(能讀寫目前工作目錄、能跑指令,但碰網路或跳出目錄還是會問你)。danger-full-access 除非在信任的 CI 容器裡,平常別用。

在互動介面(直接打 codex 進去那個)裡,你不用重開,隨時用 /permissions 就能在 Read Only / Auto / Full Access 之間切。啟動時想直接指定,就加 --sandbox 或用 -a(--ask-for-approval)控制它「何時該問你」(可選 untrusted、on-request、never)。

實戰一:加一個「深色模式切換」功能

情境:你有一個現成的網站專案,想加一個右上角的深色模式切換按鈕,狀態要記得住(重新整理不會跑掉)。跟著五步走。

偵察 + 計畫:先別動手,要它講清楚

在專案資料夾裡開 Codex,用唯讀模式進去,確保它這階段只看不改:

codex --sandbox read-only

然後把任務描述丟給它,關鍵是明確叫它先別動手:

我想加一個深色模式切換按鈕,放在網站右上角。先別改任何檔案,
先告訴我:你會改哪些檔、用什麼方式實作、有哪些需要我決定的取捨。

它會去讀你的專案結構、找到相關的元件與樣式檔,然後回你一份計畫。這一步之所以用 read-only,是因為你根本還沒要它改,先讓它「讀懂再說」,順便你也確認它有沒有找對地方。

對齊:看計畫、給方向

它列出計畫後,別急著說「好」。看它的取捨對不對,不對就當場修正。這是整個流程 CP 值最高的一步:

方向對,但兩點要改:主題狀態存在 localStorage,不要用 cookie;
按鈕沿用現有的 Button 元件,不要自己刻一個新的。

兩種最常見任務,同一套節奏:加功能與修 bug 都走偵察、對齊、放行、驗證四步

一句話就把它拉回你要的方向。如果一開始就放它去改,這種偏差你得等改完看 diff 才發現,再改一輪——現在花 20 秒就對齊了。

動手:切到可寫模式,放行編輯

方向對了,現在讓它真的動手。在互動介面裡直接 /permissions 切到 Auto(或 workspace-write),然後:

照這個計畫做。改完自己跑 npm run dev 確認能編譯,有錯就自己修到能跑起來。

注意最後那句「改完自己跑 npm run dev」——讓它自己驗證能不能編譯,而不是丟一堆改動給你才發現連跑都跑不起來。Codex 在 workspace-write 下可以直接跑這個指令。

驗證:review、實測、commit

它說做完了,你的工作才開始。三件事:

看 diff:用 /review 讓它先幫你把改動審一遍(下面觀念會細講),或自己 git diff 逐行看。
實際點按鈕測試:打開瀏覽器,點切換、重新整理、看狀態有沒有記住。AI 說「能跑」不等於「符合你要的效果」。
對了就存檔:git commit,順手叫它「幫我寫一句 commit 訊息,說明這次改了什麼」。

關鍵順序偵察 → 計畫 → 對齊 → 動手 → 驗證。先對齊方向再動手,比一上來就改省下大量來回。這個順序你會用一輩子。

實戰二:修一個 bug

情境:使用者回報「購物車數量超過 10 時,總價算錯」。這是最典型的除錯任務,骨架跟加功能一樣,但有一個絕對不能跳的關鍵動作。

描述症狀,給足線索

一樣先 read-only 進去。描述 bug 時,症狀愈具體、線索愈多,它找得愈準:

使用者回報:購物車在商品數量超過 10 時,總價會算錯。
數量 10 以內都正常。幫我找出原因在哪,先別改。

「10 以內正常、超過才錯」這種邊界資訊很值錢,能讓它直接鎖定像是「數量上限判斷」「批發折扣」之類的邏輯,不用大海撈針。

先解釋根因,再修(絕對別跳過)

這是除錯流程的靈魂。找到疑點後,逼它先把根本原因講清楚:

先告訴我根本原因到底是什麼,再動手修。

為什麼這步不能省?因為如果 AI 沒真的搞懂 bug 就急著改,常常是「表面補一下、根因還在」——你以為修好了,換個情境又冒出來。逼它先講清楚根因,是修對的前提。它解釋的邏輯你聽得通,才放它去修。

修正 + 補一個測試

理解對了,切到可寫模式放行,而且要求它補測試:

修好這個問題,並補一個測試蓋住「數量超過 10」這個情況,
然後跑 npm test 到全部通過。

補測試是關鍵:它把這次的 bug「釘」成一條測試,以後誰再改到這段程式、不小心弄壞,測試會立刻紅給你看。這叫回歸測試,是修 bug 該有的標準動作。

確認:diff、跑一次、commit

看 diff 確認它只動了該動的地方(沒有順手改壞別的)、本地跑一次確認測試真的過、然後 commit。修 bug 的 commit 訊息可以請它寫成「fix: 修正購物車數量超過 10 時總價計算錯誤」這種格式。

別跳過「解釋根因」整個修 bug 流程裡,最容易被省略、也最不該省的,就是「先講根本原因」。AI 很會裝懂——它會很有自信地改一版給你,但根因沒抓到的修法,只是把問題推到下一次。花一分鐘讓它解釋,值回票價。

觀念:三個讓你更省力的指令

上面兩個實戰你已經能獨立完成了。再送你三個工具,讓你從「會用」進化到「用得順」:

三個讓你更省力的指令:review 自審 diff、resume 續接對話、model 切換模型

/review(或 codex review):讓 Codex 讀你選的 diff,列出「優先級排序」的問題清單,而且完全不動你的工作區。它可以審未提交的改動、審對某個分支的差異、或審特定 commit。commit 前先跑一遍當自審,常常能抓到你自己漏看的東西。
codex resume --last / codex fork:對話太長開始失焦、或關掉終端機隔天想接著做,不用把脈絡重講一次——codex resume --last 直接續接最近一次的 session(連計畫、核准紀錄都在);想從某個節點分岔出去試不同做法,用 codex fork。
/model(或啟動時 --model):切換模型。2026 年 7 月的預設是 gpt-5.5-codex(綜合最強),ChatGPT Pro 用戶另外有一個 GPT-5.3-Codex-Spark 快速版,適合簡單、要求反應快的任務。

進階:把重複任務交給 codex exec

前面都在互動介面裡來回對話。但有些任務是「一句話丟進去、我要結果、不想陪聊」——這時候用非互動的 codex exec:

互動模式 codex 適合探索對話,非互動 codex exec 一句話直接輸出、可接管線與 CI

codex exec --sandbox workspace-write "把所有測試跑一遍,失敗的自動修到全過"

codex exec 不開介面,把過程印到 stderr、最後結果印到 stdout,所以可以塞進管線、腳本、甚至 CI。幾個常用旗標:-o <檔案> 把最終訊息寫到檔案、--json 輸出機器可讀的 JSON Lines(給程式接)、codex exec resume --last 續接上一次 exec。日常探索用互動模式,重複性、可自動化的雜事丟給 exec。

和你的 ChatGPT 訂閱是同一個帳號Codex 不用另外付費。用 `codex login` 以你的 ChatGPT 帳號登入,額度就吃你的訂閱:ChatGPT Plus(每月 20 美元)已內含 Codex,GPT-5.5 大約每 5 小時 15～80 則本地訊息;Pro(每月 100 美元起)是 Plus 的 5 倍額度。額度用完可以買 credit 續用,或等重置。

常見坑

坑 1:一次要它做太多,diff 大到看不完

你一句「幫我把購物車、結帳、會員頁全部重構一遍」,它真的會全改,然後給你一份三十個檔案的 diff。你根本 review 不動,出錯也不知道是哪一塊。

解法:拆小,一個 commit 只做一件事。把大任務切成「先重構購物車 → commit → 再結帳 → commit」。每一段都小到你能完整看懂、能獨立回退。Codex 也是,任務範圍愈聚焦,它改得愈準。

坑 2:沒對齊就放行,它照自己的理解亂改

跳過「先講計畫」直接放它跑,改完你才發現它用了你不想要的做法(例如你要 localStorage 它用了 cookie),整段白做。

解法:回到黃金五步,動手前一定先看計畫、先要它解釋。修 bug 尤其要它先講根因。這一步花的時間永遠比返工少。

坑 3:被 sandbox 擋住,指令卡住或報權限錯誤

在 read-only 模式下叫它跑 npm install 或改檔案,它會卡住等你核准,或你會看到類似:

error: command failed: operation not permitted in read-only sandbox

這不是 bug,是 sandbox 在保護你。解法:看清楚它想幹嘛——如果這個動作合理(例如它真的需要寫檔),就 /permissions 升到 workspace-write 放行;如果你不確定它為什麼要碰某個東西,那正是該停下來問清楚的時候。別因為嫌麻煩就無腦切 full-access 全開,那等於把第 2 課學的安全網整個拆掉。

新手最常踩的三個坑:一次做太多、沒對齊就放行、被 sandbox 擋住,以及各自的解法

坑 4:它一直修不好,愈修愈亂

同一個 bug 來回改了三四次還是不對,通常是它其實沒抓到根因,在瞎猜。

解法:三招。一、git restore 還原到乾淨狀態,別在錯的基礎上疊加。二、給更多線索:貼上完整的錯誤訊息、重現步驟,或叫它「先加 log 印出中間值,找出真正的問題再修」。三、如果對話已經很長、它開始鬼打牆,codex resume 開個乾淨脈絡、或直接重開 session 把重點重講一次,常常比硬凹有效。

作業

找一個你自己的專案(或隨便 clone 一個小專案),完整走一遍加功能流程:偵察 → 計畫 → 對齊 → 動手 → 驗證,加一個小功能(例如一個「回到頂部」按鈕),全程確保「動手前一定先看過計畫」。
在同一個專案製造或找一個 bug,走一遍修 bug流程,重點練習「先要它解釋根因、再修、再補測試」。感受一下有沒有先講根因,修出來的品質差多少。
commit 之前跑一次 /review,看它抓到什麼你沒注意到的問題。
試一次 codex exec:用一句話叫它「把 README 裡的安裝步驟更新成最新的指令」,體會非互動模式的手感。
挑戰:對話做到一半故意關掉終端機,再用 codex resume --last 接回來,確認脈絡沒斷。

下一課(最後一課)預告

到這裡,你已經能用 Codex 獨立加功能、修 bug 了。但市面上還有 Claude Code 這個同類型、同樣強的工具——到底該用哪個?各自強在哪?什麼情境用哪個更順? 最後一課我們做一場橫向比較,把兩者的模型、價格、工作流、生態差異攤開來講,再整理一份「新手最常踩的坑」總表,幫你選對工具、少走冤枉路,漂亮收尾這門課。