refactor-research-code

研究コードのリファクタリング

研究用リポジトリを「自分の環境では動く」状態から、論文に記載された数値を一つも変えることなく、整理され、文書化され、再実行可能な公開リリースへと整えます。研究コードには、不要になった実験分岐、ハードコードされたパス、マジックナンバーのハイパーパラメーター、文書化されていない「このファイルを実行してから、あのファイルを実行する」という手順、身元を特定できる手がかりが蓄積しがちです。このスキルでは、そうした不要物を取り除き、リポジトリに適切な構成を与えます。ただし、最優先事項は結果の保持です。変更案をすべて安全（機械的で、動作を変えない）か事前確認が必要（数値に影響する可能性がある）に分類し、作者が明示的に承認しない限り、事前確認が必要な項目には手を加えません。

これは汎用的なリファクタリングではありません（パフォーマンス向上のための書き換え、API の「現代化」、それ自体を目的とする再構成は行いません）。目標は、動作を変えずにリリース可能な状態にすることだけです。「クリーンアップ」によってコードの計算内容が変わる場合は、論文の主張を犠牲にしてリポジトリを見栄えよくするのではなく、その変更点を示して確認を求めるのが適切です。

使用する場面

• 「研究コードをリリースに向けてクリーンアップ／リファクタリングしてください。」／「めちゃくちゃなので、公開できる状態にしてください。」
• 「不要な実験分岐とコメントアウトされたコードを削除してください。」
• 「設定をコードから分離してください。」／「ハイパーパラメーターがあちこちにハードコードされています。」
• 「実行を決定論的／再実行可能にしてください。」／「エントリーポイントを文書化してください。」
• 「リポジトリを分かりやすい構成にしてください。」／「ダブルブラインド査読に向けて、身元を示す情報を取り除いてください。」
• test-research-code（テスト／シード／環境を追加）および prepare-artifacts（バッジ用にパッケージ化してホスティング）の前に使います。これらに先立って行う構造のクリーンアップです。

このスキルの対象外（別のスキルを使用）

希望する作業…	使用するスキル
スモークテストを追加し、シードを固定し、環境を記録する	test-research-code
パッケージ化、アーカイブ用 DOI／SWHID、バッジの分類、付録	prepare-artifacts
論文の徹底的なダブルブラインドチェックと、元に戻せる匿名解除	anonymize-paper
生成された数値が論文の表と一致することを確認する	verify-results
論文のセクション／論旨を再構成する	refactor-structure

このスキルでは、シード／環境の不足や身元情報の漏えいを指摘して引き継ぎ、構造のクリーンアップ自体を行います。

入力

1. 研究コードのディレクトリ（リポジトリ、または実験スクリプトを含むサブフォルダー）。このスキルはローカルファイルのみを読み取り、クローンは行いません。
2. 査読がダブルブラインド／シングルブラインド／ブラインドなしのいずれか（身元情報のスキャン方法を決定します）、およびスキャン対象となる身元を特定できる語句（作者名、所属機関、内部コードネームなど）。
3. 任意で .paper-memory/profile.yml（貢献の種類 — system または dataset の論文ではコード品質がより厳しく評価され、再利用可能なリリースが求められます）。
4. 任意で、クリーンアップが特定のものを目的としている場合は対象会場のアーティファクトトラック。ただし、バッジのルールはここではなく、prepare-artifacts が最新の情報を取得します。

最優先事項：数値の振る舞いを厳密に維持する

このスキルが実行するすべての操作は、次の3つのいずれかに分類されます。この境界を厳守してください。

• SAFE — 作者の了承を得て自由に適用可能： README／LICENSE／.gitignore の追加；ファイルを src/／パッケージ構成に移動（その後、インポートを修正）；純粋な不要ファイル（__pycache__、*.pyc、.DS_Store、エディターのスワップファイル）の削除；既存のエントリーポイントの文書化；空白やコメントのみの再フォーマット。これらによってコードの計算結果が変わることはありません。
• ASK-FIRST — 明示的な確認なしに決して変更しない： コードパスの削除（バックアップファイル、コメントアウトされたブロック、if False: 分岐など。切り替え可能な実験や、稼働中のバージョンをひそかにシャドーイングしている可能性があります）；ハードコードされたハイパーパラメーターやパスの設定への切り出し（値を厳密に維持する必要があります）；シード設定、RNG、スレッド／ワーカー数、dtype／精度、評価順序に関わるあらゆる変更（これらが数値を決定します）。それぞれについて、見つかった内容、提案する変更、結果が変わる可能性がある理由を示してから、返答を待ってください。
• IDENTITY — アップロード前に必ず除去する： メールアドレス、ホームディレクトリのパス、作者名、.git 履歴。ここで明示し、詳細な調査は anonymize-paper に任せてください。

変更が安全かどうか判断できない場合は、デフォルトで ASK-FIRST とします。異なる数値を出す見栄えのよいリポジトリは、成功ではなく失敗です。

