test-ml-pipeline

ML パイプラインのテスト（ルーター）

ML ワークスペースのテストがどこにあるか、何と何を対応させるか、 各テストカテゴリの本体をどのサブスキルが担当するかを説明します。

最初に行うこと（毎ターン）

ほかのことに答える前に、以下を行います。

1. ユーザーが尋ねているテストについて、承認済みの設計ノートがあることを確認します。 対応ルールは厳守です。 tests/<category>/test_NN_<short_name>.py が存在するのは、 journal/NN_<short_name>.md が少なくとも approved であり、 experiments/NN_<short_name>.py が対応するスクリプトである場合に限ります。設計ノートが存在しない場合は、 iterate-ml-experiment に引き継ぎます。
2. 事前チェックリスト（以下）を、回答内に見えるテキストとして、各項目にチェックを付けて出力します。
3. ディスパッチ表を使ってテストカテゴリを担当するサブスキルを選び、引き継ぎます。

事前チェック — テスト作業の前に、このチェックリストを見えるテキストとして出力します

Pre-flight (test-ml-pipeline):
- [ ] `journal/NN_<short_name>.md` exists and is at least `approved`
      (or confirmed n/a — about to hand off to `iterate-ml-experiment`)
- [ ] `experiments/NN_<short_name>.py` exists with the matching stem
      (or confirmed n/a — about to hand off to `organize-ml-workspace`)
- [ ] Test category picked: smoke | regression | distribution | …
- [ ] Subskill dispatched: `smoke-test-ml-pipeline` | …
- [ ] Test file stem decided: `tests/<category>/test_NN_<short_name>.py`
- [ ] pytest is on the project's dependency manifest (per
      `data-science-python-stack` § Tier 1)

停止条件 — ほかのことを行う前に確認してください

• 承認済みの設計ノートなしにテストを作成してはいけません。 対応する journal/NN_*.md がディスク上に存在し、少なくとも approved になっていない場合は、tests/<category>/test_NN_*.py を決して作成しないでください。設計ノートが契約であり、テストはその契約が守られていることを検証します。逆の順序では整合性がありません。
• ファイル名の規則は厳守です。 テストファイルのベース名は test_NN_<short_name>.py（pytest が必要とする test_ 接頭辞付き）であり、NN_<short_name> の部分は実験と完全に一致します。1 つの実験につき、カテゴリごとにテストファイルは 1 つです。test_<NN>_v2.py も test_NN_<short_name>_2.py も不可です。テストを変更する必要がある場合は、そのファイルを直接編集してください。対応関係は 1 対 1 のままにする必要があります。
• カテゴリごとにサブスキルは 1 つです。 このスキルが行うのは空のテストファイルを配置して引き継ぐことだけです。このスキルでは、アサーション本体、フィクスチャの構築、テスト固有のロジックを記述しないでください。それらは対応するサブスキル（smoke-test-ml-pipeline など）の担当です。
• テストランナーは pytest です。 テストは pytest のテストであり、jupytext 形式の # %% スクリプトではありません。実験スクリプトは experiments/ に置き、対話的な反復のために # %% 形式のままにします。テストは合格または不合格で判定され、pytest のレポート機能が役立ちます。2 つの形式を混在させないでください。

このスキルが担当するレイアウト

project/
└── tests/
    ├── smoke/
    │   ├── test_01_baseline.py        # ↔ experiments/01_baseline.py
    │   ├── test_02_short_name.py
    │   └── ...
    └── (future: regression/, distribution/, …)

対応ルール：

journal/NN_<short_name>.md
experiments/NN_<short_name>.py
tests/<category>/test_NN_<short_name>.py

— 3 つすべてで、同じ NN_<short_name> のステムを使います。テストファイルのベース名にある test_ 接頭辞は pytest の命名規則です。それ以降はすべて実験に対応します。

tests/<category>/ サブフォルダーにより、名前を変更せずにワークスペースへテストの種類を追加できます。v1 で必須なのは tests/smoke/ のみです。

テストカテゴリ — ディスパッチ表

まずユーザーの意図を確認し、該当しない場合は末尾のデフォルトに従います。

状況	サブスキル
新しい実験が承認された直後で、そのスモークテストを接続する必要がある	smoke-test-ml-pipeline
ユーザーが「02 のスモークテストを書いて」「スモークテストが失敗している」「X のスモークテストでは何をアサートすべき？」と言う	smoke-test-ml-pipeline
ユーザーが「02 と 03 の間でメトリクスがずれたので、それを固定できますか？」「先週の実行結果を基準にした回帰テスト」と言う	regression-test-ml-pipeline（将来の機能 — v1 では未実装）
ユーザーが「予測値が範囲外」「本番環境でキャリブレーションがずれている」「スキーマの不変条件」と言う	distribution-test-ml-pipeline（将来の機能 — v1 では未実装）
ユーザーから「この実験にテストを付けるべき？」という自由形式の質問がある	デフォルトは smoke-test-ml-pipeline — 各反復でスモークテストは必須です。それ以外は任意です。

