用一句話改整個專案:讓 Codex 讀檔、跨檔修改、自己跑測試

前兩課你把 Codex 裝好、也搞懂了核准模式。但如果你到現在還只把它當成「會聊天的自動補全」——問一句、貼一段程式進去、複製它的回答貼回編輯器——那你根本沒用到它真正值錢的地方。

Codex 這種「跑在終端機、看得到你整個專案」的工具,真正的能力是:你只講目標,它自己去搜尋相關檔案、讀懂脈絡、提出計畫、跨多個檔案一起改、改完自己跑測試驗證,錯了再修到通過。你從「一行一行寫程式的人」變成「講需求、驗收成果的人」。這堂課就是要把這條完整的工作流,用一個真實的重構任務走給你看,讓它變成你每天開發的節奏。

這堂課適合誰適合:已經裝好 Codex CLI、也懂核准模式,想把它從「聊天玩具」升級成「日常改專案主力」的人(本課程屬工程師 / 進階應用專區)。需要基礎:會開終端機、看得懂基本的 git diff、上一課的核准模式觀念。前置課:第 1 課(安裝與第一個任務)、第 2 課(核准模式與 Git 安全網)。

這堂學什麼

Codex 怎麼「讀懂」你的專案:它自己搜尋、開檔、建脈絡,你不用把程式碼一段段貼給它
最穩的工作流節奏:讀 → 計畫 → 改 → 自我驗證 → review,以及為什麼「先讓它講計畫再動手」比一上來就叫它改好用十倍
跨檔修改:用一句話改掉散在整個專案裡的同一件事(統一錯誤格式、換 logger、改 API 命名)
讓它自己跑測試 / 型別檢查,形成「改了就自我驗證」的自我修正迴圈——這是 Codex 最被低估的一招
用 2026 年新的 /review 斜線指令做程式碼審查,比只看 git diff 更快抓到問題
怎麼選模型(gpt-5.5 / gpt-5.4 / gpt-5.4-mini / gpt-5.3-codex-spark)以及「拆小任務」為什麼決定成敗

觀念一:它怎麼「讀懂」你的專案

新手最常犯的錯,是把 Codex 當成網頁聊天視窗:「我把這個檔案貼給你,你幫我改」。這完全誤用了它。Codex 跑在你的專案資料夾裡,它有一雙自己的眼睛——你只要描述目標,它會自己用模糊檔名搜尋、grep 整個專案、開啟相關檔案,把脈絡拼起來。

Codex 讀懂專案的方式:你只講目標,它自己搜尋檔名、grep 關鍵字、開啟相關檔案建立脈絡,不用你一段段貼程式碼

所以正確的用法是直接問目標,把找檔案這件苦工交給它:

> 我想新增一個「匯出 CSV」的功能,先幫我盤點要動到哪些檔案、你打算怎麼做

> 這個專案的 API 錯誤處理寫法不一致,幫我盤點目前總共有幾種寫法、分別在哪

它會先「偵察」——把相關檔案讀過一輪——再回你一份計畫。你也可以主動縮小範圍:在對話框打 @ 會跳出模糊檔名搜尋,選中就把路徑塞進訊息,適合你很確定「就是這幾個檔」時。但多數情況讓它自己找更全面,連你沒想到的關聯檔都會挖出來。

觀念二:最穩的節奏是「讀 → 計畫 → 改 → 驗證 → review」

這是整堂課的骨架,先把這張圖記進腦子:

Codex 編輯工作流五步循環:講目標、它讀檔、提計畫你確認、動手跨檔改、自我驗證後你 review 收工

關鍵在第二步和第三步之間要卡一下:先讓它把計畫講出來、你確認方向對了,再讓它動手。多花三十秒,能省下半小時的災難——AI 對需求的理解偏差,在「計畫」階段修正只要一句話;等它改了十個檔你才發現方向錯,得整包 git restore 重來。

實務上延續上一課的判斷:探索與要計畫用 Read Only(--sandbox read-only,只讀不改),方向對了切到 Auto 讓它動手。這樣「讀 + 計畫」全程零風險。

先計畫、再動手的咒語面對稍大的任務,第一句話結尾加上「先不要動手,列出你的計畫和會改到的檔案清單給我確認」。等你回「OK 照做」它才開改。這一個習慣,是新手和熟手用 Codex 最大的差距。

