agentleFS
yuisekiyuiseki/GeoAI-master-skills/.agents/skills/experiment-design/SKILL.md

experiment-design

Skill3 starsChanged yesterdayApache-2.0View on GitHub

分析を流す前に、何を主張とし、どの結果ならその主張を支持し、どの結果なら退けるかを固定する。主張ごとに、同じ結果を説明できる別の理由、測る量、比べる相手、評価の作り方、判断の規則、悪い結果の意味、反証と頑健性の確かめを書き、比較の単位 (実験の区画) と流す順に落とす。計画 (EXPERIMENT_PLAN.md) と実行の記録 (EXPERIMENT_TRACKER.md) を分けて残す。結論が比較の結果で決まり、その比較の設定 (分け方、重み、単位、閾値、モデル) を結果を見てから変えられるとき、また、問いの言葉の読み方 (何を数えるか、どの範囲に入れるか、値をどう対応づけるか) を選べて、読み方で答えが変わりうるとき (一番の場所や上位を答える問いを含む) に使う。手法そのものは選ばない。

32 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use list-quality-scorecard and positive-reply-scoring.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • creatop-gtmSkill

    list-quality-scorecard

    Check a lead list before it goes into a sequence. Gives a deliverability readout (firm) and a targeting readout (advisory). Surfaces issues, never blocks. Use before enrolling any list.

    Also in 3 projects that use this

  • creatop-gtmSkill

    positive-reply-scoring

    Classify replies and compute positive reply rate, the metric that predicts revenue. Use to tell whether a campaign is actually working, not just getting replies.

    Also in 3 projects that use this

The file

Files
SKILL.md

experiment-design

結果を見た後なら、どんな結果にも筋の通る説明が付けられる。分け方を変えれば点数は上がり、重みを変えれば有意になり、単位を変えれば相関が出る。どれも一つずつは正当に見える。このスキルは、結果を見る前に「何が出たら主張を認め、何が出たら認めないか」を書いて固定し、見た後に変えたことを、変えたと分かる形で残す。

ここでいう実験は、介入の実験 (無作為化した処置) に限らない。主張を支持するか退けるかの証拠を得るために、条件を固定して行う比較を 1 つの実験の区画 (block) と呼ぶ。たとえば次のものは、どれも区画になる。

  • モデルや特徴量の比較 (同じ分割で、ある / なし)
  • 評価の分け方を使い道に合わせた比較 (空間で分ける、地域で伏せる、時間で分ける)
  • 要素を外す比較 (ablation)
  • 負の対照 (効くはずのない入力や結果で、効果が 0 になるか)
  • 答えの分かる模擬
  • 内挿の back-test (観測点を伏せて当てる)
  • 空間の重みや単位を変えたときの感度
  • 頑健性の確かめ
  • 因果の推定量どうしの比較

このスキルが決めるのは、比較の要求仕様 (何と何を、どんな評価で、どの規則で比べるか) まで。どの手法やスクリプトで実現するかは、分析の流れ (リポジトリ直下の AGENTS.md) が決める。因果の主張なら、識別できるか (処置、推定の対象、調整の集合、識別の仮定) は、ここでは決めない。識別の設計の表を受け取り、その表に従った推定の比較を区画にする。表が無ければ、因果の主張を確認の区画にしない。

ひな形は assets/EXPERIMENT_PLAN.md と assets/EXPERIMENT_TRACKER.md。

使うか、どこまで書くか

計画の重さは、結果を見てから変えられる選択の数で決める。

  • 使わない: 選べる設定も読み方も無い問い、変えても答えが変わらない問い (1 つのデータの決まった列を数える、引く)。最終回答の方法の欄で足りる。1 つの値や一番の場所を答える問いでも、読み方を選べて答えが変わりうるなら、使わないに入れない。
  • 短く書く: 主張が 1 つで、決め手の比較が 1 つ。計画は主張、判断の規則、悪い結果の意味の 3 行と、区画 1 つでよい。記録は 1 表。
  • 全部書く: 主張が複数ある、決め手の比較の設定が何通りもありうる、結果で意思決定する、確認として報告する。

読み方で答えが変わりうる問いは、多くは短く書く。読み方の候補 (問いの言葉が指しうるもの、範囲に入れるもの入れないもの、値の対応づけ方) を並べ、読み方ごとの比較を 1 つの区画にする。主にする読み方は、結果を見る前に使い道から決めて理由を書く (「駅に近い」を、歩く人の使い道なら道のりで、地図の上の近さなら直線で)。結果を見てから、答えの都合のよい読み方を主にしない。主の読み方の答えと、読み方を変えたときの答えを並べて報告する。

迷ったら短く書く。区画の欄を全て埋めることが目的ではない。埋めなかった欄は、要らない理由を 1 語で書く (「なし: 乱数を使わない」)。

探索と確認

区画ごとに、mode を決める。

  • 確認 (confirmatory): 主張、測る量、比べる相手、評価の作り方、判断の規則を、決め手の結果を見る前に書いた区画。結果は、主張を支持するか退けるかの証拠として報告できる。
  • 探索 (exploratory): それ以外の全て。データを見て仮説を作る、設定を探す、結果を見てから変えた区画。結果は仮説として報告し、主張の証拠には数えない。