現在実装されているのは smoke-test-ml-pipeline のみです。 今後、カテゴリは同階層のサブスキルとして追加されます。ディスパッチ表は、それらを追加する際の契約です。

実験ごとの必須テストのルール

承認されたすべての実験は、JOURNAL.md で done としてマークする前に、成功するスモークテストを備えている必要があります。 これは iterate-ml-experiment § 3（設計メモの承認後、スクリプトの作成前）と § 4（結果を記録する前）で徹底されています。テストは反復ループの一部であり、後回しにするものではありません。スモークテストが失敗した場合、次の反復の対象はモデルではなくパイプラインです（build-ml-pipeline に戻ります）。スモークテストの失敗は、予測器の指標の問題ではなく、DataOps グラフの構成に関する構造的な問題であることがほとんどです。

スモークテストは、ワークスペース内のすべての実験で必須です。その他のテストカテゴリ（回帰、分布など）は任意で、ワークスペースのニーズに応じて追加します。

判断フロー

1. 承認済みの journal/NN_<short_name>.md と、それに対応する experiments/NN_<short_name>.py はありますか？
   • いいえ → iterate-ml-experiment（設計メモが先）または organize-ml-workspace（スクリプトが先）に引き継ぎます。ここで終了します。
   • はい → 続行します。
2. ユーザーの意向（Dispatch テーブル）からテストカテゴリを特定します。デフォルトは smoke です。
   • Dispatch テーブルでサブスキルが (将来対応 — v1 では未実装)（regression-test-ml-pipeline、distribution-test-ml-pipeline など）とされている場合：ここで終了します。tests/<category>/ を作成しないでください。サブスキルが存在するかのように引き継がないでください。def test_、アサーションのコード片、スモークテスト本体を書かないでください。カテゴリは認識されていますが未実装です、と一文で伝えます。任意で「サブスキルがリリースされるまでのギャップ」と補足できます。
3. pytest のひな形（def test_*(): 関数を1つ、空の本体、# TODO: filled in by <subskill> マーカー）を使って、空のテストファイルを tests/<category>/test_NN_<short_name>.py に配置します。ファイルがすでに存在する場合は、上書きしないでください。手順2で将来対応のカテゴリのために終了した場合は、この手順を省略します。
4. サブスキル（smoke-test-ml-pipeline など）に引き継ぎます。アサーション、フィクスチャの構築、必要なヘルパーはサブスキルが作成します。
5. テストを実行する前に、サブスキルのドラフトが正しいことをユーザーに確認します（このループを担当するのはサブスキルです。このスキルが行うのは、配置と引き継ぎのみです）。

このスキルが行わないこと

• pytest を実行すること。テストの実行はユーザー（または CI）が判断します。
• アサーション本体を書くこと。各サブスキルが担当カテゴリのアサーションを作成します。
• テストが必要かどうかを判断すること。実験ごとの必須テストのルール（各反復でスモークテストを行うこと）はこのスキルで固定されていますが、任意カテゴリの追加はワークスペース単位の判断事項であり、このスキルではなくユーザーが決めます。
• tests/ 以外のファイルを変更すること。iterate-ml-experiment／organize-ml-workspace／build-ml-pipeline／evaluate-ml-pipeline への関連スキルの編集は、それぞれのスキルに対するものであり、このスキルに対するものではありません。

関連スキル

• smoke-test-ml-pipeline — スモークテストの契約を担います （フィクスチャの構築、診断可能な設計という特性、 アサーション、失敗時のセマンティクス）。v1 で必須となる 唯一のテストカテゴリです。
• organize-ml-workspace — ワークスペース作成時に、 journal/ ／ experiments/ と並べて tests/<category>/ を用意します。プレースホルダーのテストファイルを配置するのはこの スキルであり、organize-ml-workspace ではありません。
• iterate-ml-experiment — イテレーションループを進行させます。設計メモの承認後、 このスキル（さらに smoke-test-ml-pipeline を呼び出します）に処理を引き継ぎ、 対応するテストを作成します。実験の実行後は、実験を done に変更する前に スモークテストが合格することを必須とします。
• build-ml-pipeline — パイプラインの宣言を担います。スモークテストは、 build-ml-pipeline の X マーカールール（X を早い段階でマークし、その後に特徴量化し、 上流ノード経由で履歴を参照する）が遵守されたことを示す実行可能な証明です。 スモークテストの失敗は通常、パイプラインの構成に誤りがあることを意味します。 このスキルに戻ってください。
• evaluate-ml-pipeline — CV プロトコルを担います。履歴に依存する特徴量がある パイプラインでは、CV は必要ですが十分ではありません。smoke-test-ml-pipeline が CV では補えない部分を埋めます。
• data-science-python-stack — このスキルを使用するすべてのワークスペースで、 pytest を Tier 1 の必須依存関係として宣言します。