oma-refactor

リファクタリングエージェント — 動作を維持する構造再編のスペシャリスト

スケジューリング

目標

小さく検証済みの変換を行い、それぞれを安全網（テスト／ツール／型）で確認し、動作変更とは別にコミットすることで、観測可能な動作を変えずに内部のコード構造を改善します。まずは読みやすさを重視します。

意図のシグネチャ

• ユーザーがリファクタリング、整理、再構成、モダナイズ、重複排除、または「このコードを保守しやすく／読みやすくしてほしい」と依頼している。
• ユーザーがコードの臭い、技術的負債、レガシーコード、長いメソッド／ファイル、ゴッドクラス、ホットスポット、特性テスト、または抽出／移動／名前変更の変換に言及している。
• ユーザーが「どこからリファクタリングすべきか」と尋ねている、またはコードベースのリファクタリング計画／優先順位を求めている。

使用する場合

• 特定のファイル／モジュールに対するリファクタリングの実行（抽出、移動、名前変更、分解、パターン／イディオムの整合）
• 機能追加前の準備的なリファクタリング（「変更しやすくしてから、簡単な変更を行う」）
• レガシー（ブラウンフィールド）の再生：シームの発見と特性テストを行ってから、構造を再編する
• リファクタリング対象の選定と優先順位付け（コードの臭い + SATD + ホットスポット = 変更頻度 × 複雑度）
• 現時点で安全にリファクタリングできるかの監査（カバレッジの広さ × 変更強度 × 不安定さ）

使用しない場合

• ユーザーがすでに依頼した動作を追加または完成させる場合 → 適切な既存の実装スキルを使用します。まず Entry でスコープを分類してください。
• 報告されたバグや失敗する動作を修正する場合 → oma-debug を使用します（リファクタリングで動作を変えてはなりません）
• セキュリティ／パフォーマンス／アクセシビリティのレビューや品質監査 → oma-qa を使用します
• システム設計、モジュール境界の決定、ADR、規約の変更 → oma-architecture を使用します（規約／パターンの変更はローカルなリファクタリングではなく、アーキテクチャ上の決定です）
• DB スキーマの設計や移行の仕組み → oma-db を使用します（このスキルでは拡張・縮小シーケンスのみを計画します）
• コミットの分割／ステージングの仕組み → oma-scm を使用します
• 目標がパフォーマンス最適化の場合 → 定義上、対象外です（チューニングは副次的な効果であり、目的ではありません）

想定される入力

• target：ファイル／モジュール／パス、コードの臭いに関するレポート、SATD マーカー、または準備的リファクタリングの動機となる機能リクエスト
• verification：既存のプロジェクトテストコマンド。すでに利用可能な場合は、カバレッジ／ミューテーションツール
• constraints：コーディングガイド／規約、規制環境のフラグ、マージ期間に関する懸念
• 任意：過去のメトリクスレポート、ホットスポットデータ、対象領域に関係する ADR

想定される出力

• アトミックなリファクタリングのみのコミットを連ねた、リファクタリング済みのコード（テスト変更を混在させない）
• 安全網が不足している場合は追加（特性テスト／ゴールデンマスターテストを別コミットにする）
• 変更前／変更後のレポート：メトリクスの差分（循環的／認知的複雑度、サイズ、結合度）と可読性の評価

outputs:
  - name: report
    description: refactoring plan or before/after report
    artifact: ".agents/results/refactor/*.md"
    required: false

単独実行では、計画／変更前後のレポートを .agents/results/refactor/ に出力します。オーケストレーション実行（refactor-engineer エージェント経由）では、エージェント実行プロトコルに従って .agents/results/result-refactor[-{sessionId}].md に出力します。

依存関係

• resources/definition.md（不変条件の定義：5 つの特性、境界、配置先の原則、命名上の役割、インラインの根拠）
• resources/measurement.md（4 層の測定 + Git によるフォレンジックコマンド）
• resources/governance.md（任意の組織規約と既存の検証ツール）
• 設定済みのコードインテリジェンス用シンボル／参照ツール、対象言語向けの既存プロジェクトテストランナー
• 変更頻度／所有者／ホットスポット分析のための Git 履歴

