高效 AI 駕馭術
AI 做完怎麼驗收?Claude Code、Codex 說完成之後的 5 道檢查(2026)
Claude Code、Codex 說做完了,怎麼確認是真的?我給 AI 的完成標準、push 之後的上線確認、截圖規格和 SEO 追蹤做法,附一份可以直接貼進 AGENTS.md 的範本。
Kelvin Wang · · 8 分鐘閱讀
重點整理
- 完成要有證據:跑了哪個指令、輸出是什麼,不接受「應該可以了」。
- push 成功只代表程式碼到了 GitHub;等建置成功、用 curl 在線上頁面找到改動,才算上線。
- 畫面看手機 390×844 和桌機,淺色深色都看;SEO 改動上線後記錄,7、14、28 天回頭看。
- 文章發布、push 到 main、社群貼文,各自要我明確同意。
我把「完成」拆成五個可以檢查的證據:本機測試和建置通過、部署真的成功、線上頁面找得到這次的改動、手機和桌機的截圖沒有跑版、SEO 改動有記錄並在幾週後回頭量。五個都對上了,AI 說的「完成」才算數;要發布的東西,最後還要我自己看過、點頭。不管用 Claude Code 還是 Codex,這套檢查都一樣。
AI 說「完成」為什麼不算數?
AI agent 停下來的時機,是它覺得事情看起來做完了。Claude Code 的官方文件講得很直接:如果沒有東西能告訴它「是不是真的做完」,它只能憑「看起來做完」判斷,結果你就變成那套測試,每個錯都留在那裡等你剛好發現1。Codex 的文件也說,它可以自己跑「改、測、確認」這個循環,前提是它知道「好」長什麼樣子2。
所以驗收要從動工前開始:先給 AI 一個會回報通過或失敗的東西。
- 測試檔或建置指令。結束碼是 0 就過,其他都是沒過。
- 一段比對輸出的指令。例如用
curl抓線上頁面,找這次改的那句話。 - 截圖。給它固定的尺寸和主題,讓它自己看有沒有跑版。
Codex 的文件把「沒告訴 agent 怎麼跑建置和測試」列為新手常見錯誤2;Claude Code 的文件則說,repo 已經有檢查的話,規則檔裡最有用的一行就是跑它的指令1。每個專案的規則檔,我第一個寫的就是測試指令。
想深入 Harness Engineering 是什麼?AI Harness 讓 AI agent 穩定做事的 7 個部分(2026) 驗收是 harness 的第七個部分,前面六個是規則、測試、skill、MCP、記憶和子代理。本機要先跑過哪些檢查?
這個網站的規則檔和我給 AI 的回饋裡寫著兩個指令,AI 改完任何東西都要跑:
npx vitest run:所有測試。裡面包含網站的建置測試、文章版面規則、間距刻度,還有一些「以前出過事,所以寫成測試擋住」的規則。npm run build:完整建置一次。測試全過但建置失敗的情況還是會有,例如某個元件只在建置時才會報錯。
我要的回報格式很簡單:跑了哪個指令、結果幾個通過幾個失敗。只寫「測試都過了」不夠,我要看到指令和數字。失敗了就讀錯誤訊息修掉再跑,不是把那個測試跳過。
規則被違反第二次,我就把它寫成測試。這樣驗收不必靠 AI 記得,也不必靠我記得,每次跑 npx vitest run 都會檢查到。
push 成功了,為什麼還要等部署?
因為 push 成功只代表程式碼到了 GitHub,網站有沒有更新是另一回事。這個網站從 2026 年 9 月 29 日起接上 Cloudflare Workers Builds,push 到 main 就會自動建置、部署3。建置在 Cloudflare 的機器上跑,環境跟我的電腦不一樣,本機過了不代表那邊也會過。
2026 年 11 月 5 日,連續七次 push 裡有五次在 Cloudflare 建置失敗,錯誤是 EMFILE: too many open files:建置工具 Rollup 預設同時開到 1000 個檔案,超過了建置機器的檔案數上限。每次 push 本身都成功,GitHub 上的程式碼也是新的,但網站一直停在舊版,那段時間更新的一則幣安事件頁也就一直沒有上線。
修法是把同時開檔數限制在 64(commit 44ec11e),在本機用 ulimit -Hn 512 重現過,再加一個測試 tests/build-config.test.ts,確保這個設定不會被人改掉。從那天起,我給 AI 的規則多了一條:沒確認上線的 push,不算完成。
每次 push 之後的流程:
- 查建置結果。Workers Builds 接上 GitHub 之後,每次建置都會在 GitHub 留一個 check run4,用
gh api repos/<owner>/<repo>/commits/<sha>/check-runs看,等到它回報成功。 - 建置失敗就看 log、修原因。log 在 Cloudflare 後台的 build history3。不推一個空 commit 「再試一次」,那只是在賭。
- 用 curl 確認線上頁面(下一段)。
- 前三步都對了,才回報已上線。
怎麼確認線上頁面真的更新了?
最直接的方法是抓線上頁面,找這次改的文字:
curl -s https://example.com/zh-hant/blog/<slug>/ | grep -c "這次新增的那句話"
輸出 0 就是沒上線,不管建置狀態寫什麼。有 CDN 快取的網站,找到舊內容時先確認是不是快取還沒更新,再判斷是不是部署有問題。
要登入才看得到的頁面,curl 拿不到內容。這個網站的後台 /app 用一支腳本處理:先產生一個登入狀態,再去抓後台實際載入的 JavaScript 檔,檢查裡面有沒有這次新加的字串(tests/e2e/prod-bundle-check.mjs)。原理一樣:在線上找到一個只有新版才有的東西。
畫面改動要看哪些尺寸?
測試能擋住邏輯錯誤,擋不住「手機上按鈕被擠到看不見」。所以改到畫面的工作,我要 AI 用 Playwright 截圖5,固定四張:
| 截圖 | 尺寸 | 主要看什麼 |
|---|---|---|
| 手機淺色 | 390×844 | 有沒有水平捲動、按鈕點擊區夠不夠大 |
| 手機深色 | 390×844 | 深色主題的文字和背景對比、有沒有寫死的白底 |
| 桌機淺色 | 1280 寬 | 雙欄版面、目錄、表格寬度 |
| 桌機深色 | 1280 寬 | 同上,換深色主題 |
手機的規則出自這個網站的設計規範 DESIGN.md §0.5(手機共通規則)和 §7(改完 UI 之後的檢查清單);桌機 1280 寬是我另外固定要看的尺寸。
截圖之外,有兩件事用數字量,不用眼睛看:
- 不能有水平捲動。390px 寬時,頁面的
document.scrollWidth必須等於視窗寬。 - 點擊區至少 44×44px。圖示看起來可以小,能按的範圍不能小。
深淺色要用網站上的切換鈕切,不只靠作業系統的設定。
上線後我會自己打開線上頁面看。AI 截回來的圖,不一定截到我想看的地方。
SEO 改動怎麼驗收?
改標題、改描述這類 SEO 改動,上線當下看不出好壞,要等搜尋資料累積。我的網站接了一套 SEO Monitor,每天收 Google Search Console 和 GA4 的數字;它的規則寫在 repo 的 seo/CLAUDE-SEO.md,不管哪個 AI 工具在這個 repo 工作都會讀到。
- 只在真的上線之後記錄。用
record_change寫下網址、改了什麼類型(標題、描述、內容…)、改之前和改之後、原因,以及上線的那個 commit。 - 一次改一件事。同一頁同時改標題和內容,之後就分不出是哪個造成的變化。
- 7、14、28 天後回頭看。用
get_change_history查那個網址,看點擊、曝光、排名在改動前後各一段時間的差異。 - 多語系一起看。改了中文版標題,要確認英文版和 hreflang 需不需要一起處理。
對一個小網站來說,7 天的資料通常太少,多數改動在 7 天時都還看不出結果,所以才要等 14 天、28 天再看。搜尋排名同時受很多事影響,前後的差異只代表時間上的相關,不代表因果,我把它當參考,不當成績單。
哪些事一定要人點頭?
測試、部署、截圖都可以交給 AI 自己跑。下面這幾件,不管檢查做得多完整,都要等我明確同意:
- 網站文章發布。每一篇文章我都自己讀過,決定要不要發。AI 可以寫稿、跑測試、跑建置,然後停下來把結果給我看。
- commit、push 到
main。這個網站 push 就會部署,所以 push 等於發布。「寫一篇文章」的同意不包含「把它發出去」。 - 手動部署。AI 不自己跑部署指令,部署走 push 後的自動建置。
- Threads 和 X 貼文。要另外問,而且要把確切的貼文文字給我看。我說「可以發了」,指的是網站文章,不包含社群。
會這樣分,是因為網站文章改錯了可以再改,社群貼文是用我的名字直接對讀者說話,發出去就收不回來。
程式碼改動走 PR,我在手機上看 diff 再決定要不要合併。
想深入 2026 手機怎麼用 Claude Code 改程式、開 PR?Remote Control + GitHub App 從改到合併的完整流程 AI 開分支、跑測試、開 PR,我在手機上看 diff 再合併。怎麼把驗收標準寫進 AGENTS.md 或 CLAUDE.md?
驗收標準寫在規則檔裡,AI 每次開工就讀得到,不用每次在對話裡重講。Codex 讀 AGENTS.md,Claude Code 讀 CLAUDE.md,我讓兩邊讀同一份,做法在 CLAUDE.md、AGENTS.md 怎麼寫。可以直接改的範本:
## 完成的標準
- 改完跑 `npx vitest run` 和 `npm run build`,回報指令和通過/失敗數。
- 改到畫面:用 Playwright 截手機 390×844 和桌機 1280 寬,淺色深色各一張。
- push 之後等部署成功,再用 curl 在線上頁面找到這次的改動,才回報已上線。
- 部署失敗就看 log 修原因,不推空 commit 重試。
## 要先問我
- commit、push 到 main(push 就會部署)。
- 任何社群貼文,附上確切文字。
寫成規則檔是第一步。像「commit 前測試一定要過」這種沒有例外的規則,可以再往下做成 hook 或 CI,讓工具本身擋住,不靠模型自己遵守1。
常見問題
專案沒有測試怎麼辦?
先從建置開始:npm run build 的結束碼就是一個通過或失敗的檢查。接著挑最常出問題的一個地方,請 AI 先寫一個測試把現在的行為鎖住,再開始改。Claude Code 的文件說,repo 已經有測試的話,規則檔裡最有用的一行就是跑測試的指令1。
可以讓 AI 自己檢查自己嗎?
可以,但最好讓沒參與寫程式的那一個來看。Claude Code 的 /code-review 會開一個沒看過對話的子代理審查 diff,不會被寫程式時的推理影響1;Codex 的 /review 可以對照 base branch、未 commit 的改動或某個 commit 審查2。我會再加一層:測試和截圖這種有明確答案的,交給工具;要不要發布,留給我。
每次都要截四張圖會不會太多?
只改文字或後端邏輯的工作不用截圖,測試和線上檢查就夠了。只要動到版面、元件或 CSS,就四張都截:手機和桌機的版面不同,深淺色用的顏色也不同,一種情況沒問題不代表另一種也沒問題。
資料來源