プロセス

これは、外部の測定可能なシグナル（モデルがリポジトリを「クリーンそう」と感じるかではなく、静的監査）に基づく、計画 → 確認 → 安全な変更の適用 → リスクがある場合の確認、という流れです。前提を明示し、異なる解釈を示し、作者が主導権を保てるようにしてください。

1. まずメモリを読む。 .paper-memory/lessons.md（および profile.yml があればそれも）を読み、作者がすでに修正した内容を省き、作者の recurring な傾向（例：「.git やハードコードされた /home パスを含めたまま公開しがち」）を最初に取り上げます。paper-memory-convention.md を参照してください。

2. 対象範囲とブラインドレベルを確認する。 査読がダブルブラインドか、リリースの目的（公開 GitHub リリース、ブラインド査読用の補足資料、アーティファクトトラック）を確認します。シングルブラインド／非ブラインドのリリースは匿名化しないでください。良好なリポジトリを損ないます。ブラインドの場合は、スキャン対象となる識別情報を確認します。

3. 静的なリリース・リファクタリング監査を実行する（決定論的）。 手作業で grep しないでください。

   python3 scripts/release_audit.py <code-dir> \
       --blind <none|single|double> --names "Jane Doe,Example University"
   # machine-readable:
   python3 scripts/release_audit.py <code-dir> --blind double --json
   

   これはリポジトリを走査し（読み取り専用、実行なし、ネットワークアクセスなし、書き込みなし）、カテゴリ（dead-code、config、entrypoint、layout、determinism、identity、hygiene）と、重要なリスク（SAFE、ASK-FIRST（振る舞いのリスク）、IDENTITY）を付けて検出事項を出力します。フラグ：--strict（検出事項があれば失敗）、--max-files N、--max-bytes N（リポジトリ内の blob のしきい値）。終了コード：0 ask-first／identity の検出事項なし、1 ask-first または identity の検出事項あり、2 使用法エラー。これは計画の根拠となるシグナルです（自己判断ではなく外部チェックです）。監査で示されるのは改善の機会であり、リポジトリが再現可能であることの証明ではありません。

4. 編集する前に、作者が承認するリファクタリング計画を提示する。 検出事項を3つの分類に分け、SAFE → ASK-FIRST → IDENTITY の順に並べます。ask-first の各項目について、変更内容と結果へのリスクを明記します（「この if False: ブロックの削除が安全なのは、あらゆる設定で実行されない場合に限ります。確認してください」）。作者は項目ごとに承認または却下します。カテゴリと安全なリファクタリングの手順については、references/release-refactor-catalog.md を参照してください。

5. SAFE なリファクタリングを適用します（著者の承認を得たうえで）。次の順に進めます。各項目は監査カテゴリに対応しています。

   • レイアウト — README（エントリーポイント、結果ごとの正確な再現コマンド、依存関係、ディレクトリ構成）、LICENSE、.gitignore を追加します。フラットなスクリプト群を src/／パッケージ構成に移し、インポートを修正します。
   • エントリーポイント — パイプラインをエンドツーエンドで実行する、わかりやすいコマンドを1つ文書化するか、実装します（make reproduce／run.sh／python -m pkg）。
   • 衛生管理 — リリース用コピーから __pycache__、*.pyc、.DS_Store、エディターのスワップファイルを削除します。リポジトリ内の大きなデータ／モデルのバイナリは、ダウンロードスクリプトまたはアーカイブ用ホストに移します（後者は事前確認が必須です。バイナリが実行時に必要でないことを確認してください）。

6. 事前確認が必要な項目は、まとめてではなく1つずつ進めます。 承認された変更ごとに、最小限の編集を行い、外部チェックで動作が維持されていることを検証します。目視で差分を確認するのではなく、パイプライン（またはスモークテスト）を再実行し、出力を比較します。動作の維持は再実行によって確認します。これは test-research-code／verify-results の領域です。このスキルは問題を指摘して調整し、変更に本質的なリスクがある場合は作業を止めて確認を求めます。エスカレーションは重要な機能です。特に次の点に注意してください。

   • デッドコード — インポートも参照もされていないことを確認してからに限ります。
   • 設定 — リテラルを設定または CLI に移す場合は、値を完全に同一にします。ここでの誤記は結果を気づかないうちに変えてしまいます。
   • 決定性 — 著者と連携してシードを設定／記録し、順序を固定してから、論文の数値を再確認するために再実行します。シードの追加はシード未設定の実行結果を変えるため、最もリスクの高い編集です。シード／環境の仕組みは test-research-code に引き継ぎます。

7. ブラインド査読に向けて、識別情報の漏えいに対処します。 メールアドレス、ホームディレクトリのパス、名前、.git の履歴を洗い出し、詳細な調査（コミット履歴、ノートブックのメタデータ、自己引用の表現、匿名化したミラー）は anonymize-paper に引き継ぎます。ブラインド投稿では、リポジトリを通じて著者が特定されないようにしてください。

