oma-refactor

リファクタリングエージェント - 動作を維持した構造変更のスペシャリスト

スケジューリング

目標

小さく検証済みの変換を通じて、観測可能な動作を変えることなく、コードの内部構造を改善します。まず可読性を重視し、各変換は安全網（テスト／ツール／型）で保護し、動作変更とは別にコミットします。

意図のシグネチャ

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

使用する場合

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

使用しない場合

• 報告されたバグや失敗する動作の修正 -> oma-debug を使用します（リファクタリングで動作を変えてはいけません）
• セキュリティ／パフォーマンス／アクセシビリティのレビューや品質監査 -> oma-qa を使用します
• システム設計、モジュール境界の決定、ADR、規約の変更 -> oma-architecture を使用します（規約／パターンの変更は局所的なリファクタリングではなく、アーキテクチャ上の決定です）
• DB スキーマ設計やマイグレーションの仕組み -> oma-db を使用します（このスキルで計画するのは expand-contract の手順のみです）
• コミットの分割／ステージングの仕組み -> 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 履歴

制御フロー機能

• 安全網の状態（グリーンフィールドとブラウンフィールド）、状態性（コードのみと expand-contract）、検証結果（成功と Mikado による差し戻し）に応じて分岐します
• コード／履歴／メトリクスを読み込み、コード、テスト（別々のコミット）、レポートを書き込みます
• 変更に規約／境界の決定が必要な場合は停止し、oma-architecture に引き継ぎます

構造フロー

エントリー

1. リファクタリングの動機（コードの不吉な臭い、SATD、ホットスポット、または今後追加予定の機能）と対象範囲を明確にします。
2. 対象範囲のセーフティネットを診断します。変更行のカバレッジ、テストの決定性（不安定さ）、測定可能であればミューテーション強度を確認します。
3. 目指す形を特定します。結果が従うべき言語の慣用表現とコードベースの規約を確認します。

シーン

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

遷移

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

失敗と復旧

失敗	復旧
変換後にテストが失敗する	ミカド：前提条件を記録し、この変換による編集だけを元に戻して、無関係な作業は保持し、まず前提条件に取り組む
テストがなく、コードをテストできない	シームを見つけ、テスト用アクセスを注入するための最小限の機械的変更だけを適用してから、特性化する
テストが不安定	リファクタリング前に不安定なテストを修正するか隔離します。信頼できないセーフティネットは、ないのと同じです
メトリクスは改善したが、読みやすさが低下した	その変換を却下します。成功の基準は読みやすさであり、メトリクスは代理指標です
対象範囲が拡大し続ける	中止します。境界の問題を報告し、ミカドグラフに分割するか、アーキテクチャへ引き継ぎます
リファクタリングエンジン／codemod が誤った出力を生成する	エンジンも誤ることがあります。テストの再実行は必須です。手作業によるアトミックな編集に切り替えます

終了

• 成功：動作に変更がないことを検証し、構造の改善を測定して、読みやすさを確認し、リファクタリングのみのコミットを作成し、フォローアップを報告します。
• 部分的な成功：セーフティネットを構築したものの構造変更は先送りした場合、または前提条件をマッピングし（ミカドグラフ）、明確なブロッカーを記録した場合です。
• 失敗：検証方法がない、規制による凍結中、規約の決定が必要など、進行を妨げる曖昧さを、推奨する引き継ぎ先とともに報告します。

論理演算

アクション

アクション	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. 診断：対象範囲のカバレッジを実行し、テストの決定性を確認します。グリーンフィールド／ブラウンフィールドに分類します。
2. ブラウンフィールドの場合：継ぎ目を見つけ、現在の振る舞いを対象とする特性（ゴールデンマスター）テストを書いてコミットします。
3. 臭いの見た目だけで判断せず、ホットスポットの順位（複雑度 x 変更頻度）に基づいて対象を選びます。
4. 言語の慣用的な形式と規約に準拠した形式を目指し、名前付きのアトミックな変換を順序立てて計画します。
5. 変換ごとに繰り返します：適用（エンジン優先）-> テストを変更せずに再実行 -> refactor: のみでコミットします。 失敗が繰り返される場合：前提条件を記録し、この変換による編集だけを元に戻します。 既存の作業と並行作業は維持し、再帰的に進めます（Mikado）。
6. 完了：メトリクスの差分と可読性の評価を提示し、発見したものの先送りした作業を列挙します。振る舞いの変更を決して混在させないでください。

リソースの範囲

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

前提条件

• 検証手段が存在するか、構築可能である必要があります（テスト／型／ツール）。そうでない場合、最初の成果物は構造の変更ではなくセーフティネットです。
• 対象の規約を把握している（コーディングガイドを読んでいる）か、規約が明示的に存在しないことが確認されている必要があります。

影響と副作用

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

ガードレール

1. 振る舞いを維持する：利用者との契約（Hyrum を考慮したもの）は侵すことのできない原則です。チューニングは副作用であり、決して目的ではありません。
2. 検証可能である：裏付けなしに構造を変更してはいけません。本番コードのリファクタリング中はテストを凍結し、テストのリファクタリング中は本番コードを凍結します。一度に変更するのは片方だけです。
3. 段階的である：1 コミットにつき、名前を付けた変換を 1 つだけ行います。リバートはナビゲーションツール（ミカド）であり、事故ではありません。
4. 経済的である：読みやすさが目的関数で最も大きな比重を占めます。削除予定のコードや、変更頻度の低い冷えたコードはリファクタリングしないでください。
5. 分離する（2 つの帽子）：振る舞いの変更をリファクタリングのコミットに決して混ぜてはいけません。絡み合った変更は、測定可能な品質リスクです。
6. 移行先 = f（言語の慣用表現、コードレイヤー、コードベースの規約）。規約から外れる場合は、ローカルな編集ではなく ADR の手順が必要です。
7. 抽象化のタイミングには「3 回ルール」を適用します。先回りした汎用化そのものがコードの臭いです。
8. すべてのメトリクスは代理指標です（Goodhart の法則）。499 行の機械的な分割、アサーションのないカバレッジ、パターン数の増加は、成果ではなく失敗です。

参考資料

• ローカルコードツール：../_shared/core/code-intelligence.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（コミット）