deterministic-metric-design

dot-skills 決定論的な指標設計のベストプラクティス

決定論的で、計算可能で、証明可能かつ妥当な指標を設計します。エージェントが信頼し、不正に利用することなく最適化できる尺度です。8 つのカテゴリにわたる 44 のルールに従って、曖昧な概念を、採用可能で機械検証できる数値へと変えていきます。概念を定義し、健全な代理指標を用いて計算可能性の限界に向き合い、測定理論に基づかせ、その特性を証明し、決定性を固定し、経験的に検証し、最適化の圧力に耐えられるよう強化して、採用しやすい形にまとめます。

すべてのカテゴリを通じて、一貫した例を取り上げます。動作を保ったままコードベースのサイズを縮小する決定論的な尺度（アプリの動作を変えずにコードを減らすこと）です。理想的な形が証明上、実現不可能であるため、格好のストレステストになります（コルモゴロフ複雑性は計算不可能であり、プログラムの等価性は Rice の定理により決定不能です）。そのため、設計の要点は、保証を証明できる決定論的で扱いやすい代理指標を作ることです。

これは測定設計のレイヤーであり、*-algorithms スキルが適用する（Big-O、NDCG、サイクロマティック複雑度、MoJoFM）ものの、教えることはありません。

適用するタイミング

次のような場合にこのスキルを使用します。

• 新しい指標、スコア、インデックスを設計する場合、または他者が提案した指標の厳密性をレビューする場合
• 合意された尺度がまだない性質を「定量化」「測定」「採点」「ランク付け」するよう求められた場合
• エージェントが最適化する決定論的な目標を構築する場合（例：動作を変えずにコードサイズを縮小する）
• 既存の指標に「違和感がある」場合の監査 — LOC と疑わしいほど強く相関する、実行ごとに数値が変わる、または不正に利用されている
• 研究上のアイデアや数式を、計算可能で再現性があり、採用可能なものにする場合

ワークフロー：定義 → 計算可能にする → 証明 → 検証 → 強化

カテゴリは、カスケードの重大度に応じて並んでいます。上流での誤りは、その下のすべてを損ないます。上から順に進め、この表を使って該当するカテゴリから直接始めることもできます。

状況	開始カテゴリ	最初のルール
曖昧な性質から始める	def-	def-name-the-latent-construct
理想が計算不可能または決定不能ではないかと懸念している	comp-	comp-do-not-define-metric-as-uncomputable-ideal
平均や比率を使えるか確信がない	meas-	meas-declare-the-scale-type
指標の特定の挙動を主張する	prop-	prop-prove-monotonicity
実行ごとに異なる数値が出る	det-	det-pin-iteration-and-tie-break-order
実際に測りたいものを測れているか確信がない	valid-	valid-discriminant-not-just-loc
エージェントに指標を最適化させる	game-	game-hard-block-construct-violating-wins
他の人に指標を公開する	agg-	agg-ship-reference-impl-and-test-vectors

各リファレンスファイルは {category}-{slug}.md という形式で、重要な理由、失敗箇所を注記した誤った例、最小限の修正を示す正しい例、リファレンスが含まれています。誤った例と正しい例は、アプリケーションコードではなく、指標の定義と手順です。対比しているのは、設計が不適切な尺度と、修正後の尺度です。

優先度別ルールカテゴリー

#	カテゴリー	プレフィックス	影響度	ルール
1	構成概念の定義と操作化	def-	CRITICAL	6
2	計算可能性と実行可能性	comp-	CRITICAL	7
3	測定理論の基礎	meas-	HIGH	5
4	指標の性質の証明	prop-	HIGH	6
5	決定性と再現性	det-	HIGH	5
6	構成概念妥当性とキャリブレーション	valid-	MEDIUM-HIGH	6
7	最適化の安全性と不正利用への対策	game-	MEDIUM	5
8	集約、報告、導入	agg-	LOW-MEDIUM	4

優先順位の根拠について詳しくは、references/_sections.md を参照してください。

クイックリファレンス

1. 構成概念の定義と操作化（CRITICAL）

• def-name-the-latent-construct — 数式を書く前に、観測不能な特性に名前を付ける
• def-separate-construct-from-proxy — 構成概念、代理指標、および両者の想定される関係を区別する
• def-write-falsifiable-operational-definition — 数値を導き出す正確な手順を明記する
• def-fix-unit-of-analysis — 分析単位と測定境界を定める
• def-anchor-to-the-decision — 指標が左右する意思決定と行動のしきい値を結び付ける
• def-operationalize-behavior-and-size — フォーマッターによって変わらないよう、「振る舞い」（≈）と「サイズ」を定義する

2. 計算可能性と実行可能性（CRITICAL）

• comp-do-not-define-metric-as-uncomputable-ideal — 指標をコルモゴロフ複雑性として定義しない
• comp-respect-rices-theorem-for-semantic-properties — 決定不能な意味的事実には健全な近似を使う
• comp-choose-a-decidable-observational-equivalence — 決定不能な同値性を、検証可能な ≈ に置き換える
• comp-design-a-proxy-with-a-proven-error-direction — 過大評価しない健全な上限を代理指標に設ける
• comp-keep-the-metric-tractable — NP 困難な最適解ではなく、ほぼ線形時間で計算できる代理指標を選ぶ
• comp-bound-approximation-error-explicitly — 代理指標と理想値の差を定量化して報告する
• comp-prefer-monotone-confluent-transformations — 合流性があり停止する書き換えによって、一意の不動点を得る