確認か探索かを分けるのは、決め手の結果 (比べる指標の値、効果の大きさ、検定の結果) を見たかどうか。生のデータを読んだこと (行数、列、値の範囲、欠け、表そのもの) は、確認を妨げない。データを読まずに計画は立てられない。

妨げるのは、決め手と同じデータで、結果を見ながら仮説や設定を作ったとき。その仮説を同じデータで確認しない。確認にするなら、確認に使う部分 (地域、期間、標本) を先に分けて、その部分の結果を見ないでおく。分けられないなら、その主張は探索として報告する。

計画の「流す前に決めたこと」には、何を見た後に決めたかを、生のデータと結果に分けて書く (「表は全行読んだ。指標は計算していない」)。

結果を見た後に設計を変えることは禁止しない。変えたら、何を見た後に、何を、なぜ変え、結論にどう効くかを、記録の deviation の欄に書く。変えた区画は探索として扱う。変える前の区画の結果も消さずに残す。

手順

  1. 問いと使い道を 1 行で書く。使い道は、比べる相手と評価の作り方を決める (未調査の地域を埋めるなら、評価でも地域を伏せる)。
  2. 主張を書く。結果の数字で確かめられる形にする (「最寄り駅までの道のりを特徴量に入れると、まだ取引の無い町丁での地価の予測の誤差が、入れないときより小さい」)。主張は、使い道の判断に効くものだけ。主張の数に上限は置かないが、どの判断にも効かない主張は書かない。
  3. 主張ごとに、下の 8 つを順に書く。
    1. 主張 (claim)
    2. 別の説明 (alternative explanation): 主張が偽でも、同じ観測結果が出る理由。下の表から、この比較で起こりうるものを選ぶ。
    3. 測る量 (observable quantity): 主張が正しいとき、何がどう動くか。指標と、どの行で測るか。
    4. 比べる相手 (comparator、control): 基準 (平均、前の期間、最近傍、ないとき)、外した版、負の対照。
    5. 評価の作り方 (evaluation design): 評価する行の集団と、分け方の原則 (使い道を真似る)。分割表を作るのは分析の段階。ここでは原則と、分割表を基準とモデルで共有することを書く。
    6. 判断の規則 (decision rule): どの結果なら支持し、どの結果なら退けるか。下の「判断の規則と閾値」。
    7. 悪い結果の意味 (failure interpretation): 主張が退けられたら、何が分かったことになるか。救済に使ってはいけない変更 (分け方、重み、閾値、モデル、単位) を、ここで名指しする。
    8. 反証と頑健性 (falsification、robustness): 別の説明が正しいなら結果が変わるはずの比較 (反証)、結論が設定の妥当な別の選び方でも保たれるかの比較 (頑健性)。
  4. 区画に落とす。1 つの区画は、1 つの比較で 1 つの主張 (か別の説明) を試す。区画の欄はひな形にある。
  5. 流す順を決める (下の「流す順」)。
  6. 流す前に決めたこと (pre-run decisions) を、計画の最後に書く。決めた日時と、その時点で見ていた結果 (見ていなければ「なし」)。
  7. 計画を保存してから流す。流したら、1 回ごとに記録に 1 行足す。結果のファイルの場所、データの版、状態。計画と違うことをしたら deviation に書く。
  8. 判断の規則を、結果に当てる。当てた結果 (支持、退ける、判断できない) を記録の notes に書く。規則で判断できなければ、判断できないと書く。後から規則を作らない。

別の説明

論理の否定 (「効かない」) ではなく、主張が偽でも同じ結果が出る仕組みを書く。

別の説明例試す比較の例
リーク特徴量が答えや試験側の情報を含む。同じ地点が学習と試験の両方にある使い道を真似た分け方での比較、特徴量の作られた時点の確認
交絡処置と結果の両方を動かす変数がある識別の設計の表に従う。表が無ければ確認にしない
単位と尺度の選び方格子の大きさ、行政区の階層、変換の単位で結果が変わる単位を何段か変えた比較
多く使ったデータ比べる相手より多くの行や情報源を使っている同じ行と情報源にそろえた比較
モデルの容量比べる相手より柔らかいモデルを使った。差は特徴量でなくモデルの違い同じモデルで特徴量だけを変えた比較
観測の努力記録が多いのは、調べた量が多いから努力のそろった単位どうしの比較
偶然fold、種、標本で揺れる範囲の差分け方の繰り返し、置換、区間
手法の設定重み、帯域、近傍の数、閾値の 1 つの選び方でだけ出る設定の妥当な別の値での比較

全てを試さない。この比較で、もっともらしいものだけを書き、書かなかったものは理由を 1 語で残す。

