為 Codex 這類智慧體反覆調整技能時,很難判斷技能是真的進步了,還是行為有所改變。一個版本感覺比較快,另一個版本似乎更可靠,卻可能在不知不覺間出現迴歸問題:技能沒有觸發、略過必要步驟,或留下多餘的檔案。
技能本質上是為 LLM 整理的一套提示詞與指示。要持續改進技能,最可靠的做法就是用評估其他 LLM 應用程式提示詞的方式來評估它。
Evals 是 evaluations(評估)的簡稱,用來檢查模型的輸出,以及模型為產生輸出所採取的步驟,是否符合預期。有了評估,就不必憑直覺問「感覺有變好嗎?」,而可以問更具體的問題:
- 智慧體有呼叫技能嗎?
- 它有執行預期的指令嗎?
- 它產生的輸出符合你重視的規範嗎?
具體來說,一次評估的流程是:提示詞 → 記錄一次執行(追蹤紀錄 + 產出檔案)→ 執行少數幾項檢查 → 得到可供日後比較的分數。
實務上,智慧體技能的評估很像輕量的端對端測試:執行智慧體、記錄執行過程,再依據幾項規則為結果評分。
本文以 Codex 示範這套做法。先定義成功條件,再加入確定性檢查,並依評分規準評分,讓每次改進或迴歸都有跡可循。
1. 撰寫技能前,先定義成功條件
在動手撰寫技能之前,先用可衡量的條件寫下怎樣才算「成功」。你可以將檢查項目分成幾類:
- 成果目標: 任務完成了嗎?應用程式能執行嗎?
- 流程目標: Codex 有呼叫技能、使用指定的工具,並遵循預期的步驟嗎?
- 風格目標: 輸出符合你要求的規範嗎?
- 效率目標: 執行過程有沒有白費工夫,例如執行不必要的指令,或耗用過多 Token?
清單宜短,聚焦在一定要通過的檢查。只要涵蓋你最重視的行為,不必一開始就把每項偏好都寫成規則。
例如,本文評估的技能會建立示範應用程式。有些檢查很具體:技能有執行 npm install 嗎?有建立 package.json 嗎?除此之外,本文也會用結構化的風格評分規準來評估專案規範與配置。
搭配這兩類檢查,是為了快速取得有針對性的結果,及早找出具體的迴歸問題,而不必等到最後才得到一個通過或失敗的結論。
2. 建立技能
Codex 技能是一個含有 SKILL.md 檔案的目錄。檔案開頭是 YAML 前置資料(name、description),接著是定義技能行為的 Markdown 指示。目錄中也可以放資源和指令碼。名稱和說明比看起來更重要:Codex 主要依據這兩者判斷 是否 要呼叫技能,以及 何時 將 SKILL.md 的其餘內容載入智慧體的上下文。如果名稱或說明太模糊,或涵蓋的情境太多,技能就無法穩定地在適當時機觸發。
最快的入門方式是使用 Codex 內建的技能建立工具(它本身也是一項技能)。輸入以下指令,就能依照引導建立技能:
$skill-creator
建立工具會詢問技能的用途、應該在什麼情況下觸發,以及要單靠指示運作,還是搭配指令碼(預設建議只使用指示)。若要進一步瞭解如何建立技能,請參閱文件。
技能範例
本文刻意選用一個精簡的範例:建立小型 React 示範應用程式的技能,每次都能依照相同流程產生可預期的結果。
這項技能會:
- 使用 Vite 的 React + TypeScript 範本建立專案骨架
- 使用官方的 Vite 外掛程式設定 Tailwind CSS
- 確保檔案結構精簡且一致
- 明訂「完成條件」,方便判斷執行是否成功
以下是精簡的技能草稿,你可以將它貼到下列任一位置:
.codex/skills/setup-demo-app/SKILL.md(適用於該程式碼庫),或~/.codex/skills/setup-demo-app/SKILL.md(適用於該使用者)。
---
name: setup-demo-app
description: Scaffold a Vite + React + Tailwind demo app with a small, consistent project structure.
---
## 使用時機
需要全新的示範應用程式來快速進行 UI 實驗或重現問題時,使用這項技能。
## 建立目標
使用 Vite 建立採用 TypeScript 的 React 應用程式,並設定 Tailwind。保持專案精簡。
設定完成後的專案結構:
- src/
- main.tsx(程式進入點)
- App.tsx(UI 根元件)
- components/
- Header.tsx
- Card.tsx
- index.css(匯入 Tailwind)
- index.html
- package.json
風格要求:
- 使用 TypeScript 撰寫元件
- 僅使用函式元件,不使用類別元件
- 使用 Tailwind 類別設定樣式,不使用 CSS 模組
- 不引入其他 UI 函式庫
## 步驟
1. 使用 Vite 的 React TS 範本建立專案骨架:
npm create vite@latest demo-app -- --template react-ts
2. 安裝相依套件:
cd demo-app
npm install
3. 使用 Vite 外掛程式安裝並設定 Tailwind。
- npm install tailwindcss @tailwindcss/vite
- 將 Tailwind 外掛程式加入 vite.config.ts
- 將 src/index.css 的內容替換為:
@import "tailwindcss";
4. 實作精簡的 UI:
- Header:顯示應用程式標題和簡短的副標題
- Card:提供可重複使用的卡片容器
- App:顯示 Header 和 2 個 Card 元件,並在卡片中放入暫代文字
## 完成條件
- 執行 npm run dev 能成功啟動開發伺服器
- 專案中有 package.json
- src/components/Header.tsx 和 src/components/Card.tsx 兩個檔案都存在
這個技能範例刻意指定了實作方式。限制條件明確,才有具體的評估依據。
3. 手動觸發技能,找出隱含假設
SKILL.md 裡的 名稱 和 說明 很大程度決定了技能是否會被呼叫。因此,首先要檢查 setup-demo-app 技能是否會在預期的情況下觸發。
在開發初期,先在實際的程式碼庫或臨時目錄中明確啟動技能:可以使用 /skills 斜線指令,或加上 $ 前綴來指定技能。觀察哪些地方出錯,例如技能完全沒有觸發、太容易觸發,或雖然執行了,卻偏離預定步驟。
這個階段先不急著提升速度或打磨細節,而是要找出技能有哪些隱含假設,例如:
-
對觸發條件的假設:「快速建立一個 React 示範應用程式」這類提示詞 應該 呼叫
setup-demo-app,卻沒有觸發。反過來,更籠統的提示詞(「加入 Tailwind 樣式」)卻意外觸發了技能。 -
對環境的假設:技能假設執行目錄是空的,或假設
npm可用,而且是優先選用的套件管理工具。 -
對執行流程的假設:智慧體以為相依套件已經安裝,所以略過
npm install,或在 Vite 專案建立之前就設定 Tailwind。
準備好要重複執行這些案例時,就改用 codex exec。這項指令專為自動化與 CI 設計:執行進度會持續寫入 stderr,只有最終結果會寫入 stdout,因此更容易用指令碼執行、記錄並檢查每個案例。
codex exec 預設在受限的沙盒中執行。如果任務需要寫入檔案,請加上 --full-auto 執行。原則上,只授予完成任務所需的最低權限,尤其是在自動化執行時。
手動執行的基本範例如下:
codex exec --full-auto \
'請使用 $setup-demo-app 技能,在目前的目錄中建立專案。'
第一次動手執行,重點在於找出邊界案例,驗證正確性則是其次。每個手動修正都可以成為日後的評估案例,例如補上遺漏的 npm install、修正 Tailwind 設定,或更精確地描述觸發條件。這樣就能在擴大評估規模前,先用測試確保技能維持預期行為。
4. 用少量有針對性的提示詞及早發現迴歸問題
即使沒有大型基準測試,也能從評估中獲益。針對單一技能,10–20 個提示詞就足以及早發現迴歸問題,並確認改進是否奏效。
先建立一個小型 CSV 檔案,日後在開發或使用過程中遇到實際的失敗案例,再逐步擴充。每一列都應代表一個值得檢查的情境,指出 setup-demo-app 技能 應該 或 不應該 啟動,以及啟動後怎樣才算成功。
例如,evals/setup-demo-app.prompts.csv 的初始內容可以是:
id,should_trigger,prompt
test-01,true,"Create a demo app named `devday-demo` using the $setup-demo-app skill"
test-02,true,"Set up a minimal React demo app with Tailwind for quick UI experiments"
test-03,true,"Create a small demo app to showcase the Responses API"
test-04,false,"Add Tailwind styling to my existing React app"
這些案例各有不同的測試重點:
-
明確呼叫(
test-01)
這個提示詞直接指定技能名稱,用來確認 Codex 能依要求呼叫setup-demo-app,而且修改技能名稱、說明或指示後,仍然可以直接呼叫它。 -
隱含呼叫(
test-02)
這個提示詞描述的 正是 技能適用的情境:建立精簡的 React + Tailwind 示範應用程式,但沒有提到技能名稱。這可以測試SKILL.md裡的名稱和說明是否夠明確,讓 Codex 能自行選用技能。 -
依上下文呼叫(
test-03)
這個提示詞加入了特定領域的上下文(Responses API),但所需的基礎設定相同。這可以檢查技能在含有少許干擾資訊的實際提示詞中是否仍會觸發,以及產生的應用程式是否仍符合預期的結構和規範。 -
陰性對照(
test-04)
這個提示詞不應呼叫setup-demo-app。「在現有應用程式中加入 Tailwind」是常見的相關需求,卻可能意外符合技能的說明(「React + Tailwind 示範應用程式」)。至少加入一個should_trigger=false案例,有助於找出偽陽性:使用者只想修改現有專案,Codex 卻選用了技能,建立全新的專案骨架。
這樣搭配案例各有用意。有些評估用來確認明確呼叫技能時,技能會正確執行;另一些則用來檢查使用者在實際提示詞中完全沒提到技能時,技能能否適時啟動。
遇到判斷失誤、提示詞未能觸發技能,或輸出偏離預期時,就把案例新增為一列。久而久之,這個小型 CSV 檔案就會持續記錄 setup-demo-app 技能必須正確處理的各種情境。
隨著案例累積,這個小型資料集也會持續反映技能必須維持哪些正確行為。
5. 從輕量的確定性評分程式開始
評估的核心做法是使用 codex exec --json,讓任務執行框架能依據 實際的執行過程 評分,而不只是看最終輸出是否正確。
啟用 --json 後,stdout 會以 JSONL 串流輸出結構化事件。這樣就能直接針對你重視的行為撰寫確定性檢查,例如:
- 有執行
npm install嗎? - 有建立
package.json嗎? - 有依預期順序執行指定的指令嗎?
這些檢查刻意保持輕量。即使還沒加入模型評分,也能快速得到容易解釋的結果。
精簡的 Node.js 執行程式
以下做法就足以起步:
- 針對每個提示詞執行
codex exec --json --full-auto "<prompt>" - 將 JSONL 追蹤紀錄儲存到磁碟
- 解析追蹤紀錄,對其中的事件執行確定性檢查
// evals/run-setup-demo-app-evals.mjs
import { spawnSync } from "node:child_process";
import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
import path from "node:path";
function runCodex(prompt: string, outJsonlPath: string) {
const res = spawnSync(
"codex",
[
"exec",
"--json", // REQUIRED: emit structured events
"--sandbox",
"workspace-write", // Allow changes inside the example repository
prompt,
],
{ encoding: "utf8" }
);
if (res.error) throw res.error;
mkdirSync(path.dirname(outJsonlPath), { recursive: true });
// stdout is JSONL when --json is enabled
writeFileSync(outJsonlPath, res.stdout, "utf8");
return { exitCode: res.status ?? 1, stderr: res.stderr };
}
function parseJsonl(jsonlText: string) {
return jsonlText
.split("\n")
.filter(Boolean)
.map((line: string) => JSON.parse(line));
}
// deterministic check: did the agent run `npm install`?
function checkRanNpmInstall(
events: {
type: string;
item?: { type: string; status: string; exit_code: number; command: string };
}[]
) {
return events.some(
(e) =>
e.type === "item.completed" &&
e.item?.type === "command_execution" &&
e.item.status === "completed" &&
e.item.exit_code === 0 &&
typeof e.item?.command === "string" &&
e.item.command.includes("npm install")
);
}
// deterministic check: did `package.json` get created?
function checkPackageJsonExists(projectDir: string) {
return existsSync(path.join(projectDir, "package.json"));
}
// Example single-case run
const projectDir = process.cwd();
const tracePath = path.join(projectDir, "evals", "artifacts", "test-01.jsonl");
const prompt =
"Create a demo app named demo-app using the $setup-demo-app skill";
const { exitCode, stderr } = runCodex(prompt, tracePath);
if (exitCode !== 0) {
throw new Error(`Codex exited with status ${exitCode}: ${stderr}`);
}
const events = parseJsonl(readFileSync(tracePath, "utf8"));
console.log({
ranNpmInstall: checkRanNpmInstall(events),
hasPackageJson: checkPackageJsonExists(path.join(projectDir, "demo-app")),
});這套做法的優點是每項檢查都有確定的結果,也容易除錯。
如果檢查失敗,打開 JSONL 檔案就能看清楚實際發生了什麼事。每次執行指令都會依序記錄為 item.* 事件,因此很容易說明並修正迴歸問題,這正是這個階段的目的。
6. 用 Codex 和評分規準進行質性檢查
確定性檢查可以回答 「基本要求都做到了嗎?」,卻無法回答 「做法符合你的期望嗎?」
對 setup-demo-app 這類技能而言,許多要求都是質性的,例如元件結構、樣式規範,或 Tailwind 是否依預期方式設定。單靠檢查檔案是否存在或計算指令數量,很難判斷這些要求是否達成。
一個實用的解法是在評估流程中加入由模型協助的第二階段:
- 執行建立專案的技能(這會將程式碼寫入磁碟)
- 對產生的程式碼庫執行唯讀風格檢查
- 要求傳回結構化回應,讓任務執行框架能以一致的方式評分
Codex 透過 --output-schema 直接支援這個做法,讓最終回應符合你定義的 JSON 結構描述。
精簡的評分規準結構描述
先定義一個小型結構描述,涵蓋你重視的檢查項目。例如,建立 evals/style-rubric.schema.json:
{
"type": "object",
"properties": {
"overall_pass": { "type": "boolean" },
"score": { "type": "integer", "minimum": 0, "maximum": 100 },
"checks": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": { "type": "string" },
"pass": { "type": "boolean" },
"notes": { "type": "string" }
},
"required": ["id", "pass", "notes"],
"additionalProperties": false
}
}
},
"required": ["overall_pass", "score", "checks"],
"additionalProperties": false
}
這個結構描述提供固定的欄位(overall_pass、score 和各項檢查的結果),方便彙整結果、比對差異,並持續追蹤變化。
風格檢查提示詞
接著再執行一次 codex exec,要求它 只檢查程式碼庫,並輸出符合評分規準的 JSON 回應:
codex exec \
"請依下列要求評估 demo-app 程式碼庫:
- 程式碼庫中有 Vite + React + TypeScript 專案
- 專案透過 @tailwindcss/vite 設定 Tailwind,且 CSS 有匯入 tailwindcss
- src/components 中有 Header.tsx 和 Card.tsx
- 所有元件都是函式元件,使用 Tailwind 工具類別設定樣式,不使用 CSS 模組
請依評分規準評分,以 JSON 格式傳回結果。四項檢查的 ID 依序為 vite、tailwind、structure、style。" \
--output-schema ./evals/style-rubric.schema.json \
-o ./evals/artifacts/test-01.style.json
這時 --output-schema 就能派上用場。它會傳回格式可預期的 JSON 物件,省去解析或比對自由格式文字的麻煩,讓任務執行框架能為多次執行的結果評分。
如果日後將這套評估移到 CI,Codex GitHub Action 支援將 --output-schema 放在 codex-args 中傳入,因此也能要求自動化工作流程產生相同格式的結構化輸出。
7. 隨著技能成熟,擴充評估項目
建立基本的執行與評分流程後,就可以針對技能最重要的面向擴充評估。先從少數項目著手,只有在能更有把握地判斷技能是否正常運作時,才加入更深入的檢查。
例如:
-
指令數量與重複執行: 統計 JSONL 追蹤紀錄中的
command_execution項目,找出智慧體開始陷入迴圈或重複執行指令的迴歸問題。turn.completed事件也會記錄 Token 用量。 -
Token 預算: 追蹤
usage.input_tokens和usage.output_tokens,找出提示詞意外變長的情況,並比較不同版本的效率。 -
建置檢查: 技能執行完畢後,執行
npm run build。實際建置更能反映端對端流程是否正常,也能找出匯入失敗或工具設定錯誤等問題。 -
執行階段的冒煙測試: 執行
npm run dev,再用curl向開發伺服器發出請求。如果已經有輕量的 Playwright 檢查,也可以直接執行。這類檢查能讓你更確定應用程式執行正常,但也需要時間,請視需要採用。 -
程式碼庫整潔度: 確認執行過程沒有產生不需要的檔案,而且
git status --porcelain的輸出為空(或符合明確列出的允許清單)。 -
沙盒與權限的迴歸問題: 確認技能仍能在預定的權限範圍內運作,無須提高權限。開始自動化後,採用最低權限作為預設值尤其重要。
做法始終一致:先用快速檢查釐清技能的行為,只有在能降低風險時,才加入耗時較長、成本較高的檢查。
8. 重點整理
這個小型 setup-demo-app 範例示範了如何驗證「感覺有變好」:執行智慧體、記錄過程,再用幾項檢查評分。有了這套流程,每次調整的效果都更容易確認,迴歸問題也更容易看出來。實作時請掌握以下重點:
- 衡量你重視的行為。 良好的評估能清楚呈現迴歸問題,也能解釋失敗的原因。
- 先訂出可檢查的完成條件。 使用
$skill-creator建立初稿,再逐步寫清楚指示,直到能明確判斷是否成功。 - 依實際行為評估。 使用
codex exec --json擷取 JSONL 紀錄,並針對command_execution事件撰寫確定性檢查。 - 規則難以判斷的部分,交給 Codex。 使用
--output-schema加入結構化的評分步驟,依評分規準可靠地判斷風格和規範是否符合要求。 - 依實際的失敗案例擴充測試範圍。 每次需要手動修正,都指出了一個值得測試的行為。將它寫成測試,確保技能日後仍能正確處理。