觀念三:跨檔修改,一次改掉散在整個專案的東西

真實世界的需求很少只改一個檔。「把所有 API 回應的錯誤格式統一」「這個函式改名,所有呼叫它的地方一起改」——這種橫跨數十個檔的機械式修改,是人最容易改漏、改到手軟的,卻正是 Codex 最擅長的。

跨檔修改:一句「統一錯誤格式」的指令,Codex 找出散在多個檔案的相關位置一起改,並列出清單給你 review

> 把所有 API 回應的錯誤格式統一成 { error: string, code: number },
  後端所有回傳錯誤的地方、還有前端接收錯誤的地方,都一起更新

它會把所有相關位置找出來、一次改完,結束時列出「我動了這幾個檔」。你要做的不是自己 grep 找漏,而是看它列出的清單合不合理——這才是該花注意力的地方。

觀念四:讓它自己跑測試,改完自我驗證

這是 Codex 最被低估、也最能拉開差距的一招。多數人改完就自己去手動測,其實你可以直接叫它改完自己跑測試,錯了繼續修到全過:

Codex 自我驗證迴圈:改程式碼 → 跑測試/型別檢查 → 看結果,失敗就回去修,直到全綠才停,它自己閉環

> 修好這個登入逾時的 bug,然後跑 npm test,
  如果有測試失敗就繼續修,直到全部通過再停

它會形成閉環:改 → 跑測試 → 讀結果 → 再修 → 再跑,直到綠燈才回報你。你從「改一次測一次盯一次」的苦工,變成最後只需 review 一份「已自我驗證過會過測試」的成果。注意:這需要你在 Auto 模式(workspace-write),它才有權在專案內跑測試指令。

最有效的一句話幾乎每個改動指令,結尾都可以加上「改完自己跑測試 / 型別檢查(npm test、npm run typecheck),確認通過再停」。這一句會逼它自己抓錯、自己修,大幅減少你來回踢皮球的次數。沒有測試的專案,退而求其次也能叫它「跑一次建置 npm run build 確認沒編譯錯誤」。

觀念五:review 成果——用 /review,不只 git diff

改完務必驗收,別因為它說「完成了」就直接 commit。2026 年的 Codex 除了讓你自己看 git diff,還內建了一個專門的 /review 斜線指令:在互動介面打 /review,它會叫出一個專屬的審查員,讀你選定的 diff(可選未提交的改動、對某個 base 分支、或指定 commit),回給你一份照優先級排好、可直接行動的問題清單——像是多了一個資深同事幫你 code review。

review 兩種方式:git diff 是你自己逐行看原始差異,/review 是 Codex 專屬審查員讀 diff 後回一份優先級問題清單

兩個一起用最保險:

/review          # 叫出審查員,讀改動、回一份優先級問題清單

git diff         # 你自己逐行看它到底動了哪些行(習慣還是要保留)

改得對、審查也沒揪出大問題 → 保留、commit。
改歪了 → 直接跟它說「這裡不對,應該要…」它會修正;或用上一課的 git restore . 一鍵還原重來。

要在腳本 / CI 裡做審查,用非互動的 codex exec review --uncommitted,把審查結果印出來,適合當 commit 前的自動關卡。

觀念六:選對模型,和「拆小」比什麼都重要

Codex CLI 2026 年 7 月現行的模型有這幾個,用 --model(或設在 config.toml)切換,也可以在 TUI 裡用 /model 切:

Codex 模型選擇:gpt-5.5 日常主力複雜任務、gpt-5.4 一般任務、gpt-5.4-mini 輕量快速、gpt-5.3-codex-spark 為 Pro 即時迭代研究預覽

模型	定位	什麼時候用
`gpt-5.5`	官方推薦、預設起手式	複雜重構、跨檔大改、需要規劃與多步推理——多數任務直接用它
`gpt-5.4`	一般能力款	日常一般任務,想省一點額度
`gpt-5.4-mini`	輕量快速	簡單、反應要快的小任務
`gpt-5.3-codex-spark`	ChatGPT Pro 專屬研究預覽	為即時互動迭代優化,只有 Pro 方案看得到