判断の規則と閾値

  • 数の閾値 (「誤差が 5% 以上下がれば採用」) は、根拠があるときだけ使う。根拠になるのは、業務の要件 (この精度が無ければ使えない)、測定の誤差、意味のある最小の差 (それより小さい差は判断を変えない)、先に確立された基準。根拠を規則の隣に書く。
  • 根拠が無ければ、数の閾値を作らない。代わりに、向き (比べる相手より良いか) と不確かさ (fold や種での揺れを越えるか、区間が 0 をまたぐか) で書くか、「規則なし、記述として報告」と書く。
  • 規則は、結果の数字に当てて機械的に判定できる形で書く (「同じ分割表の全ての repeat で、駅の距離ありの RMSE が、なしより小さい」)。
  • 指標は 1 つを主にする。主の指標で判断し、他の指標は判断を変えない補助として書く。複数の指標で判断するなら、組み合わせ方 (全てで良い、どれかで良い) を先に書く。

悪い結果の意味

悪い結果が出たときに何をしないかを、先に書く。

  • 救済しない: 分け方、重み、閾値、モデル、単位、評価の行を、結果が悪かったからという理由で変え、その結果で同じ主張を支持しない。変えた比較は探索の区画として残す。
  • 悪い結果が言うこと: 「この評価と規則のもとで、主張は支持されなかった」。主張が偽だとまでは言えないなら、何が足りないか (検出力、データの量、比べる相手の強さ) を書く。
  • 判断できない結果: 規則に当てて判定できない (揺れが大きすぎる、指標が出ない)。判断できないと書き、どうすれば判断できるかを書く。

反証と頑健性

  • 反証: 別の説明が正しいときと、主張が正しいときで、違う結果を予言する比較。負の対照、置換、偽の閾値、答えの分かる模擬。主張が正しければ、反証の比較で効果は消えるか、決まった向きに出る。
  • 反証の比較ごとに、何を保ち、何を壊すかを書く。置換や入れ替えは、ある構造を壊し、別の構造を残す (群の中で並べ替えると、群ごとの平均は残る。時間の中で並べ替えると、値の分布は残るが順序は壊れる)。試す別の説明の仕組みが、保った側に入っていると、その比較は別の説明を試せない。別の説明が正しいとき、壊した後に効果がどうなるか (消える、残る) と、主張が正しいときにどうなるかが違うことを、流す前に書いて確かめる。両方で同じなら、その比較は反証にならない。
  • 頑健性: 結論が、妥当な別の選び方 (種、分け方、単位、重み、データの版) でも保たれるか。保たれた範囲に結論を合わせて書く。
  • 計画では、どの別の説明をどの反証で試すか、どの設定を何通りに変えるかを書く。条件を掃引して保たれた範囲を表にするのは、分析の段階の仕事で、ここではその要求 (変える設定と値、結論の式) だけを書く。
  • 反証と頑健性の区画も、流す前に判断の規則を書く。反証で効果が消えなかったら、主張ではなく別の説明が支持される。

流す順

基本は次の順。各段の後で、先へ進むかを決める。

  1. 健全性 (sanity): 入力の行数、結合の前後、指標の計算が既知の例で合うか。合わなければ止める。
  2. 基準と対照 (baseline、control): 比べる相手を、決め手と同じ評価で流す。基準が既知の値を再現しなければ止める。
  3. 決め手 (decisive): 主張を確認する区画。
  4. 反証と頑健性: 決め手が支持でも退けるでも流す。支持のときだけ流すと、頑健性の確かめが偏る。
  5. 費用の大きい追加 (expensive optional): 判断を変えないなら流さない。

要らない段は飛ばしてよい。飛ばすなら理由を書く (「健全性: 既存の分割表と同じ入力で、行数は前の記録で確かめた」)。決め手の前に、決め手と同じデータで設定を探すなら、その探索は探索の区画として順に入れ、決め手の評価の部分を見ない。

計画と記録

  • EXPERIMENT_PLAN.md: 流す前に書く。問いと使い道、主張の地図、区画、流す順、仮定、判断の規則、反証、流す前に決めたこと。流した後に計画を書き直さない。直すなら、直した日時と理由を計画の末尾に足し、記録の deviation にも書く。
  • EXPERIMENT_TRACKER.md: 流すたびに 1 行足す。行を消さない。失敗した実行、捨てた実行も残す (status を failed か abandoned に)。
  • 置き場所は分析の作業場所 (成果物と同じ場所)。分析の結果のファイルを指す result_path は、作業場所からの相対パス。
  • 最終回答や報告では、計画と記録から写す。何が確認で何が探索か、何を見た後に何を変えたか、救済に使わなかった変更は、事後には正しく復元できない。流す前と流す間に、ここに書いておく。

やらないこと

  • 手法やスクリプトを選ぶこと、分割表や重みを作ること。要求を書くだけ。
  • 因果の識別の判断。設計の表を受け取るだけ。
  • 根拠の無い固定の数 (主張の数の上限、種の数の既定、改善率の閾値)。種の数は、決め手の差と揺れの大きさで決め、決めた理由を書く。
  • 論文の構成 (本文と付録、図の割り当て、新規性の筋書き)。

書き出すもの

  • EXPERIMENT_PLAN.md (短く書く場合は、主張、判断の規則、悪い結果の意味と区画 1 つ)
  • EXPERIMENT_TRACKER.md
  • 主張ごとの判定 (支持、退ける、判断できない) と、その区画が確認か探索か
  • deviation の一覧

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.