codex-evaluation

name	codex-evaluation
description	Codex 評估類 Use Case 技能。涵蓋 eval-driven improvement loop 工作流。觸發條件：當需要使用 Codex 進行持續品質改進、 評分迴圈、LLM-as-judge 評估時啟用。

Evaluation — Codex Use Cases Skill

概述

Evaluation 是 Codex 最核心的設計模式之一 — eval-driven improvement loop。 透過確定性評分腳本與 LLM-as-judge 的組合，Codex 可以自動迭代改進任何可量化的任務。

本分類包含 1 個 use case：

• iterate-on-difficult-problems — 評分驅動的持續改進迴圈

Use Case: Iterate on difficult problems

工作流程

步驟	動作	說明
1	讀取 AGENTS.md	了解專案規範
2	找到評分腳本	確定性 + LLM 評分
3	運行基準評分	記錄初始分數
4	聚焦改進	一次改一個維度
5	重新評分	比較前後差異
6	記錄變更	分數 + 改了什麼
7	視覺檢查	view_image 確認
8	重複 4-7	直到分數 > 90%
9	最終報告	分數、迭代日誌、風險

推薦 Prompt

Role: You are a quality-obsessed engineer running an eval-driven improvement loop.
Context: This workspace has a difficult task with an evaluation script that scores output quality.

Task:
1. Preparation:
   - Read `AGENTS.md` and follow all instructions.
   - Locate the eval script/command (e.g., `python eval.py`, `npm run eval`).
   - Run baseline eval and record initial scores.
   - If no eval exists, create one scoring: correctness (0-100), quality (0-100), completeness (0-100).

2. Iteration Loop (repeat until target met):
   a. Analyze current scores — identify the weakest dimension.
   b. Make ONE focused improvement targeting that dimension.
   c. Re-run eval immediately after the change.
   d. Log to `iteration_log.md`: timestamp, change description, before/after scores.
   e. If output is visual, use `view_image` to inspect.
   f. If score regressed, analyze why before reverting.

3. Convergence Criteria:
   - Overall score > {{target_score}}% (default: 90).
   - LLM average > {{target_score}}%.
   - No single dimension below {{min_dimension_score}}% (default: 75).

Constraints:
- Never stop at the first acceptable result.
- Never revert unless new scores are strictly worse AND artifact quality degraded.
- If stuck at a plateau, try a different approach rather than incremental tweaks.
- Maximum {{max_iterations}} iterations (default: 20).

Output Format:
- `iteration_log.md`: Complete history with scores per iteration.
- `final_report.md`: Best scores, approach summary, remaining risks.
- Final artifacts in `outputs/`.

Self-Verification:
Run eval one final time on the best version.
Confirm all scores meet convergence criteria.

Eval 腳本設計原則

一個好的 eval 腳本應該：

1. 確定性 + LLM 混合評分：

   • 確定性：語法正確、測試通過、檔案大小
   • LLM：可讀性、風格一致性、使用者友善度

2. 多維度評分：

   • 每個維度 0-100 獨立評分
   • 整體分數 = 加權平均
   • 單一維度最低限制防止偏科

3. 可重現：

   • 相同輸入 → 相同分數（確定性部分）
   • LLM 部分使用固定 temperature=0

AGENTS.md 配置

# Iteration Conventions

- Run eval after every meaningful change
- Log scores and rationale in iteration_log.md
- Do not stop at the first passing result
- If eval improves but is still below target, explain the bottleneck
- Visual outputs: always use view_image to inspect before proceeding

Tips & 注意事項

1. 分數不會線性增長: 80% → 90% 比 70% → 80% 難很多
2. Plateau 突破: 如果連續 3 次分數不變，嘗試完全不同的方法
3. LLM-as-judge 偏差: 不同 LLM 的評價標準可能不同，建議固定評審模型
4. 視覺產出: Codex 可以看圖片（view_image），善用這個能力
5. 回退策略: 除非新版本在「數值 + 品質」上都更差，否則不回退

Eval Loop 模式圖

┌─────────────────────────────────────┐
│           Start: Read AGENTS.md     │
│                   ↓                 │
│         Run Baseline Eval           │
│                   ↓                 │
│     ┌──→ Analyze Weakest Dim ──┐    │
│     │          ↓               │    │
│     │   Make ONE Improvement   │    │
│     │          ↓               │    │
│     │      Re-run Eval         │    │
│     │          ↓               │    │
│     │    Log Scores            │    │
│     │          ↓               │    │
│     │   Score > Target?        │    │
│     │    NO ↓     YES ↓        │    │
│     └────────    Final Report  │    │
│                                     │
└─────────────────────────────────────┘

常見問題

Q: 沒有 eval 腳本怎麼辦？

Codex 會自動建立一個基礎 eval 腳本。但建議提前準備好，因為好的 eval 是成功的關鍵。

Q: 目標分數設多少？

• 簡單任務: 95%
• 中等任務: 90%（推薦預設）
• 困難任務: 85%

技術棧速查

技術	用途
Eval scripts	確定性評分
LLM-as-judge	主觀品質評分
view_image	視覺產出檢查
iteration_log.md	迭代記錄