exp-batch

Exp Batch：必要性を確認 → 設定を明確化 → 事前確認 → 実行 → 指標を取り込む

小規模でも完全な実験にします。1つのブランチで、適切に完了し、プロット可能な状態にします。範囲を横に広げてほかのブランチに手を出してはいけません。時間を節約するために厳密さを損なってもいけません。

1. そのブランチがまだ必要か確認する

• プロジェクトのメモ、キャンペーン計画、既存の結果を確認します。プローブによってこのブランチがすでに枝刈りされていませんか？ 同等の設定ですでに指標が測定されていませんか？ 該当する場合は、その旨を伝えて停止します（または、以前の枝刈りが適用されない理由を記録します）。
• 2〜3文で言い直します。このバッチが最終表／図に何を加えるのか、どのセルを埋めるのか、合格指標は何かを明記します。計画書は作成しません。

2. 未解決の設定項目だけを徹底確認する

• 事実（パス、デバイスの利用状況、キャッシュの場所、過去の設定）は自分で確認します。ユーザーに尋ねるのは、科学的な意味を変える選択肢だけです。プロトコルで固定されていないハイパーパラメーター、シード数、どの分割を使うか、コールバックと再読み込みのどちらをカバーするか、正式な実験か探索的な実験か、などです。
• バッチの指標の契約は、同系列の実行と同一に保ちます。分割、指標の定義、指標を適用する対象を揃えます。測定方法が異なるバッチをほかのバッチと同じ図に載せることはできません。逸脱があれば、記録に明記します。
• 構造化された質問は1回だけ行います。2回目は、回答によって科学的に新たな選択肢が実際に生じた場合に限り認められます。設定上の決定事項が膨らむなら、実際にはキャンペーンです。exp-campaign を提案します。

3. 事前確認：環境とリソース

この確認をせずに開始する実行は、ほかの誰かとデフォルトデバイスを取り合う実行です。数秒で済み、承認も不要で、プローブか正式な実験か、長時間か短時間かを問わず、起動前に毎回行います。形式的な手順を省くのが目的です（足場づくりも、防御的なコードも、追加の承認ラウンドも不要）。この確認は形式的な手順ではありません。

• 環境： インタープリター／環境の有効化、作業ディレクトリ、現在実際にインポート可能な依存関係のバージョン、入力パスの存在、出力先とチェックポイント用ディレクトリへの書き込み権限を確認します。
• まずプラットフォームを把握する： プロジェクトのメモ、慣例、またはセッションですでに指定されているデバイスプラットフォーム（CUDA／Ascend／MUSA／PPU クラス／…）を使います。本当に不明な場合は、環境（インストール済みツールキット、デバイスファイル、プロジェクト独自のランチャーの設定など）から確認するか、一度だけ質問します。その後は、そのプラットフォーム固有のツールと環境変数の命名規則を使います。プラットフォームの取り違えによるエラーは自ら招くもので、実行を無駄にします。
• 普段の状態ではなく、現在のリソースを確認する： このマシンで使われている方法（nvidia-smi、Ascend の npu-smi、MUSA の mthreads-smi、または同等のプラットフォーム用ツール）でデバイスの現在の状態を読み取り、使用率、メモリ、各デバイスをどのプロセスが使っているかを確認します（ほかの人のジョブと、このプロジェクトの並列ブランチの両方が対象です）。その結果に基づいて判断し、プラットフォームの可視デバイス用環境変数（CUDA_VISIBLE_DEVICES、ASCEND_RT_VISIBLE_DEVICES、MUSA_VISIBLE_DEVICES、…）を明示的に設定してデバイスを指定します。実行をデフォルトデバイスに任せてはいけません。チェックポイント／ログ用ディスク容量、およびジョブがデバイスに依存しない場合の RAM／CPU も、同じ確認で把握します。
• 競合： 以前の試行の残存ジョブ（「前回のジョブは本当に終了したか？」）や同系列のブランチは、カードを使用していることに気づきにくいよくある原因です。プロセス一覧の所有者、名前、経過時間を確認すれば判別できます。
• コスト： この設定に基づく実行時間とメモリ使用量を正直に見積もります。そうすれば、後で発生する競合をコードのせいにせず、競合として判断できます。
• その後、実行する： 誰が何を起動するかについて、プロジェクトのルールに従います。空きリソースが設定に足りない場合は、開始せず、設定を黙って縮小もしません。不足しているものを伝え、待機するか、別のデバイスを使うか、合意のうえで設定を変更するかを選びます。

4. このセッションで実装し、プロジェクトの規約に従って実行する

