large-file-refactor について
large-file-refactorは、大きなファイルを調査し、分割の妥当性を評価する開発スキルです。コードベースの保守担当者向けに、行数だけでなく責務のまとまり、結合度、変更リスク、テスト容易性に基づく計画を作成します。
主な機能
- 01閾値を超えるソース・テストファイルの検索
- 02候補を網羅したレポートの作成
- 03凝集性とリスクに基づく分割評価
- 04移行手順と検証方法の計画
- 05生成物・ベンダーコードの対象化
活用シーン
- 01コードベース内の大規模ファイルの把握
- 02複雑なモジュールを分割するかの評価
- 03レビュー可能なリファクタリングとテストの計画
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/large-file-refactorを入力して読み込まれたか確認します。
同梱ファイルagents/openai.yamlscripts/large-file-refactor.py
詳細
大容量ファイルのリファクタリング
このスキルは調整の対象外です。宣言された作業では ai-coord ゲートをスキップしてください。
スラッシュまたはドル記号による呼び出しですでにこれらの指示が会話に追加されている場合は、そのまま従ってください。その場合、このスキルをスキルツールから再度呼び出さないでください。
LOC のしきい値を使って候補を見つけた後、凝集度、結合度、所有権、変更リスクに基づいて分割が妥当かどうかを判断します。ソースファイルは 1000 LOC を超えるものが対象です。テストファイルでは、検出のしきい値を緩和して 2000 LOC とします。
引数
path：スキャンするファイルまたはディレクトリ。省略した場合は、現在の作業ディレクトリです。--include-generated：デフォルトでスキップされる生成物、ベンダーコード、依存関係、ビルド出力のパスを含めます。
ワークフロー
-
スキルのディレクトリを解決し、対象のリポジトリからヘルパーを実行します。
uv run "<skill-dir>/scripts/large-file-refactor.py" [path] [--include-generated] -
ヘルパーが出力する Markdown テーブルを、網羅的なレポートとしてそのまま保持します。リファクタリング計画が一部の候補だけを扱う場合でも、一致した行を省略しないでください。
-
ヘルパーがしきい値に一致するものはないと報告した場合は、レポートの後で終了します。一致したファイルは候補であり、分割すべきことの証明ではありません。
-
ユーザーが別の件数を明示的に要求していない限り、最大の 3 ファイルのみを対象にリファクタリング計画を作成します。
-
候補ごとに、複数の責務、変更頻度／リスク、結合度、テスト容易性に基づいて分割の価値を順位付けします。利用可能なセマンティックシンボル／参照ツールを使用してください。Serena がインストールされている場合は、優先して使用します。
- シンボルの概要、参照、インポート、関連する履歴を調べます。
- 得られた根拠を使って、抽出境界、対象モジュール名、移行順序、テスト範囲を決定します。
-
このワークフローのデフォルトは、レポートと計画の作成です。ユーザーの依頼ですでに実行が許可されている場合、またはユーザーが後から承認した場合に限り、実装してください。変更されていない、すでに許可済みの成果について、別途依頼を求めないでください。
リファクタリング計画の形式
選択したファイルごとに、以下を記載します。
- 現在の役割：ファイルが担っていると思われる責務と、行数の多さがなぜ症状なのか。
- セマンティック調査：コードを移動する前に実施する、具体的なシンボル／参照／履歴の調査。
- 分割案：責務を割り当てた 2～5 個の対象モジュールまたはファイル。
- 移行順序：公開動作を維持する、小さくレビューしやすい手順。
- 検証：分割を裏付ける、対象を絞ったテスト、型チェック、ビルド、またはスモークチェック。
各計画の先頭には、次のいずれかの明確な判定を 1 つ記載します：### ✂ Split justified、### 🧱 Keep intact、または
### ⚠️ Generated — change the generator。繰り返し適用する評価基準には、簡潔な根拠テーブルを使用します。分割を提案する場合、所有権の説明に役立つ場合に限り、ソースモジュールと対象モジュールをツリー形式で示します。
--include-generated の使用により、選択したファイルが生成物またはベンダーコードの場合は、生成された出力を手作業で分割するのではなく、ジェネレーター、スキーマ、またはアップストリームのソースを対象に計画します。
ガードレール
- サイズの順位付けに限り、テーブルを基準として扱います。リファクタリングの優先度は別途順位付けしてください。
- 計画の凝集度を保ちます。行数を減らすことだけを目的に分割しないでください。
- 既存のプロジェクトのモジュール境界と命名規則を優先します。
- ヘルパーが
tokeiの代わりに移植可能な LOC 推定値を使用した場合は、その旨を報告します。
完了
しきい値に該当するファイルの網羅的なレポートと、凝集度または変更リスクから分割が妥当と判断された候補に限る、根拠に基づいて順位付けした計画を提示して完了します。先頭に ### 🔎 Large-file scan — <candidate count> を記載し、大きなファイルをそのままにすべき場合は、その理由を述べます。移植可能な LOC 推定値にフォールバックした場合は、⚠️ Approximate counts として明示します。ヘルパーの網羅的なテーブル、パス、LOC 値、コマンドは、正確なまま装飾を加えずに保持します。