前幾天每次完成修改，都會要求 Codex 執行專案可用的測試與 build，有些 Prompt 也提到了 lint。

但只靠 Prompt 提醒仍然可能漏掉其中一步，而且目前 Issue Tracker 實際上沒有 lint 指令。今天先從 repository 的真實設定出發，把已經存在的品質檢查整合成一個固定入口。

先確認目前有哪些指令

打開 package.json，目前有：

npm run dev
npm test
npm run build

其中：

• npm test 使用 Vitest 執行測試
• npm run build 先執行 tsc -b，再執行 Vite build
• tsc -b 已經包含 TypeScript 型別檢查
• 專案目前沒有 lint 或 formatter 設定

這點和 AGENTS.md 的內容一致：不要假設 npm run lint 可以執行。

為什麼今天不直接加入 lint？

要導入 lint，不只是多寫一行 script，還需要選擇工具、規則、套件版本與設定檔，也可能一次產生大量既有程式警告。

這些都是合理的專案工作，但不應該只為了讓文章標題看起來完整，就在沒有討論規則的情況下加入。

所以今天只整合目前已經能證實的檢查：

自動化測試
-> Type Check
-> 正式建置

未來決定 lint 規則後，再把 npm run lint 加入同一個入口。

為什麼需要單一入口？

目前每次都要記得執行兩個命令：

npm test
npm run build

步驟不多，但人和 Codex 都可能只執行其中一個。

如果建立統一指令：

npm run check

本機開發、Codex 任務和明天的 GitHub Actions 就能使用相同入口，不需要各自維護一套檢查流程。

今天使用的 Prompt

我會在 Issue Tracker repository 開啟新的 Codex 任務，輸入：

請替目前 Issue Tracker 建立一個本機與 CI 都能共用的品質檢查入口。

請先閱讀：
- package.json
- TypeScript 與 Vite 設定
- 現有測試設定
- README.md
- AGENTS.md

先確認目前真正存在的測試、Type Check、build、lint 與 formatter 指令。
不要假設不存在的工具。

請完成：
1. 在 package.json 新增 `npm run check`
2. `check` 依序執行完整測試與現有 build
3. 確認現有 build 中的 `tsc -b` 已涵蓋 Type Check
4. 不新增 lint 或 formatter 套件；在回報中明確說明目前未涵蓋 lint
5. 更新 README，將 `npm run check` 說明為提交前的完整本機檢查
6. 更新 AGENTS.md，要求完成功能後執行 `npm run check`
7. 實際執行 `npm run check`

限制：
- 不修改產品功能與測試內容
- 不新增、移除或升級任何套件
- 不改變現有 `test` 與 `build` 指令的行為
- 不建立目前不存在的 lint 或 formatter 設定
- 只修改 package.json、README.md 與 AGENTS.md；若需要其他檔案，先說明原因

完成後請回報：
- 修改了哪些檔案
- `check` 實際依序執行哪些命令
- 測試、Type Check 與 build 結果
- 哪些品質檢查目前仍未包含
- 目前 Git 狀態

這個任務不需要安裝套件，所以 package-lock.json 理論上也不應該改變。如果 lockfile 出現在 diff，要先確認原因。

這段 prompt 的回覆和執行

&& 為什麼重要？

check 可以用 && 串接現有指令，例如概念上：

{
  "scripts": {
    "check": "npm test && npm run build"
  }
}

前一個命令成功後，才會執行下一個命令。

如果測試失敗，整個 check 會以失敗結束，也不會繼續假裝所有檢查都已完成。GitHub Actions 明天也能根據這個 exit code 判斷 workflow 應該顯示紅燈或綠燈。

為什麼 build 也算 Type Check？

這個專案目前的 build 不是只有產生靜態檔案，而是：

tsc -b
-> vite build

TypeScript 檢查失敗時，Vite build 不會繼續執行，因此 npm run check 同時涵蓋測試、型別檢查與正式建置。

未來如果希望 Type Check 能單獨執行，可以再加入 typecheck script；但今天沒有必要為相同命令建立重複入口。

README 和 AGENTS.md 都要更新嗎？

要，因為兩份文件的讀者與用途不同。

• README 告訴開發者提交前可以執行 npm run check
• AGENTS.md 告訴 Codex 任務完成前應執行同一個指令

如果只修改 package.json，指令雖然存在，使用者與 Codex 卻不一定知道什麼時候要使用。

文件也不能宣稱 check 包含 lint。自動化入口做了什麼，應該和實際 script 保持一致。

如何驗證新的 check 指令？

Codex 完成後，我會確認：

1. package.json 只新增預期的 script
2. npm run check 真的執行測試
3. 測試通過後會接著執行 Type Check 與 build
4. 指令最後回傳成功狀態
5. README 與 AGENTS.md 的描述和實際行為一致
6. package-lock.json、產品程式與測試沒有改變

不能只分別執行原有命令，還要實際執行一次新入口，證明串接方式正確。

失敗時不要只看最後一行

如果 npm run check 失敗，要先確認是哪一個階段：

• Vitest 測試失敗
• TypeScript 型別檢查失敗
• Vite build 失敗

Codex 的完成摘要也應該明確回報失敗命令與原因，不能把「測試通過但 build 失敗」寫成驗證完成。

單一入口的目的不是隱藏細節，而是讓所有檢查都從同一處啟動；發生錯誤時仍然要回到對應輸出調查。

這是我的 repo，在裡面的 commit 找到 "chore: add unified project check command" 就是這篇文章寫完時的狀態。

今日小結

今天根據現有 package.json，把 Vitest 測試、TypeScript 檢查與 Vite build 整合成 npm run check。