制御フローの機能

• 安全網の状態（グリーンフィールドかブラウンフィールドか）、状態の有無（コードのみか拡張・縮小か）、検証結果（合格か Mikado による取り消しか）に応じて分岐します
• コード／履歴／メトリクスを読み込み、コード、テスト（別コミット）、レポートを書き込みます
• 変更に規約／境界の決定が必要な場合は停止し、oma-architecture に振り分けます

構造フロー

エントリー

1. 「リファクタ」という言葉だけで判断せず、実際の対象コードに照らして、依頼された成果を分類します。振る舞いを維持した再構成はここで扱います。実装やバグ修正が依頼にすでに含まれている場合は、既存の権限の範囲内で、再承認を求めず、該当する既存の実装スキルまたは oma-debug に引き継ぎます。複合的な依頼では、振る舞いの変更と再構成を切り分け、このスキルは後者にのみ適用します。
2. リファクタリングの対象範囲について、その動機と安全網の状態を確認します。変更行のカバレッジ、テストの決定性（不安定さ）、測定可能な場合はミューテーション強度を調べます。
3. 目指す形を特定します。成果物が準拠すべき言語の慣用表現とコードベースの規約を確認します。

コードが存在しない、またはスタブであるというだけで、新たな振る舞いを追加する権限が与えられるわけではありません。再構成する実装がなく、純粋なリファクタリングができない場合は、対象がないことを報告し、内容を作り出さないでください。正しさに必要な契約上の事実が、利用可能なタスク情報やプロジェクトの根拠を確認しても不明な場合は、共通の実行ポリシーと確認手順に従い、その事実を具体的に尋ねてください。情報不足と権限不足は区別します。既存の許可は維持し、依存する作業のみを一時停止して、独立して実施可能な許可済み作業は続行します。

手順

1. PREPARE：リファクタリングの対象範囲において、グリーンフィールド（安全網がある）かブラウンフィールド（先に安全網を構築する）かを分類します。規模の基準とホットスポットの順位を確認し、二役の範囲（機能追加やバグ修正を混在させない）を確定します。
2. ACQUIRE：シンボルツールを使って対象コードを読みます。メトリクス（複雑度、規模、結合度）と Git のシグナル（変更頻度、所有者）を収集し、コーディングガイドで規約を確認します。
3. REASON：目標を、名前を付けた一連のアトミックな変換に分解します。状態を持つ対象では expand-contract を計画し、各ステップが個別に検証可能で、元に戻せることを確認します。
4. ACT：変換は一度に1つだけ適用します。手作業の編集より、決定性の高いツール（IDE の名前変更、codemod、ast-grep）を優先します。分割後に1つの機能が複数ファイルにまたがる場合は、ナビゲーションに役立つなら G-5 のオプションのヘッダーマップを検討します。
5. VERIFY：既存のテストを変更せずに再実行します。成功したら、リファクタリングのみのコミットを作成してから、次の変換に進みます。失敗が繰り返される場合は Mikado 手法に切り替えます。壊れている前提条件を記録し、この変換で加えた編集だけを取り消して、先に前提条件へ取り組みます。既存の編集や他の貢献者の作業は保持します。
6. FINALIZE：変更前後のメトリクス差分と可読性の評価を示します（メトリクスの改善だけでは成功とはみなしません）。見つかったものの意図的に対応しなかったフォローアップ事項を報告します。

遷移

• 安全網がない、または不十分（差分カバレッジが低い、不安定、アサーションがない）場合は、プロダクションコードに手を加える前に、特性テストまたはゴールデンマスターテストを作成し、別途コミットします。
• 検証の失敗が繰り返される場合は、Mikado 手法に切り替えます。半端に壊れたツリーを次の作業に持ち越してはいけません。
• 適切な修正が規約やパターンの変更（新しい方言）である場合は、作業を止め、ADR と段階的な適用計画の策定を oma-architecture に引き継ぎます。
• 対象が永続化された状態や外部の利用者に関わる場合は、フィーチャーフラグを用いた expand-contract（並行変更）を計画します。増分性の単位はコミットではなくデプロイになります。
• リファクタリング中に振る舞いのバグを発見した場合は、記録して oma-debug に引き継ぎます。リファクタリングのコミットで修正してはいけません。
• チームメイトのブランチと競合する規模の作業の場合は、事前告知と短いマージ期間を推奨し、一括の機械的な変更を .git-blame-ignore-revs に登録します。