3. 測定理論の基礎（HIGH）

• meas-declare-the-scale-type — 統計量を使う前に、名義尺度・順序尺度・間隔尺度・比例尺度のいずれかを明示する
• meas-only-admissible-statistics — 尺度の変換に対して不変な統計量だけを使う
• meas-establish-meaningful-zero-and-unit — 比例尺度の主張には、真のゼロと明示した単位を用いる
• meas-preserve-the-empirical-relation — 既知の基準事例を指標が正しく順序付けることを検証する
• meas-avoid-ad-hoc-weighted-sums — 互換性のない尺度を恣意的な重みで合算しない

4. 指標特性の証明（高）

• prop-prove-monotonicity — 構成概念が変化したとき、スコアも適切な方向に変化することを証明します
• prop-prove-invariance-under-irrelevant-transforms — 名前変更や書式変更に対する不変性を証明します
• prop-ensure-sensitivity-to-relevant-change — 引き続き変化を識別できることを確認します（飽和しないこと）
• prop-check-weyuker-briand-axioms — 指標の種類に関する公表済みの公理を確認します
• prop-prove-boundedness-and-handle-empty — 値の範囲を証明し、空の場合や分母がゼロの場合の扱いを定義します
• prop-prove-or-disclaim-composability — 集計する前に加法性を証明するか、合算を避けます

5. 決定性と再現性（高）

• det-make-the-metric-a-pure-function — 隠れた時間、ネットワーク、グローバル状態に依存させません
• det-pin-iteration-and-tie-break-order — 全順序キーでソートし、ランダム性にはシードを指定します
• det-pin-the-input-representation — 測定対象とする表現（AST の段階）を厳密に固定します
• det-control-floating-point-and-accumulation — 加算順序と丸め精度を固定します
• det-version-and-record-the-toolchain — 指標のバージョン、ツールのバージョン、入力のハッシュを出力します

6. 構成概念妥当性と較正（中〜高）

• valid-converge-with-accepted-measure — 信頼できる構成概念の測定値との収束を示します
• valid-discriminant-not-just-loc — LOC／サイズを超える追加のシグナルがあることを証明します
• valid-predictive-validity-against-outcome — サンプル外で実際の結果を予測できることを示します
• valid-beat-the-trivial-baseline — 単純なベースラインに対する改善幅を示します
• valid-calibrate-thresholds-to-ground-truth — 切りのよい数値ではなく、データからしきい値を導出します
• valid-validate-out-of-sample — コーパスへの過剰適合を避けるため、ホールドアウト分割または時系列分割を使用します

7. 最適化の安全性とゲーミング対策（中）

• game-make-cheapest-improvement-the-right-one — 最もコストの低いスコア改善が、本質的な改善となるようにします
• game-recognize-goodhart-variants — 回帰型／極値型／因果型のグッドハートの法則を想定します
• game-pair-with-guardrail-metrics — 悪化を伴う「勝利」を退ける対抗指標を追加します
• game-hard-block-construct-violating-wins — 不変条件をゲートとして適用し、取引可能なソフトペナルティは決して使用しません
• game-detect-reward-hacking-with-audits — 上位スコアを抜き打ち監査し、代理指標と結果の乖離に注意します

8. 集計、レポート、導入（低〜中）

• agg-respect-scale-in-aggregation — 尺度が許す方法で集計する（順序尺度の平均は取らない）
• agg-report-uncertainty-not-false-precision — 見せかけの精度ではなく、区間／範囲を報告する
• agg-version-the-metric-publicly — SemVer と変更履歴を公開し、利用者が比較可能な状態を保つ
• agg-ship-reference-impl-and-test-vectors — 実装間で結果が一致するよう、テストベクトルを公開する

使い方

1. ワークフロー表で現在の段階を確認し、該当する最初のルールを開きます。
2. カテゴリを上から順に確認します。曖昧な構成概念や計算不能な理想像があると、その後のすべてがノイズになったり、使用不能になったりするため、def- と comp- は最重要です。
3. 指標を提案または批評する際は、レビュー担当者が根拠を確認できるよう、ファイルパスを添えてルールを引用します。
4. 新しい指標については、構成概念、代理指標、尺度＋単位＋ゼロ点、証明済みの特性、決定性の保証、妥当性の根拠、ガードレール、バージョンを明記した1ページの仕様書を作成します。各項目はここにあるカテゴリごとに1行で記載します。
5. 並び順の根拠については references/_sections.md を、新しいルールの追加については assets/templates/_template.md を参照してください。

参考ファイル

ファイル	説明
references/_sections.md	カテゴリの定義、影響レベル、並び順の根拠
assets/templates/_template.md	新しいルールを追加するためのテンプレート
metadata.json	分野、種類、参照元

関連スキル

• same-results-less-code、code-simplifier、complexity-optimizer、knip-deadcode — コード削減を指示するスキルです。このスキルは、これらに欠けている測定レイヤーを提供します。対象を定めて検証できる、決定論的で動作を保持する削減指標です。
• algorithmic-complexity-review、computer-science-algorithms — 既存の尺度（Big-O）を適用します。このスキルでは、新しい尺度の設計方法を学びます。
• opensearch-function-scoring-algorithms — 適用済みのランキング指標（NDCG、A/B テスト）です。このスキルは、その eval- カテゴリを支える基礎的な方法論です。