• 実装は、研究者が実行開始の許可を出した後、ここで、同じセッション内で行います（これは exp-campaign のモデルのような新しいセッションへの引き継ぎではありません）。実行のタイミングは研究者が決め、正式な実行は、誰が開始するかについてのプロジェクトのルールに従います。研究者が実行するか、明示的に許可を与えます。
• モジュールの配置： それぞれのコードは、それが属するモジュールに配置します。実験固有のコードは、予測可能なレイアウトの実験専用ディレクトリ内に置き、実験名から見つけられるようにします。利用者が 1 つしかいない共通の抽象化は作成しません。兄弟ブランチ間で同じファイルを奪い合うことになる場合は、モジュールを分割します。
• 疎結合： 既存のインターフェースを通して、安定した共通ライブラリを利用します。このバッチに合わせるために共通ライブラリの内部を変更してはいけません。共通コードにバッチ固有の分岐を追加してはいけません。インターフェースに本当に必要なものがない場合は、作業を止めてエスカレーションしてください。これはキャンペーンレベルの判断事項です。
• ポニーテール型の研究コード： バッチを正しく実行するために必要最小限のコードにします。防御的プログラミングはしません： 推測に基づく検証や「念のため」の分岐は追加せず、エラーを握りつぶしません。エラーが発生したら、実際のエラーを出して終了します。実行に失敗した場合、まずコードではなく環境（デバイスの競合、ディスク容量不足、古いキャッシュ、競合するジョブ）を疑います。証拠からコードの誤りが示された場合にのみ、コードを変更します。
• この種のプロジェクトでよくある既知の失敗モードに注意します。OOM（自分のプロセスまたはマシン）、NaN、チェックポイントのシリアライズ、メトリクスの退化（例：すべて同じ回答になる）、エビクション（隣のジョブまたはカーネルが実行中にデバイスを奪う）です。失敗した場合は、失敗した成果物とログを保持し、最小限に切り分け、失敗した実行を結果の行として報告してはいけません。
• 対処する前に「環境」と「コード」を切り分けます： 終了コード、ログの末尾、プラットフォーム標準のツールを使って最新のデバイス情報を取得すること（自分のプロセスはまだ動いているか、現在誰がデバイスを使用しているか）で、エビクションされたジョブと実際のバグを見分けられます。エビクションされた実行については、証拠を保持し、最新の情報から空いているデバイスを選び、逸脱を記録したうえで再キューイングします。証拠からコードの誤りが示された場合にのみ、コードを変更します。リソースに合わせて設定を変更した場合は、必ず明記してください。兄弟実行とのメトリクス契約が壊れる可能性があります。
• これらのパターンは典型例であり、起こり得るすべての事例ではありません。 想定外の失敗には、その場で対処します。判断を下し、証拠を保持し、実施したことを伝えてください。存在しないルールを待って作業を止めてはいけません。また、失敗を結果として扱ってはいけません。
• 否定的な結果も結果です。成功時と同じスキーマで記録してください。

5. 長時間の実行では later を使って待機する（実行を委任）

長時間の実行（数時間に及ぶもの）でターンを止めてはいけません。また、ループでポーリングしてはいけません。無人で実行する場合のパターンは次のとおりです。

• 委任を明示します。「実行して結果を確認してください」は、実行を委任する指示です。研究者から委任されていない場合は、実行を開始する前に提案します。「これには約 X 時間かかります。バックグラウンドで実行し、later ツールで自動的に再開できます。委任しますか？」と伝えます。また、バッチが完了するまで各ターンの最後に later のスケジュールを設定することも伝えます。
• **プロジェクトの規約（nohup/tmux/ランチャー）に従ってバックグラウンドで起動し、その後 later ツールを呼び出します。**所要時間を見積もり、約 10％の余裕を加えます（5 時間の実行なら、5.5 時間後にスケジュール）。プロンプトには、将来の自分への完全な指示として、確認事項、判断事項、次に実行する内容を書きます。
• スケジュールを設定したらターンを終了します。later の呼び出しがそのターンの最後のアクションです。待機中に何もせず時間をつぶしたり、処理を回し続けたり、トークンを消費してポーリングしたりしてはいけません。スケジュールされたプロンプトはユーザーメッセージとして届き、人が不在のままセッションが再開します。実行をまたいで再開を連鎖させます。再開のたびに状況を確認し、判断し、次の実行を開始して、次の later をスケジュールします。
• **タイマーは所要時間の見積もりであり、完了の合図ではありません。**再開時には、メトリクスを記録する前に、実行が実際に完了し、成功したことを確認します。まだ実行中の場合は、当初の予定ではなく、観測した進捗（ログ／エポックカウンター、現在のスループットなど。競合によって予定していた 5 時間の実行が 7 時間に延びることもあります）から残り時間を再見積もりし、残り時間に余裕を加えた時刻で、別の later をスケジュールします。実行が実際に完了するまで繰り返します。再開回数に上限はありません。
• ホストに later ツールがない場合は、代替として、想定所要時間と戻ってくる時刻を研究者に伝えるか、プロジェクト独自の待機規約に従います。

6. 図表に利用できる場所にメトリクスを保存する

• すべての実行結果を共有の結果テーブルに記録します。記録項目は、ID、設定、分割、サーフェス、メトリクス、ステータス、エビデンスのパスです。選択したものだけでなく、記録されたすべてのエポック／ポイントを含めます。
• 完了前にプロット可能か確認します。このバッチを独立した曲線ファミリーとして最終図に組み込めますか。また、必要な基準線（ベースラインの参照線）はそろっていますか。データの形状によって扱いにくいプロット（孤立した点、軸の混在など）が必要になる場合は、図の作成時ではなく、今のうちにデータ収集を修正します。
• **バッチレポートは、作業が部分的、ブロック中、または中断された場合も含め、必須です。**キャンペーン計画の隣に <batch-or-stage>.report.md を作成します（既定のパスは docs/experiments/<slug>.stage<N>.report.md です。独立したブランチの場合は、プロジェクトの実験用エリアに置きます）。レポートには、完成状況の総表（計画した実行／セルごとに、完了／部分的／保留／未着手とエビデンスのパスを記載）、実際に実行した設定とコマンド、実行しなかった内容とその理由、メトリクス契約からの逸脱、失敗とその対処（追い出し／OOM／NaN）、キャンペーンで再検討すべき点を含めます。結果の行を捏造したり、計画した実行を黙って省略したりしてはいけません。
• 同じ内容を簡潔にチャットでも報告します。このバッチによって計画セッションが再開することはありません。研究者がレポートを持ち帰るため、確認対象となるのはファイルです。