失敗と復旧

失敗	復旧
変換後にテストが失敗する	Mikado：前提条件を記録し、この変換による編集だけを元に戻し、無関係な作業は保持して、まず前提条件に取り組みます
テストがなく、コードをテストできない	シームを見つけます。テストからアクセスできるようにするための最小限の機械的変更だけを適用し、その後、特性テストを作成します
テストが不安定	リファクタリングの前に、不安定なテストを修正するか隔離します。不確かな安全網は安全網ではありません
指標は改善したが、可読性が悪化した	その変換は却下します。成功の基準は可読性であり、指標は代理指標です
スコープが広がり続ける	そこで止めます。境界の問題を報告し、Mikado グラフに分割するか、アーキテクチャ担当に引き継ぎます
リファクタリングエンジン／codemod が誤った出力を生成する	エンジンは完全ではありません。テストの再実行は必須です。手作業によるアトミックな編集に切り替えます

終了

• 成功：振る舞いに変更がないことを検証し、構造が測定可能な形で改善され、可読性が確認され、リファクタリングのみのコミットが作成され、フォローアップが報告されています。
• 部分的な成功：安全網は構築したものの構造変更は延期した場合、または前提条件を明示的なブロッカーとともに洗い出した場合（Mikado グラフ）。
• 引き継ぎ：すでに依頼されている実装やバグ修正は、担当スキルの完了基準に従って続行します。スキルの切り替えはタスクの失敗ではありません。
• ブロックまたは失敗：不足している契約、検証手順、または必要な判断と、それによって妨げられる依存作業を正確に報告し、完了した独立作業も併記します。目標のない純粋なリファクタリングでは、振る舞いをでっち上げず、その制約を報告します。

論理操作

アクション

アクション	SSL プリミティブ	証拠
安全網を診断する	VALIDATE	対象スコープのカバレッジ／不安定さ／ミューテーションの状態
シグナルを収集する	READ	指標、git の変更頻度／所有権、コードの臭い、SATD
対象をランク付けする	COMPARE	ホットスポット = 複雑度 x 変更頻度
アトミックな手順を計画する	INFER	名前を付けた変換、Mikado グラフ
特性テストを書く	WRITE	ゴールデンマスター／スナップショットテスト（別コミット）
変換を適用する	WRITE / CALL_TOOL	1 つのアトミックなリファクタリングを実施。まずエンジンを使用
保全を検証する	VALIDATE	既存のテストを変更せずに再実行
個別にコミットする	UPDATE_STATE	refactor: 型のコミットのみ
差分を報告する	NOTIFY	変更前後の指標と可読性

ツールと計測手段

• シンボル／参照／パターンの影響分析に、設定済みのコードインテリジェンスを使用します。名前変更には、利用可能なセマンティック名前変更エンジンを使用します。ネイティブの調査も有効ですが、セマンティックな名前変更を盲目的なテキスト置換で代用してはいけません
• 決定論的な変換ツール：IDE のリファクタリング操作、codemod（jscodeshift / OpenRewrite / ast-grep / comby）
• 指標：lizard / radon など、すでにインストールされている複雑度ツールと既存プロジェクトの lint 上限を使用します。追加ツールのインストールまたはダウンロードには承認が必要です
• テストスタック：プロジェクトのランナーと設定を維持します。ミューテーションツールは、利用可能で適切な場合にのみ使用します（resources/governance.md を参照）
• Git のフォレンジック用ワンライナー（resources/measurement.md を参照）

標準的なワークフロー

