如需完整的文件索引,請參閱 llms.txt。在文件頁面的網址末尾加上 .md ,即可取得該頁面的 Markdown 版本。
主要導覽
主題
Jan 22, 2026 Codex

用評估系統化地測試智慧體技能

本指南說明如何測試智慧體技能、為執行結果評分,並據此持續改進技能。

作者: Dominik Kundel, Gabriel Chua

用評估系統化地測試智慧體技能

為 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 執行程式

以下做法就足以起步:

  1. 針對每個提示詞執行 codex exec --json --full-auto "<prompt>"
  2. 將 JSONL 追蹤紀錄儲存到磁碟
  3. 解析追蹤紀錄,對其中的事件執行確定性檢查
// 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 是否依預期方式設定。單靠檢查檔案是否存在或計算指令數量,很難判斷這些要求是否達成。

一個實用的解法是在評估流程中加入由模型協助的第二階段:

  1. 執行建立專案的技能(這會將程式碼寫入磁碟)
  2. 對產生的程式碼庫執行唯讀風格檢查
  3. 要求傳回結構化回應,讓任務執行框架能以一致的方式評分

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 加入結構化的評分步驟,依評分規準可靠地判斷風格和規範是否符合要求。
  • 依實際的失敗案例擴充測試範圍。 每次需要手動修正,都指出了一個值得測試的行為。將它寫成測試,確保技能日後仍能正確處理。