paper-to-code

論文からコードへ

公開コードのない論文を、その手法が論文の主張どおりに機能するかという、ひとつの問いに答えられる最小限の実装に変換します。

成果物はコードベースではなく、判定です。このスキルのすべては、すばやい反証のためにあります。手法が機能しないなら、壊れた仕組みを中心にインフラを一週間かけて構築した後ではなく、おもちゃ規模で半日以内に確かめたいものです。

使用しない場合

• 論文に公式コードがある場合 → 代わりにそれを読んで監査してください（公開された成果物が結果を再現するかどうかが問題なら、reproducibility-audit を使用してください）。
• ユーザーが論文の構成要素を自分のコードベースに取り入れたい、または完全な学習環境を設計したい場合 → pytorch-training-recipe を使用してください。
• ユーザーが手法を理解したいだけで、実行するつもりはない場合 → professor-mentor-technical-teaching または flow-deep-understanding を使用してください。

プロセス

1. 論文を検証可能な主張ひとつに絞る

何かを書く前に、再現実装で検証すべき仕組みをひとつ特定します。論文では多くの要素（新しい構成要素＋調整済みベースライン＋データの工夫）が組み合わされていますが、それらすべてを再現するのは、健全性チェックには高コストで不要です。

主張を反証可能な一文で示します。たとえば「ソフトマックス注意機構を仕組みXに置き換えると、メモリを削減しながら精度を維持する」のようにします。「表2を再現する」ではありません。論文に複数の主張がある場合は、この捉え方でよいかユーザーに確認します。

次に、仕組みを検証できる最小の設定を選びます。おもちゃデータセット（合成データ、MNIST規模、または論文のデータセットの小さな一部）、その構成要素を含む最小のモデル、短時間の学習実行を使います。原則として、論文のフルスケールの数値は対象外です。

2. 手法を抽出する

論文のアルゴリズム欄、数式、本文をもとに作業します。コーディングの前に、次の2つの成果物を作成します。

記法 → テンソル表。 中心となる数式に含まれる各記号について、名称、形状、データ型／値域、由来を記録します。再現実装で発生するバグの大半はここで生まれます（バッチ軸と特徴量軸、正規化前と後、合計と平均など）。コード内の変数名は論文の記号（alpha、z_t、H など）に合わせ、コードを論文と行ごとに照合できるようにします。

仮定の記録表。 論文では、初期化方式、正規化の順序、ドロップアウトを適用する位置、学習率のウォームアップ、損失項を平均するか合計するか、「標準的なデータ拡張」の厳密な形式など、詳細が必ず省略されています。仕様が不十分な詳細ごとに、抜けている情報、選んだ仮定、その理由（一般的なデフォルト、引用された先行研究、アブレーションからの推測）、および結果がその詳細にどの程度左右されると考えられるかを記録します。よくある抜け、妥当なデフォルト、感度評価の一覧は references/underspecified-defaults.md を確認してください。感度が高い項目は、再現に失敗した際にまず疑うべきものです。判定にはこの記録表を添付します。記録表を残した再現の失敗は論文についての証拠になりますが、記録表がなければ、あなたの推測についての証拠にしかなりません。

詳細が結果を左右するうえに推測もできない場合（仕組みを実装するうえで、文字どおり不可欠な情報がない場合）は、立ち止まり、黙って作り上げるのではなく、ユーザーにその点を伝えてください。

3. 最小限の実装

直接的で読みやすい、単一ファイルの PyTorch 実装にします。スタイル上のルールがあるのは、コードの目的が論文と照合できることだけだからです。

• 1 ファイル（reproduce_<method>.py）。どうしても収まらない場合を除き、モデル、データ、学習ループ、評価をこの順に記述します。設定システム、CLI フレームワーク、将来的な再利用を想定した抽象化は使いません。ハイパーパラメーターは先頭に通常の辞書または定数として置き、値の出典（論文 §4.1、仮定 #3 など）を注記します。
• 標準の PyTorchを使い、Lightning／フレームワークのラッパーは使いません。各行は、論文に記載された内容または文書化された仮定に対応するものとします。
• 中核となるメカニズムには専用のクラス／関数を設け、ゲートで単独テストできるよう、コメントに論文の式番号を記載します。
• バニラベースラインも実装に含め、後付けにしません。手法とベースラインを比較するステップ 5 の判定に必要なため、同じスクリプトでフラグを 1 つ指定するだけで、アブレーション版／標準版（例：メカニズム X の代わりに通常のアテンション）を実行できるようにします。
• 固定シードを使い、低コストで可能な範囲では決定性を確保し、ゲートに必要な少数の数値を出力／ログに記録します。実験追跡用のスタックは使いません。

4. 段階的な検証ゲート

ゲートは順番に実行し、失敗したゲートより先には進みません。それぞれのゲートは、異なる種類の失敗を特定し、「手法が機能しない」という結論に誤ってつながるのを防ぐために設けられています。

ゲート 1 — メカニクス。 中核コンポーネントを単独でテストします。いくつかの入力形状に対する出力形状、すべてのパラメーターへの勾配の伝播（1 回の逆伝播後に .grad が None ではなく、すべてゼロでもないこと）、論文で述べられている不変条件（行の合計が 1、出力が有効な確率、同変性、X の保存など）を確認します。翻訳時のバグを検出します。

ゲート 2 — 容量。 小さなバッチ（8～32 サンプル）を過学習させます。損失がほぼ 0 になり、精度が 100％になる必要があります。16 サンプルを記憶できないモデルには、損失関数の不具合、切り離された計算グラフ、またはデータのバグがあります。手法の性能不足ではありません。配線のバグを検出します。

ゲート 3 — メカニズム。 実際のテストです。小規模な設定で手法とバニラベースラインを比較し、同じ予算、同じシード方針を使います（効果が小さそうな場合はシードを 3 つ以上使用）。合格基準は方向性です。論文が主張する効果が現れるか（手法がベースラインを上回る／メモリ使用量が少ない／収束が速い）を確認します。小規模な設定では効果の大きさが論文の結果と一致しなくても問題ありません。

ゲート 4 — アンカー（任意）。 論文に、低コストで再現できるほど小さな値（アブレーション表の小規模設定の行など）があれば、妥当な範囲内でその値を再現できるか試します。これにより判定への信頼度は上がりますが、サニティチェックの必須条件ではありません。

5. 判定

最後に、次のいずれかを明示して結論を述べます。

• 主張どおりに機能（小規模設定）： 期待される方向の効果が現れました。観察された効果と、それが依拠する仮定を述べます。
• 再現できず： ゲート 1～2 は通過したものの、効果が見られないか、逆の結果になりました。最も原因となっている可能性が高い前提条件台帳の仮定を列挙し、低コストで変更できるものがあれば、最終決定の前に変更を試します。
• 判定不能： 結果を左右する詳細が推測できない、または小規模設定では主張を検証できない（例：メカニズムが長いコンテキスト／大きな幅でのみ効果を発揮する）状態です。判断に必要なものを述べます。

出力形式

次の順に提示します。

1. 検証対象の主張（1 文）と選択した小規模設定。
2. 前提条件台帳（表：未解決点／仮定／根拠／感度）。
3. 実装（python reproduce_<method>.py で実行できる単一ファイル）。
4. ゲートの結果（各ゲートについて、合格／不合格と数値）。
5. 上記の理由を踏まえた判定。

ユーザーが最初に計画だけを求めている場合（まだコードは不要）、1～2 の後で止め、実装前に確認を求めてください。