Codex 跟 ChatGPT 訂閱的關係Codex 現在包在所有 ChatGPT 方案裡(連 Free 都有):Free $0、Go $8、Plus $20、Pro 從 $100(20x 版本 $200)/ 月,方案越高、5 小時內能用的訊息額度越多。用 codex login 綁 ChatGPT 帳號就能用,不必另外付錢;要走 API 計費(按 token)也行。所以你大概率不用為 Codex 額外花錢,手上的 ChatGPT 訂閱就含了。

但講真的,選哪個模型的影響,遠不如「你有沒有把任務拆小」。不要把大任務一次全丟給它(「幫我重寫整個後端」)。範圍越聚焦,AI 品質越好。正確做法是拆成小步:先盤點 → 改一塊 → 驗證 → 再下一塊。

大任務拆小對照:左邊「重寫整個後端」範圍太大品質崩,右邊拆成盤點、改一塊、驗證、再下一塊,每步都可控可驗收

手把手實戰:一個真實的重構任務

我們用一個常見情境走完整條工作流:一個 Node 專案的 API 錯誤處理寫法五花八門,要統一成同一種格式,並確認測試全過。找一個已經是 Git 倉庫、工作區乾淨的專案跟著做。

先確認版本與環境

不同版本用字會微調,先對一下:

codex --version    # 這篇對到 0.142.5,你的接近就行

進到互動介面後打 /status,看目前用的是哪個模型、哪個 sandbox。開工前先確保工作區乾淨(上一課的鐵律):

git status         # 確認沒有一堆未提交的改動混在一起

用 Read Only 讓它先偵察、給計畫

先別讓它動手。用唯讀模式讓它讀懂現況、盤點問題:

codex --sandbox read-only

然後丟需求,並要求它只給計畫:

這個專案的 API 錯誤回應格式不一致,我想統一成 { error: string, code: number }。
先幫我盤點目前有幾種寫法、分別在哪些檔,然後列出你的修改計畫和會動到的檔案清單。
先不要動手。

它會偵察一輪,回你「目前有 3 種寫法,分別在 A、B、C…,我打算這樣改…」。這一步零風險,而且幫你把範圍看清楚。

確認方向,切到 Auto 讓它動手

計畫看起來對,不用重開。直接在對話框用 /permissions 切到 Auto(對應 --sandbox workspace-write --ask-for-approval on-request),然後放行:

計畫 OK,照這個計畫改。所有相關的後端回傳處和前端接收處都要一起更新。
改完自己跑 npm test,如果有測試失敗就繼續修到全部通過再停。

現在它會在專案資料夾內自己改檔、跑測試。過程中若需要越界(例如 npm install 要連網),它會停下來問你——這時你看清楚再放行。

盯它的自我驗證迴圈

它會邊改邊跑測試:你會看到它跑 npm test、某幾個測試紅了、它回去修、再跑一次。這就是自我修正迴圈在運作,你不用每次插手,讓它跑完閉環。若它卡在同一個測試修不動(三四輪還紅),再介入給提示,別放它無限打轉。

用 /review + git diff 雙重驗收

它回報「全部通過」後,先叫審查員看一遍:

/review

讀它給的優先級清單,有沒有它自己沒注意到的問題(漏改、格式不一致、順手動到不該動的東西)。接著自己也掃一遍原始差異:

git diff

滿意就 commit;哪裡不對就跟它說「這個檔的第 N 處不該改,還原它」,或直接 git restore <檔> 局部還原再讓它重跑那一塊。

需要接續 / 自動化時,用 exec 與 resume

過了一天想接續,用 codex resume --last(互動)接回最近的 session,不用重講脈絡;想從歷史節點分岔出新方向,用 codex fork。要塞進腳本(跑完就結束、沒人按 Enter),用非互動的 codex exec——它本來就不會停下來問你核准,所以 --sandbox 是你唯一的防線,要設好:

codex exec --sandbox workspace-write \
  "把所有 console.log 換成專案的 logger,改完跑 npm test 確認沒壞"

想接續前一個非互動任務,用 codex exec resume --last "把漏掉的檔也改了"。

常見坑

坑 1:一上來就叫它「重寫整個 X」,結果改得又慢又亂

