duck-refactor

構造的リファクタリング 🦆。参照を追跡しながら複数ファイルを再構成します。

目的

参照を明示的に追跡・検証しながら、範囲を限定したリファクタリング操作によってコードの再構成を支援します。

方針のガードレール（スキル固有）

references/GUARDRAILS.md の共通ガードレールを継承します。

コメントとドキュメントの整合性

• 長期的に有効な制約、不変条件、契約、動作を記述します。
• コードコメントや通常のドキュメントで開発の経緯を説明しないでください。
• 却下されたアプローチ、「以前はこうだった」という履歴、最近の変更に関する情報、または変更の経緯を説明するだけのレビュー、テスト、セッションへの言及は削除するか、フラグを付けてください。
• セッション限りの判断、承認フラグ、一時的なマーカーを長期的に有効な成果物に残さないでください。
• 履歴に関する情報は、ADR や変更履歴など、履歴を記録する目的の長期的な成果物にのみ残してください。
• テストやレビューへの言及は、長期的に有効な制約または検証要件を示す場合に限り残してください。

スキル固有の追加事項：

• 複数ファイルにまたがるリファクタリング操作には、すべての参照を追跡したうえで実行承認が必要です。
• 単一ファイルのパッチや複雑さの削減とは区別してください。

起動条件

ユーザーがリファクタリング、抽出、ファイル横断での名前変更、コードの移動、インライン化、パターンの変換を依頼した場合に使用します。

起動フレーズ：

• 「これをリファクタリングして」
• 「この関数／クラス／メソッドを抽出して」
• 「これをコードベース全体で名前変更して」
• 「これを別のファイルに移動して」
• 「この関数をインライン化して」
• 「このコールバックを Promise に変換して」

手順

サブエージェント実行モード

ユーザーチャネルを持たないサブエージェントとして実行する場合（例：duckling 経由）、編集や検証コマンドを実行しないでください。手順 1～5 は分析として実行し、手順 6「リファクタリングを実行」と手順 7「検証」は、承認パッケージの内容、すなわちファイルごとの変更計画（該当する場合は diff ブロックを含む）と検証計画に置き換えてください。ホストラッパーの仕様に従って出力してください（事前確認＋diff＋承認依頼＋ステータスフッター）。

1. リファクタリングの範囲を明確にする

• コンテキストが不十分な場合は、焦点を絞った確認質問を1～3個行います。
• 根拠が不足している場合は、前提を明示します。

詳細が不明な場合は、範囲を明確にする質問を1つ行います。

• 何を抽出／名前変更／移動／インライン化しますか？
• 移動先はどこですか（新しいファイル、既存のファイル、新しい関数名）？
• 範囲の境界はどこですか（このモジュール、コードベース全体）？

2. 参照と依存関係を追跡する

読み取り専用の根拠収集を行います（duck-debug のトレースモードと同様）。

• 対象コードのすべての使用箇所を特定します
• インポート／エクスポートをマッピングします
• 呼び出し元と呼び出し先を特定します
• 対象を参照するテストファイルを検索します
• 外部依存関係を記録します

出力：「M 個のファイルにまたがる N 個の参照が見つかりました：[一覧]」

3. リファクタリング計画を提示する

編集を行う前に、範囲を限定した計画を提示します。

形式：

Refactoring plan:
- Operation: [extract function / rename / move / inline / convert]
- Target: [current name/location]
- Destination: [new name/location]
- Target phase: [Phase 1 stubs/interfaces | Phase 2 wiring/integration | Phase 3 concrete implementation]
- Files affected: [bounded list for selected phase]

Changes:
1. [file A]: [change description]
2. [file B]: [change description]

Verification: [tests to run, imports to check]

フェーズの上限またはレビュー疲れのしきい値を超える場合：「このリファクタリングは現在のフェーズの範囲を超えています。より小さく範囲を限定したリファクタリングに分割しますか？」

4. Duck Ladder を適用する

リファクタリングのアプローチを提案する前に：

1. 変更不要（YAGNI）
2. 既存のローカルヘルパー／パターンを再利用する
3. 標準ライブラリ／ネイティブ機能に置き換える
4. すでにインストールされている依存関係を使う
5. 安全な範囲で差分を最小限にする
6. その後にのみ、新しいコード／抽象化を追加する

次のように尋ねます：「既存のコード／パターンですでに解決できませんか？再構成せずに再利用できますか？」

5. 実行承認を得る

リファクタリングを実行する前に、以下を提示します。

• 対象フェーズ（Phase 1/2/3）
• 対象ファイル（選択したフェーズ内に限定）
• 想定する構造変更（何をどこに移動するか）
• 検証計画（テスト、インポート、型チェック）

実行承認フローを使用します。

• Reply with "approve" to execute this refactoring.
• 明示的な承認を待ちます
• 承認なしに複数ファイルにまたがるリファクタリングを進めないでください

6. リファクタリングを実行する

承認後：

1. 順番に変更します（定義を使用箇所より先に、インポートをコードより先に）
2. インポート／エクスポートを更新します
3. 一貫したフォーマットを維持します
4. 永続的な制約、不変条件、契約、動作を記録する、正確なコメントとドキュメントを保持します。リファクタリングによって明らかになった開発時の説明や、そのセッション限りの判断への言及は書き換えます。

7. リファクタリングを検証する

検証計画を実行します：

• テストが引き続き合格すること
• 壊れたインポートがないこと
• 型チェッカーが合格すること（該当する場合）
• 機能が変わっていないこと

報告：「リファクタリングが完了しました。検証結果：[テスト結果]。[N] 個のファイルを変更しました。」

範囲

他のスキルとの違い：

• duck-patch との違い：duck-refactor は複数ファイルの構造変更、duck-patch は単一ファイルのバグ修正です
• duck-simplify との違い：duck-refactor は中立的な構造変更、duck-simplify は明確な目標を定めた複雑さの低減です
• duck-design との違い：duck-refactor は実装、duck-design は判断やトレードオフの分析です
• duck-debug との違い：duck-refactor はコードを変更し、duck-debug は追跡・調査のみを行います

duck-refactor が行わないこと：

• 構造変更を伴わない単一ファイルの編集 → duck-patch を使用します
• 主な目的が複雑さの低減であること → duck-simplify を使用します
• アーキテクチャ上の判断 → duck-design を使用します
• コードを変更せずファイルを移動するだけの作業 → duck-patch を使用します

範囲の制限：

• フェーズごとの上限（デフォルト）：フェーズ 1 は最大 6 ファイル、フェーズ 2 は最大 4 ファイル、フェーズ 3 は最大 2 ファイル

• フェーズごとの上限を超えた場合、またはレビュー疲れのトリガーに該当した場合は、より小さな範囲に分けて承認を得ます

• リファクタリングに設計上の判断が必要な場合は、一時停止して、まず duck-design に引き継ぎます

• リファクタリングで複雑さの問題が見つかった場合は、duck-simplify での対応事項として記録します

• 変更によって信頼境界の検証、セキュリティ制御、データ損失防止、アクセシビリティ要件、または明示されたユーザー要件が損なわれる場合は、その変更を拒否し、制約を維持する安全な代替案のみを提示します。