ultraeval:スキル/コードベース評価 → 根拠付き、AI実行可能な修正ドキュメント は何をしますか?
マークダウンがプログラムです。小さな決定論的エンジンが実行を準備し、マルチエージェントワークフローを生成し、根拠付けゲートを強制します。あなた(および分散されたサブエージェント)が調査、判断、作成を行います。すべての発見は対象内の実際の file:line に解決される必要があります。ゲートは幻覚的なものを拒否します。出力は優先順位付けされたバックログと、モデルが red→green→refactor で実装できる修正ごとのTDDカードです。
使用するタイミング
- 「このスキル(またはリポジトリ)を評価/監査/採点する」;「プロダクションレディか/期待に応えているか」
- 「このコードベースをレビューし、修正計画/TDDバックログを提供して」
- 変更後の自身のスキルの回帰テスト、またはサードパーティのスキルを信頼する前の検証
対象外: 簡単な1ファイルのコードレビュー(その場合は単に読めばよい);対象自身のテストスイートの実行(直接実行すべき)。
ループ
init → plan → run(research → test-plan → execute+gates → judge → results) → verify → backlog(TDD) → score → render
すべてはプレーンな node <skill-dir>/scripts/ultraeval.mjs <cmd> 呼び出しです。サブエージェントへの分散は、生成されたワークフローがエンコードする最適化であり、必須要件ではありません。
確認すべき入力
- Target — 評価するスキル/リポジトリへのパス(またはユーザーが既にローカルにクローンしているgit URL)
- Kind —
skillまたはcodebase(自動検出: SKILL.md があれば skill)。--kindで上書き - Category — 例: 「agent skill」、「CLI」、「library」、「web app」、「security tool」。開始ルーブリックを決定
- Mode —
audit(欠陥, デフォルト)・improve(根拠付き改善機会)・deep(両方)。--modeで設定
モードと改善発見
ultraeval は2種類の発見を見つけます。両方とも根拠付けられ、ゲート検証されます:
- 欠陥 (
audit,deep) — 何かが間違っている;各々が実際のfile:lineを引用 - 機会 (
improve,deep) — 根拠付けられた改善の手がかり(内部健全性 および 製品/機能性)、影響 × 工数 で評価。analyze(決定論的ホットスポット/依存関係/チャーン/テストギャップ)→brainstorm(発散的レンズ)→brainstorm --rank(ランク付けされた機会をkind:"opportunity"としてfindings.jsonに統合)で発見。同じゲートが適用される — 機会は実際のコード/メトリクスにアンカーする必要があり、「すべてを書き直せ」という曖昧なものにはならない。references/analysis-playbook.mdを参照。
improve/deep モードでは、plan が生成ワークフローに Analyze および Brainstorm ステージを追加します。
手順
1. 実行を準備する。
node <skill-dir>/scripts/ultraeval.mjs init --target <PATH> --out <RUN> [--kind skill|codebase] [--category "<c>"]
開始次元を含む eval.config.json を書き込みます(references/rubric-library.md 参照)。
2. ワークフロー+サブエージェント契約を生成する。
node <skill-dir>/scripts/ultraeval.mjs plan --run <RUN>
<RUN>/eval.workflow.mjs(絶対エンジンパスとターゲットパスが埋め込まれた、起動準備完了のマルチエージェントワークフロー)、<RUN>/agents/*.md(ディスパッチ契約)、TEST-PLAN.template.md、dimensions.json、findings.schema.json を出力します。
3. 評価を実行する。 生成されたワークフローをハーネスのWorkflowツールで起動します:
Workflow({ scriptPath: "<RUN>/eval.workflow.mjs" })。これは Research → TestPlan → Execute → Findings → Gate → Judge → Results をパイプライン化し、エンジンゲートを自己呼び出しします。ワークフローハーネスがない場合は、各ステージを手動で実行します: 各 agents/<stage>.md を読み、契約に従ってサブエージェントをディスパッチします。references/orchestration.md を参照。すべてのサブエージェントは絶対パスの <skill-dir>/scripts/ultraeval.mjs を取得します — これには独自のカレントワーキングディレクトリがあり、相対パスを解決できません(plan は既に絶対パスをワークフローに埋め込んでいます)。
4. すべての発見を根拠付ける。 結果を <RUN>/findings.json に統合します(スキーマ: references/gate-contract.md)。各発見は evidence[].ref として対象内の path:line または生成されたログ内の run:relpath#Lnn を引用します。次に:
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN>
終了コード0になるまで findings.json を修正します — 根拠のない発見を修復または削除し、ゲートを弱めないでください。
5. 検証(敵対的出口ゲート)。
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> # VERIFY.todo.json を書き込む
# 各評決を記入: supported | partial | refuted | unsupported (懐疑的サブエージェントを使用; --shards N --shard i で並列化)
node <skill-dir>/scripts/ultraeval.mjs verify --run <RUN> --apply <verdicts.json>
node <skill-dir>/scripts/ultraeval.mjs check --run <RUN> --semantic --require-verify # 出口ゲート — これが通過するまでは提示しない
refuted な発見は dismissed に設定する必要があります。supported/partial な発見は生き残ります。
6. 修復 — 成果物。
node <skill-dir>/scripts/ultraeval.mjs backlog --run <RUN> --tdd
BACKLOG.json(下流エージェントが実行可能な、機械可読で優先順位順のタスクリスト)、REMEDIATION.md、および確認された発見ごとに1つの fixes/FIX-*.md TDDカード を出力します — 各カードにはREDの失敗テストファースト仕様、GREEN変更、VERIFYコマンドが含まれます。references/tdd-remediation.md を参照。
7. スコアリング+レンダリング+提示。
node <skill-dir>/scripts/ultraeval.mjs score --run <RUN> # judges.jsonl + dimensions -> scorecard.json (0-100 + meets-expectations)
node <skill-dir>/scripts/ultraeval.mjs render --run <RUN> # index.html + index.md ダッシュボード(評決を表示)
score は審査員パネルの judges.jsonl と設定の次元を加重評決に集約します。アクティブなP0発見(またはany judgeのno投票、またはスコアが基準を下回る)があると、meets-expectations はfalseに制限されます。評決、P0/P1バックログの見出し、および修正エージェントが消費すべきパス(RESULTS.md、BACKLOG.json、fixes/)を提示します。
CLI全体の終了コード: 0 OK / ゲート通過 · 1 ゲート失敗(check/verify) · 2 使用法または実行時エラー。
8. (オプション) 修正を実行する。 各 fixes/FIX-*.md をビルドエージェントに渡してTDDを実装させます — カードは、問題を再導出せずに red→green→refactor を実行できるように記述されています。
根拠付け契約
発見は、その証拠が解決される場合にのみ信頼できます。check は対象内の各 path:line を開き、その行が存在し範囲内であることを確認します。古い/捏造された行はハード障害です。verify は次に、引用されたコンテンツが実際に主張を支持しているかどうかを懐疑的エージェントに尋ねます。この二層ゲート(構造的+意味的)が要点です。完全な文法と合格/不合格ルールは references/gate-contract.md にあります。
方法とルーブリック
references/eval-playbook.md— research→test-plan→execute→judge→results の方法、および次元ごとにスコアリングされたルーブリックの構築方法references/orchestration.md— 生成されたワークフロー、サブエージェントディスパッチ契約、およびファンアウトのための絶対<skill-dir>不変条件references/gate-contract.md—findings.jsonスキーマ、証拠参照文法、およびcheck/verifyの合格/不合格を正確に決定するものreferences/tdd-remediation.md—BACKLOG.jsonの形状とfixes/FIX-*.mdTDDカード形式references/rubric-library.md— ターゲットカテゴリごとの開始次元references/analysis-playbook.md—analyzeシグナル、ブレインストームレンズ、および機会が根拠付けられたままである方法
安全性
- ultraeval は対象を読み取り、
<RUN>以下に書き込むだけです。対象のコードを実行することはありません。executorサブエージェントは対象自身のコマンド(テスト、ゲート)を実行する可能性があります — 信頼できないリポジトリはサンドボックス化してください。 clean --run <RUN>は派生したゲート/レンダリングアーティファクトのみを削除し、成果物は保持します。--allは実行全体を削除します。