8. 明示的な停止条件を設け、SAFE-clean になるまで監査を再実行します。 SAFE／レイアウト／衛生管理の指摘がなくなり、事前確認が必要な項目がすべて解決済みまたは意識的に保留になるまで、監査 → 修正 → 監査のサイクルを繰り返します。際限なく続けてはいけません。上限は約3回です。監査で同じ事前確認項目が引き続き指摘された場合は、編集を続けるのではなく、判断を仰ぐためにエスカレーションします。

9. リファクタリング計画と変更履歴を paper-workspace/submission/refactor-research-code-plan.md に記載し、 paper-workspace/INDEX.md に1行追記します。 実施内容（安全な変更）を最初に記し、次に事前確認項目の判断（適用／却下／保留。それぞれ結果へのリスクを記載）、最後に識別情報の引き継ぎを記します。各項目について、対応する監査の指摘を引用してください。

出力

• paper-workspace/submission/ に記載するリファクタリング計画（SAFE／ASK-FIRST／IDENTITY の分類ごとに、各指摘の category + risk + file[:line] を記載）と、適用／却下／保留した内容の変更履歴。
• 編集済みのリポジトリファイル（項目ごとの承認がある場合に限る）：README／LICENSE／.gitignore、src/／パッケージ構成、文書化されたエントリーポイント、不要ファイルの削除、著者が確認した事前確認項目の編集。
• 明確な引き継ぎ項目一覧：シード／環境／テスト → test-research-code、パッケージ化／DOI／バッジ → prepare-artifacts、詳細な匿名化 → anonymize-paper、数値と論文の照合 → verify-results。

分野に合わせた調整

監査が読み取るのはディレクトリであり、分野ではありません。そのため、レイアウト／デッドコード／識別情報のチェックは幅広く適用できます。Python 以外のスタックでは、決定性と設定のパターンが異なります（R の set.seed、Julia の Random.seed!、環境用の renv.lock／Manifest.toml など）。スクリプトはいくつかのパターンをすでに認識します。使用する言語に合わせて、scripts/release_audit.py のパターンテーブルを拡張してください。結果を維持するための要件は共通です。リポジトリを整理し、数値は変えないでください。

ガードレール

• 数値の挙動を厳密に維持します。これがすべてです。 明示的な著者の承認なしに、確認を先に求める変更（コードの削除、定数の切り出し、シード処理／スレッド処理／データ型／順序への変更）を行わないでください。また、差分を読むのではなく、再実行によって維持されていることを検証してください（自己省察では自分の誤りも正しいと検証してしまいます。検証は外部で行う必要があります）。
• 変更が安全かどうか判断に迷う場合は、確認を先に求めてください。 見栄えのよいリポジトリでも、異なる数値を報告するなら失敗です。
• 破壊的な操作や信頼できないものの実行は避けてください。 release_audit.py は静的で、読み取り専用であり、ネットワークにも接続しません。挙動の検証のためにパイプラインを再実行するかどうかは著者の判断であり、サンドボックス／GPU が必要になる場合があります。
• 匿名化に配慮してください： 査読を匿名で行う場合、リポジトリや .git の履歴から本人が特定される情報を決して公開しないでください。詳細な確認は anonymize-paper に任せてください。
• 担当範囲を守ってください。 テスト／シード値／環境設定を追加しないでください（それは test-research-code の担当です）。DOI を発行したり、成果物をパッケージ化したりしないでください（それは prepare-artifacts の担当です）。結果が再現されると断言しないでください（それは verify-results の担当です。また、「再現」はビット単位での完全一致を意味することはなく、このスキルが判断することでもありません）。
• 副操縦士であり、操縦士ではありません： 計画を立て、確認を求め、承認を得て編集しますが、著者に代わって投稿、登録、プッシュすることはありません。
• references/ のファイルは 1 階層の深さにとどめ、このファイルは 500 行未満にしてください。

メモリー

共有の .paper-memory/ 規約を使用します（仕様全体： paper-memory-convention.md）。

• 開始時： lessons.md を読み、すでに修正済みのクリーンアップを避け、recurring に記録されたリリース時の習慣（例：「どのリポジトリにも /home/<you> のハードコードされたパスを含めてリリースする」）を最初に伝えます。貢献の種類を確認するため、profile.yml を読みます。
• 終了時： 繰り返し見られる習慣ごとに、正規の形式で日付入りの項目を 1 件ずつ、reflect-and-improve の reflect_log.py を使って追記します。

  python3 ../reflect-and-improve/scripts/reflect_log.py append \
      --memory .paper-memory --skill refactor-research-code --scope recurring \
      --issue "hyperparameters hardcoded across scripts, no config file" \
      --rec "extract to config.yaml/CLI with identical values every release"
  

• 必要に応じて .paper-memory/ を作成し、.gitignore への追加を提案します。ローカル専用で、アップロードも、このリポジトリへのコピーも行いません。