外觀

語言

高效 AI 駕馭術

AI 做完怎麼驗收?Claude Code、Codex 說完成之後的 5 道檢查(2026)

Claude Code、Codex 說做完了,怎麼確認是真的?我給 AI 的完成標準、push 之後的上線確認、截圖規格和 SEO 追蹤做法,附一份可以直接貼進 AGENTS.md 的範本。

Kelvin Wang · · 8 分鐘閱讀

重點整理

  1. 完成要有證據:跑了哪個指令、輸出是什麼,不接受「應該可以了」。
  2. push 成功只代表程式碼到了 GitHub;等建置成功、用 curl 在線上頁面找到改動,才算上線。
  3. 畫面看手機 390×844 和桌機,淺色深色都看;SEO 改動上線後記錄,7、14、28 天回頭看。
  4. 文章發布、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 改完任何東西都要跑:

  1. npx vitest run:所有測試。裡面包含網站的建置測試、文章版面規則、間距刻度,還有一些「以前出過事,所以寫成測試擋住」的規則。
  2. 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 之後的流程:

  1. 查建置結果。Workers Builds 接上 GitHub 之後,每次建置都會在 GitHub 留一個 check run4,用 gh api repos/<owner>/<repo>/commits/<sha>/check-runs 看,等到它回報成功。
  2. 建置失敗就看 log、修原因。log 在 Cloudflare 後台的 build history3。不推一個空 commit 「再試一次」,那只是在賭。
  3. 用 curl 確認線上頁面(下一段)。
  4. 前三步都對了,才回報已上線。

怎麼確認線上頁面真的更新了?

最直接的方法是抓線上頁面,找這次改的文字:

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 工作都會讀到。

  1. 只在真的上線之後記錄。用 record_change 寫下網址、改了什麼類型(標題、描述、內容…)、改之前和改之後、原因,以及上線的那個 commit。
  2. 一次改一件事。同一頁同時改標題和內容,之後就分不出是哪個造成的變化。
  3. 7、14、28 天後回頭看。用 get_change_history 查那個網址,看點擊、曝光、排名在改動前後各一段時間的差異。
  4. 多語系一起看。改了中文版標題,要確認英文版和 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,就四張都截:手機和桌機的版面不同,深淺色用的顏色也不同,一種情況沒問題不代表另一種也沒問題。

資料來源

  1. 1. Best practices for Claude Code · Claude Code Docs · 2026-11-17 查詢
  2. 2. Codex best practices · OpenAI Codex Docs · 2026-11-17 查詢
  3. 3. Builds · Cloudflare Workers Docs · 2026-11-17 查詢
  4. 4. GitHub integration · Cloudflare Workers Docs · 2026-11-17 查詢
  5. 5. Screenshots · Playwright · 2026-11-17 查詢

關於作者

Kelvin Wang

電機工程師,和 AI Agent 做工具,分享工程與投資的實作筆記。

更多關於我