這是最普遍的坑。範圍太大時,AI 抓不住重點、東漏西漏,甚至順手動壞無關的地方。解法:拆小、分步。 先用 Read Only 讓它盤點、切成幾個小任務,一次只做一塊、做完驗證再下一塊。「先盤點 → 改一塊 → 驗證 → 再下一塊」永遠比「一句話重寫全部」品質高。

坑 2:它說「測試都過了」,你一跑卻是紅的

有時它在自己的沙盒裡跑過了,但你環境不同、或它根本沒真的跑到那個測試指令。看到它宣稱通過,自己一定要再跑一次驗證:

Tests:       3 failed, 27 passed, 30 total

看到這種輸出,把失敗的測試名稱和錯誤訊息原封不動貼回去:「這幾個測試在我這邊還是紅的,錯誤是 XXX,幫我修到真的過」。以你機器上實際跑出來的綠燈為準,別接受口頭保證。

坑 3:它卡在同一個測試,修了好幾輪還是紅的

自我修正迴圈不是萬能。有時它會在同一個錯誤上鬼打牆,改了 A 壞了 B、改回 B 又壞 A。看到它第三、四輪還在同一個測試打轉,停下來介入——通常是它誤解了需求。給它更多脈絡(「這個測試期待的行為是…因為…」),或先 git restore 回到動手前重講一次。放它無限打轉只會燒你的額度。

坑 4:改完想 review,卻看到滿滿一大包 diff 分不清哪些是這次改的

git diff 顯示上百行,混著你之前沒 commit 的手動改動

九成是你動手前沒先 commit(上一課的鐵律)。Codex 的改動跟你之前殘留的未提交改動混在一起,git diff 一片汪洋根本 review 不動。解法:每次放手讓 Codex 改之前,先 git status 確認乾淨、或 git commit 一次當存檔點。 這樣改完的 git diff 就是純粹這次的改動,清清楚楚。

坑 5:codex exec 在腳本裡直接報錯或什麼都沒做

codex exec 是非互動模式,不會停下來等你核准(所以它不像互動模式那樣會卡住問你),但常見兩種失敗。一是不在 Git 倉庫裡跑,直接被擋:

Not inside a trusted directory and --skip-git-repo-check was not specified.

解法是先 git init 或加 --skip-git-repo-check。二是它要動的東西超出 --sandbox 範圍(例如要寫專案外的檔),它會做不動或報權限不足——用 --add-dir <路徑> 開放額外可寫目錄,別直接跳 danger-full-access。想把結果撈給後續流程,加 -o result.txt(寫最後訊息到檔)或 --json(JSON Lines)。

作業

找一個有測試的 Git 專案,完整走一遍工作流:codex --sandbox read-only 讓它盤點並給計畫 → /permissions 切 Auto → 下一個跨檔修改任務,結尾加「改完自己跑測試通過再停」→ 用 /review + git diff 驗收。全程感受五步循環的節奏。
刻意練「先計畫再動手」:給它一個稍大的任務,第一句先要求「只列計畫和會改的檔案,先不要動手」,確認方向後才放行。對比一下這樣做,跟一上來就叫它改,結果差多少。
體驗自我驗證迴圈:給一個會讓某些測試失敗的改動,加上「跑 npm test,失敗就修到全過」,觀察它怎麼改 → 測 → 再改的閉環。如果它卡住鬼打牆,練習在對的時機介入。
選做:用 codex exec --sandbox workspace-write "..." 把一個明確的小重構寫成一行非互動指令,體驗它跑完就結束,並想想能塞進什麼自動化流程。

下一課預告

走完這堂,你已經會用 Codex 讀檔、跨檔改、自我驗證了。但你大概也發現一件煩事:每次都要跟它重講一遍專案的規矩——用哪個套件管理器、測試指令是什麼、程式碼風格要怎樣、哪些資料夾不要碰。講到嘴痠。第 4 課教你寫 AGENTS.md:一份放在專案根目錄的「給 AI 的說明書」,用 /init 就能生出骨架,讓 Codex 每次自動記住你的技術棧、指令與慣例,不用你再重複交代。把這堂的工作流,升級成「連規矩都不用再講」的順手狀態。