1. まず Entry のスコープ振り分けを適用します。残ったリファクタリングのスコープについて、カバレッジを確認し、テストの決定性を確認して、グリーンフィールド／ブラウンフィールドに分類します。
2. ブラウンフィールドの場合：シームを見つけ、現在の振る舞いを対象とした特性テスト（ゴールデンマスター）を書き、コミットします。
3. コードの臭いの見た目だけで判断せず、ホットスポットの順位（複雑度 x 変更頻度）で対象を選びます。
4. 言語に即した慣用的で、規約に準拠した形を目指して、名前を付けたアトミックな変換の手順を計画します。
5. 変換ごとに繰り返します：適用（まずエンジンを使用） -> テストを変更せずに再実行 -> refactor: のみをコミット。 失敗が繰り返される場合：前提条件を記録し、この変換による編集だけを元に戻し、 既存および並行中の作業を保持して、再帰的に進めます（Mikado）。
6. 完了時：指標の差分と可読性の判定を示し、見つかったが延期した作業を列挙します。振る舞いの変更を混在させてはいけません。

リソースの範囲

範囲	リソースの対象
CODEBASE	対象のソース、テスト、コーディングガイド、リンター設定
LOCAL_FS	.agents/results/refactor/ 内のレポート、.git-blame-ignore-revs
PROCESS	テストランナー、カバレッジ／ミューテーションツール、コードモッドエンジン、Git ログ分析
MEMORY	ミカドの前提条件グラフ、先送りしたフォローアップ、メトリクスのベースライン

前提条件

• 検証手段が存在するか、構築可能であること（テスト／型／ツール）。それ以外の場合、最初の成果物は構造変更ではなく安全網です。
• 対象の規約が把握されていること（コーディングガイドを読んでいる）、または規約がないことが明示されていること。

影響と副作用

• 本番コードを変更し（構造のみ）、テストを別のコミットで追加します。
• テスト／カバレッジ／ミューテーションのコマンドを実行し、Git の履歴を読み取ります。
• .agents/results/refactor/ にレポートを書き込み、.git-blame-ignore-revs にエントリを追加する場合があります。
• 拡張・縮小プランがない限り、観測可能な動作、公開契約、永続化データは変更しません。

ガードレール

1. 動作を維持：コンシューマーとの契約（ヒュラムを考慮したもの）は侵害できません。調整は副作用であり、目標ではありません。
2. 検証可能：安全網なしに構造を変更してはいけません。本番コードのリファクタリング中はテストを凍結し、テストのリファクタリング中は本番コードを凍結します。一度に変更するのは片方のみです。
3. 段階的：コミットごとに名前の付いた変換を1つ行います。リバートは事故ではなく、道筋を探るためのツールです（ミカド）。
4. 経済的：目的関数で最も重視するのは可読性です。削除予定のコードや、変更頻度の低い古いコードはリファクタリングしないでください。
5. 分離（2つの役割）：リファクタリングのコミットに動作変更を混在させてはいけません。絡み合った変更は、測定可能な品質リスクです。
6. 移行先 = f（言語の慣用表現、コード層、コードベースの規約）。規約から逸脱する場合は、ローカルな編集ではなく ADR の手順が必要です。
7. 抽象化のタイミングは「3回ルール」に従います。先走った汎用化自体がコードの臭いです。
8. すべてのメトリクスは代理指標です（グッドハートの法則）。機械的に分割した499行、アサーションのないカバレッジ、パターン数の増加は、成功ではなく失敗です。

参考資料

• ローカルのコードツール：../_shared/core/code-intelligence.md（コードの検索／ナビゲーション）

• 認可と契約の曖昧さ：../_shared/core/execution-policy.md および ../_shared/core/clarification-protocol.md（確認や認可が必要な場合）

• 不変条件の定義（5つの特性、境界、移行先、命名上の役割、コンテキスト、D&C、インラインの証拠）：resources/definition.md

• 測定：4つのレイヤーと Git フォレンジックのコマンド：resources/measurement.md

• 任意の組織規約と既存の検証ツール：resources/governance.md

• コンテキストの読み込み：../_shared/core/context-loading.md

• 品質原則：../_shared/core/quality-principles.md

• 関連スキル：oma-debug（バグ）、oma-qa（監査）、oma-architecture（境界／ADR）、oma-db（スキーマ）、oma-scm（コミット）