qa-refactoring

QA リファクタリング

このスキルを使用して安全にリファクタリングします。動作を維持し、リスクを軽減し、保守性とデリバリー速度を向上させながら CI を成功させ続けます。

デフォルトでは、まずベースラインを確認し、次に最小限で安全なステップを選び、直感ではなくテスト／コントラクト／可観測性によって裏付けます。

クイックスタート（10 分）

• 重要なコンテキストが不足している場合は、変更してはならないもの（不変条件）、リスクレベル（決済／認証／マイグレーション／並行処理）、デプロイの制約、テストで保護できる最小の境界について確認します。
• 対象ブランチで CI が成功していることを確認し、維持すべき動作を再現します。
• 境界を選びます。API サーフェス、モジュール境界、DB 境界、リクエストハンドラー、または codemod の影響範囲です。
• セーフティネットを追加します。その境界に特化した特性化テスト／コントラクトテスト／統合テストを用意します。
• 小さなステップでリファクタリングします。コミット／PR の各チャンクで、動作を維持する変更を 1 つだけ行います。
• 裏付けを確認します。維持する動作ごとに、オラクルと実行レイヤーを対応付けます。可能であれば、そのオラクルが誤った動作や削除された動作では失敗し、リファクタリング後は成功することを示します。まず関連する最小限のテストスイートをローカルで実行し、その後 CI 全体を実行します。失敗は決定的で、十分な成果物を伴うものにします。

ワークフロー

1. セーフティネット、境界、ロールバック方法を確立します。
2. リファクタリング戦略と、最小の変更単位を選びます。
3. 変更を行い、動作を検証します。安全性の基準が許容できるリスクを下回った場合は中止します。
4. その作業中にスコープを広げず、次の変更単位を記録します。

QA の基本（デフォルト）

安全なリファクタリングのループ（動作優先）

• 対象ブランチのベースラインを確立し、維持すべき動作を再現します。
• 不変条件を定義します。入出力、エラーの種類、権限、データの形状、パフォーマンス予算を含めます。
• セーフティネットを追加します。変更対象の境界に対する特性化テスト／コントラクトテスト／統合テストを作成します。
• 境界を作ります。注入ポイント／アダプターを導入して、副作用と外部依存関係を分離します。
• 小さなステップでリファクタリングします。一度に行うのは動作を維持する変更 1 つだけにし、差分をレビューしやすい状態に保ちます。
• 裏付けを確認します。コンパイル／型チェック／静的解析の成功と、実際に実行した動作を区別します。また、対象を絞ったリグレッションテストの成功とリリース準備の完了も区別します。データ、並行処理、タイミング、またはロールアウトに影響される経路について、引き続き必要なランタイムチェックや本番環境に近いチェックを記録します。
• 安全にリリースします。本番環境の重要な経路に影響するリファクタリングでは、カナリア、シャドウモード、マイグレーションフラグ、または抽象化によるブランチ切り替えを使用します。

リスクレベル（セーフティネットを選ぶ）

リスク	例	最低限必要なセーフティネット
低	名前変更、メソッドの抽出、フォーマットのみ	単体テスト＋リンター／型チェック
中	モジュール間のロジック移動、依存関係の逆転、影響範囲を限定した codemod	境界に対する単体テスト＋統合テスト／コントラクトテスト
高	認証／権限の経路、並行処理、マイグレーション、決済／データ損失の経路、大規模な自動書き換え	統合テスト＋コントラクトテスト、可観測性チェック、ロールアウト＋ロールバック計画

リファクタリングのテスト戦略

• 動作を維持するには、境界に対するコントラクトテストと統合テストを優先します。
• スナップショット／ゴールデンマスターは、出力が安定していてレビューされている場合に限って使用します（「すべて承認する」ループは避けます）。
• 不変条件には、プロパティベーステストやテーブル駆動のケース（入力、エッジケース、エラーの種類）を検討します。
• リファクタリングの主要なセーフティネットとして E2E／UI テストに依存することは避け、ほとんどの安全性を UI より下の層で確保します。
• 不安定な領域では、結果を信頼する前に、まず決定性を確保します（シード、時刻、順序、ネットワーク）。
• API とサービスの境界では、場当たり的なエンドツーエンドのテスト範囲よりも、明示的なコントラクトテストを優先します。
• 自動書き換えでは、リポジトリ全体に拡大する前に、差分の一部を手動で確認します。

CI のコストとデバッグのしやすさ

• リファクタリングの PR は小さく、レビューしやすい状態に保ちます。リファクタリングと機能追加を 1 つの PR にまとめることは避けてください。
• リファクタリングを保護するテストでは、失敗時の成果物（ログ、トレース ID、再現性のあるシード値、再現手順）を必須にします。
• 差分のノイズを減らします。書式変更のみの変更は分離するか、合意を得てからリポジトリ全体に一度だけ書式を適用します。
• git bisect を使える状態に保ちます。必要な場合を除き、「機械的な変更＋意味的な変更」を混在させないでください。
• コードモッドでは、まずドライランを実行してから、失敗時に停止する手順で一括実行します。

推奨事項と避けるべきこと

推奨事項：

• リスクの高い領域をリファクタリングする前に、不足しているテストを追加します。
• リファクタリングによってインターフェースが気付かないうちに壊れないよう、ガードレール（リンター、型チェック、コントラクトチェック、静的解析／セキュリティチェック）を追加します。
• 実装を安全に切り替える必要がある場合は、「抽象化による分岐」やアダプターを優先します。
• 多数のファイルを変更する場合は、正規表現による編集より、コンパイラー対応や AST 対応のリファクタリングを優先します。
• 「手作業で変更した行数が約 500 行を超える」ことを、同じ自動化か手作業かの判断を促す 2 つ目の行数基準として扱います。この判断は、references/automated-refactoring-tools.md のファイル数表ですでにファイル数を基準に示されています。リファクタリングでは、一方の基準だけに達し、もう一方には達しないことがあります（2,000 行のファイルが 1 つだけの場合もあれば、機械的な名前変更を 600 ファイルに適用しても、各ファイルの変更が数行だけの場合もあります）。ファイル数だけでなく、両方の基準を確認してください。

避けるべきこと：

• 大規模な構造的リファクタリングと動作変更を組み合わせること。
• リファクタリングの主な安全策として、不安定な E2E テストを使うこと。
• 任意の規模の基準を自然の法則のように扱うこと。上記のファイル数と行数の基準は、「コードモッドを使うべきか」を検討するためのレビュー上の目安としてのみ使い、厳格なゲートとしては扱わないでください。判断すべきなのは、この規模で手作業で編集するより自動化した方が安全かどうかであり、数値に従っているかどうかではありません。

行数の基準は、addyosmani/agent-skills（MIT）の commit 7676817、2026-08-09 を参考にしています。

専門家の判断：チェックリストでは見落とすこと

リファクタリングしない方がよい場合

リファクタリングは投資判断であり、道徳的な義務ではありません。投資判断と同じように、その価値を見極めてください。

• 開始する前に、リファクタリングで得られるもの（開発速度、不具合の削減、特定の機能の実装を可能にすること）と、かかるコスト（時間、レビュー負荷、リグレッションのリスク）を比較します。「このコードは見た目が悪い」というだけでは、ビジネス上の根拠になりません。
• 安定していて変更頻度が低く、廃止または置き換えが予定されているコードはリファクタリングしないでください。削除しようとしているコードのクリーンアップは無駄です。投資する前に、移行ロードマップを確認してください。
• 生の LOC や見た目への不満ではなく、ホットスポット（変更頻度 × 複雑さ）を基準に優先順位を付けます。誰も触らない雑然とした関数より、各スプリントで変更される平均的な関数の方が優先度は高くなります。
• Kent Beck による Tidy First?（2023）の考え方に従います。これから行う変更で、差分を小さくする、リスクを下げる、または作業の本質を明らかにするなど、整理の効果がコストを上回る場合にのみ、先に整理してください。必要な変更を実現する助けにならない整理は、ついでにまとめるのではなく、レビュー対象となる独立した低リスクのコミットに分けて、後回しにします。
• ストラングラーフィグ移行により、現在のロードマップ期間内にこのモジュールが置き換えられる場合は、なくなるコードの内部を深くリファクタリングするのではなく、移行に向けた境界部分と特性テストに投資してください。

特性テスト優先の規律

• 「このコードは理解している」は安全網にはなりません。思い込みだけで済ませず、テストを書いてください。関数を実行せずに、最も難しい3つの入力に対して何を返すか説明できないなら、特性テストを省略できるほど十分に理解していません。
• 特性テストでは、バグも含めて動作を記録します。特性を記録する際に、黙ってバグを修正しないでください。見つかったバグは別途記録し、修正のタイミングやリファクタリングとの順序はプロダクトオーナーに判断してもらいます。
• 削除に関しては、チェスタトンの柵の原則が当てはまります。未使用または誤りに見えるコードを削除する前に、git blame／git log -pで該当行を調べ、追加したコミットと関連するチケット／PRを特定し、理由を説明するコメントがないか確認してください。柵が設けられた理由を説明できてから削除してください。現時点で理由が見当たらないというだけでは不十分です。

動作を維持するための検証戦略

• 最も低コストなものから段階的に検証します。型チェック → リント → 単体テスト／特性テスト → コントラクトテスト／統合テスト → 変更箇所の境界に対するミューテーションスコアのゲート → 本番環境で重要な経路のカナリア／シャドー検証です。より低コストの段階で同種のリグレッションを検出できていたと分かった時点で、対象範囲を広げるのを止めてください。
• 意図した動作変更を伴わないリファクタリングでは、レビューで問うべきなのは「良いコードか」ではなく、「観測可能な変化がないと証明できるか」です。ゴールデンマスター、プロパティテスト、コントラクトテストがその証明になります。コードレビューだけでは、変更が安全そうに見えるかどうかしか確認できません。
• 並行処理の順序、浮動小数点数の丸め、別のシステムが解析するエラーメッセージのテキストを明示的にテストしてください。これらは、それ以外は問題のないリファクタリングで、目に見えない動作変更を引き起こす最も一般的な要因です。

期限に追われる状況でのリファクタリング（トリアージ）

• 時間が限られている場合は、対象範囲を縮小し、安全網は省かないでください。変更箇所の境界を対象にした30分の特性テストは、それによって防げるインシデントよりも低コストです。
• テストを行う時間が本当にない場合は、最も機械的な変更（名前の変更、ロジックを変えない抽出）だけに限定し、制御フローやデータ形状を変える変更は後続のチケットに回してください。「速い」ことと「リスクが高い」ことを組み合わせないでください。
• 技術的負債の台帳に、同じPRで近道を記録してください。書き留められていない期限由来の負債は、後から返済されません。
• 黙って抱え込まず、エスカレーションしてください。期限のために、リスクの高い経路（決済、認証、データ、マイグレーション）で安全網を省かざるを得ない場合は、黙ってリリースするのではなく、そのことをレビュアーまたはプロダクトオーナーにはっきり伝えてください。

ストラングラーフィグ方式とビッグバンリライト

• 稼働中のユーザーやトラフィックがあり、数か月にわたる機能提供の停止が許容できない場合は、原則としてストラングラーフィグ方式を選びます。数か月に及ぶ一度きりの全面切り替えのリスクを考慮すると、段階的な移行のほうが、リライトによって得られると見込まれているコスト削減額よりも、通常は低コストです。
• ビッグバンリライトを正当化できるのは、次の場合に限られます。まだ実トラフィックがない（真のグリーンフィールド置き換えである）、ドメインロジックが小さく、1つのチームが全体を把握できる、またはレガシーシステムの状態があまりに悪く（サポート対象外のランタイム、期限切れのライセンス、修正不能なセキュリティホールなど）、部分的な稼働が現実的でない場合です。
• 「移行が80％終わったから、残りも一気に完了させよう」という落とし穴に注意してください。残りの部分には、文書化されていないエッジケースが偏って残っています。最初の部分と同じく、最後の部分でも機能ごとの規律（1度に1つの継ぎ目を移行し、ロールアウト範囲を広げる前にパリティ指標を確認すること）を守ってください。
• リライトを本当に選択する場合も、段階的に進めてください。残りを構築する前に、まずエンドツーエンドの最小の垂直スライスをリリースし、実際の（価値が低くても）トラフィックを通すことで、ビッグバン方式のリスクを全面的に負うことなく、デリバリーに関するフィードバックを得られます。
• リライトで言語やフレームワークを変更する場合（たとえば、PHPからNext.js、COBOLからJava、AngularJSからReactへ）、プロセス内の特性化テストを両方のスタックで実行することはできません。references/cross-language-rewrite.mdを参照してください。ブラックボックスのパリティオラクルがゲートとなります。スライスの着手前に、レガシー側ではパスし、未移行の新しいスタックでは失敗する必要があります。また、別の担当者がそのテストを作成します。

LLM エージェントと「リファクタリング」中の微妙な挙動の変化

「これをリファクタリングして」と指示するプロンプトは、エージェントを特定の形で失敗させます。エージェントは局所的な改善の機会に気づいてそれを実行し、「挙動はそのままで構造を改善する」から「挙動はそのままで構造を改善し、途中で気づいた修正もいくつか加える」へと、ひそかにスコープを広げます。次のような失敗パターンに注意し、発生を防いでください。

• エラー処理のずれ — except／catch の範囲を狭めたり広げたりする、何も通知しない失敗を例外の送出に変える（またはその逆）、あるいはエラー時のデフォルト値を変えることです。「リファクタリング後」のコードがよりすっきり読めるため、レビューではほとんど見過ごされます。
• 境界条件のずれ — ほぼ重複する条件分岐をまとめる際に、> が >= に変わる（またはその逆）ことです。
• 丸め／精度のずれ — 手動の累積ループを、端数で異なる浮動小数点の挙動を示すライブラリ呼び出しに置き換えることです。金額を扱うコードや科学技術計算のコードでは、特にリスクが高くなります。
• 順序／並行性のずれ — 独立しているように見えた文の順序を変更したり、ロックの範囲を狭めたりすると、観測可能な実行順序が変わったり、高負荷時にのみ発生する競合状態が起きたりする可能性があります。
• テストを都合よく修正するアンチパターン — エージェントの変更後に特性テストや既存テストが失敗すると、エージェントは多くの場合、テストを通すためにアサーションを緩めたり、失敗するケースを削除したりします。「純粋なリファクタリング」をうたうPR内でテストファイルに変更があれば、単なる整理として扱わず、人間による明確な説明を必須とするフラグとみなしてください。
• 複数ファイルの書き換えにおけるスコープの拡大 — SWE-Bench ProMax（arXiv 2608.09802）は、170件の多言語リファクタリング事例で、最高性能モデルの解決率が41.2%だったと報告しています。これはベンチマークの結果であり、このリポジトリでの予測値ではありません。影響範囲を限定し、複数ファイルにまたがるエージェントの作業を信頼する前に、実際の差分をサンプルレビューしてください。

別の言語への書き換えでは、references/cross-language-rewrite.md（言語ペアごとの意味上の落とし穴、副作用の一覧、大規模な翻訳）も読み込んでください。上記のずれの一覧は、同じ言語内での変更のみを対象としています。

エージェントが作成した「リファクタリング」をマージする前に、次の確認を必須にしてください。

1. ソースコードの差分を見る前に、まずテストファイルの差分を確認してください。弱められたアサーション、削除されたアサーション、新たにスキップされたアサーションは、人間が理由を説明するまで不合格とします。
2. 既存の（エージェントが作成したものではない）特性／契約テスト一式を再実行してください。エージェント自身が作成したテスト一式がすべて成功しても、それだけでは挙動が保たれている証明にはなりません。
3. エージェントが安全策となるテストも生成した場合は、そのテストを信頼する前に、変更対象の境界をミューテーションテストしてください。references/mutation-testing.mdを参照してください。行カバレッジだけでは、エージェントはまさにそこを狙ってごまかすようになります。
4. 上記のずれのパターンがないか、実際の差分を自分でサンプルレビューしてください。差分を書いたのと同じエージェントによる差分の要約を、差分を読む代わりに受け入れてはいけません。
5. タスクの途中でエージェントにスコープを広げさせないでください（「ついでに、ここも……」など）。そのような変更は分割し、個別のPRとしてレビューしてください。

クイックリファレンス

タスク	ツール／パターン	コマンド／アプローチ	使用する場面
長い関数、または複数の関心事を扱う関数	メソッドの抽出	小さな関数に分割する	1つの関数で検証、オーケストレーション、副作用が混在している場合
大きいクラス／モジュール、または凝集度の低いクラス／モジュール	クラスの分割／モジュールの抽出	責務を絞った単位を作成する	1つの型が関連のないワークフローや、依存関係を抱えすぎている場合
コードの重複	関数／クラスの抽出	DRY 原則	同じロジックが複数箇所にある場合
複雑な条件分岐	条件分岐をポリモーフィズムに置き換える	継承／ストラテジーパターンを使用する	型に応じた switch 文がある場合
長いパラメーターリスト	パラメーターオブジェクトの導入	DTO／設定オブジェクトを作成する	パラメーターが3つを超える関数
レガシーコードのモダナイゼーション	特性化テスト＋ストラングラーパターン	まずテストを作成し、段階的に移行する	テストがなく、コードベースが古い場合
大規模な機械的書き換え	Codemod／AST 変換	ドライラン、差分サンプルのレビュー、段階的な一括適用	複数ファイルにわたる名前変更、API 移行、反復的な編集
Java フレームワークの移行（Spring Boot、Java バージョン）	Moderne CLI または MCP 経由の OpenRewrite レシピ	インストール済みカタログから完全修飾レシピを選択し、ドライランを実行する	レシピ名は移行先によって変わります
自動品質ゲート	コンパイラー＋リンター＋コントラクトチェック	フェイルファストのチェックと成果物を含む CI パイプライン	リファクタリング中の回帰の見落としを防ぐ
技術的負債の追跡	負債レジスター＋静的解析	傾向、ホットスポット、担当者を追跡する	リファクタリング作業の優先順位付け

ナビゲーション

• 基本の手順については ## Workflow と ## Core QA (Default) を参照してください
• より詳しい資料については ## Operational Deep Dives、## Templates、## Resources を参照してください
• テスト、アーキテクチャ、コードレビューへの引き継ぎについては ## Related Skills を参照してください

関連スキル

スキル	目的
qa-debugging	本番環境の問題とテストの不安定さをデバッグする
software-code-review	コードレビュープロセスとチェックリスト
software-architecture-design	アーキテクチャの設計と再設計の判断
qa-testing-strategy	テスト戦略とカバレッジの計画
data-sql-optimization	パフォーマンスの調整、SQL、クエリプラン

運用の詳細

共通基盤

• ../software-clean-code-standard/references/clean-code-standard.md - 引用するための標準的なクリーンコード規則（CC-*）
• レガシー向けプレイブック：../software-clean-code-standard/references/code-quality-operational-playbook.md - 運用手順（従来の RULE-* セットは CC-* との対応表に統合されて廃止済みです。レビューとリファクタリングの判断ツリーは現在、software-code-review とこのスキルにあります）
• ../software-clean-code-standard/references/refactoring-operational-checklist.md - リファクタリングのコードスメルと対処法の対応表、安全なリファクタリングのためのガードレール
• ../software-clean-code-standard/references/working-effectively-with-legacy-code-operational-checklist.md - シーム、特性化テスト、段階的な移行パターン

スキル固有

詳細なリファクタリングカタログ、Codemod の段階的適用パターン、品質ゲート、技術的負債のプレイブック、レガシーコードのモダナイゼーション手順については、references/operational-patterns.md を参照してください。

テンプレート

チェックリストや品質ゲートの設定には、assets/ にあるテンプレートをコピーして使用してください。

• リファクタリング：assets/process/refactoring-checklist.md。一般的なコード品質のレビューについては、software-code-review を参照してください（assets/process/code-review-quality.md は現在、そちらを参照するためのファイルです）
• 技術的負債：assets/tracking/tech-debt-register.md
• 品質ゲート：assets/quality-gates/javascript/eslint-config.js、assets/quality-gates/platform-agnostic/sonarqube-setup.md

リソース

詳細ガイドは references/ にあります。必要なものだけを読み込んでください。

• 運用パターン：references/operational-patterns.md - 再利用してから書くための手順（以前ここにあったカタログ／品質ゲート／レガシーのモダナイゼーションに関する内容は、現在は以下のファイルにあります）
• リファクタリングカタログ：references/refactoring-catalog.md - 動作変更のリスクが潜むリファクタリング（Fowler の内容を完全に再掲したものではありません。そちらについては refactoring.com/catalog を参照してください）
• コードスメルガイド：references/code-smells-guide.md - 名前のレベルでのスメル一覧、検出ツール、デッドコードの削除段階
• 技術的負債の管理：references/tech-debt-management.md
• レガシーコードのモダナイゼーション：references/legacy-code-strategies.md
• ブラウンフィールドのエージェントループ：references/brownfield-agent-loop.md - レガシーリポジトリに対してコーディングエージェントを動かす方法：リポジトリをグラフ化し、接合点を選び、不変の受け入れゲートを構築し、タスクの範囲を定めてループを実行します
• 特性テスト：references/characterization-testing.md - ゴールデンマスターおよび承認テストのパターン
• ストラングラーフィグ移行：references/strangler-fig-migration.md - 段階的なレガシー移行戦略（拡張と縮小／並行変更に関する説明を含みます）
• 言語間の書き換え：references/cross-language-rewrite.md - 対象の言語またはフレームワークがソースと異なる場合に読み込みます：同等性の判定基準、言語ペアごとの落とし穴、副作用、認証／SEO／セキュリティの同等性、データチェック
• 自動リファクタリングツール：references/automated-refactoring-tools.md - Codemod、AST 変換、レシピのテスト、IDE によるリファクタリング
• ミカドメソッド：references/mikado-method.md - 依存関係が絡み合ったレガシー変更の前提条件ツリー。葉から順に実行します
• ミューテーションテスト：references/mutation-testing.md - Stryker／mutmut／cosmic-ray／PIT、ミューテーションスコア、CI のしきい値、段階的な実行
• フィーチャーフラグの廃止：references/feature-flag-retirement.md - 段階的な手順：参照を特定し、不要な分岐を削除し、最後に定義を削除します

オプション：AI／自動化

実施すること：

• 振る舞いが維持されることをテストと契約によって証明できる場合に限り、機械的なリファクタリング（名前の変更／抽出／移動）の提案に AI を使用します。
• AI を使って差分やリスクの高い箇所を要約し、対象を絞った特性テストを実行して検証します。
• 利用できる場合は、自由形式のテキスト編集よりもツールを活用したリファクタリング（IDE／コンパイラーを考慮したツール、codemod）を優先します。
• エージェントが生成したリファクタリングは、人間が代表的な差分をレビューし、安全策がすべて機能するまではドラフトパッチとして扱います。
• Java プロジェクトでは、手書きの codemod より OpenRewrite のレシピ（mod CLI または MCP サーバー経由）を優先します。レシピは決定的で、バージョンを考慮します。AI エージェントはツール呼び出しとして直接実行できます。
• AI が生成した特性テストをリファクタリングの安全策として扱う前に、ミューテーションテストで検証します。行カバレッジだけではテストの品質を証明できません。references/mutation-testing.md を参照してください。
• エージェントにレガシーリポジトリを扱わせる前に、まず受け入れゲートを構築し、エージェントには決して変更させないでください。エージェントに最も理解しやすい場所を選ばせるのではなく、リポジトリをグラフ化して接合点を選びます。references/brownfield-agent-loop.md を参照してください。
• エージェントが複数ファイルにわたって大規模なリファクタリングを行う場合は、実行前に影響範囲を絞ります。上記の「LLM Agents and Subtle Behavior Changes During 'Refactors'」にあるスコープ拡大の項目を参照してください。

避けること：

• 明示的な要件と回帰テストがないまま、振る舞いを変更するリファクタリングを受け入れること。
• CI を通すためにアサーションを弱めて「テストを修正」するよう AI に任せること。
• ドライランやサンプルレビューを行わずに、AI が生成した複数ファイルにわたる編集をリポジトリ全体に適用すること。
• リファクタリングの途中でエージェントが自律的に範囲を拡大すること。エージェントの開始前に境界と影響範囲を定義してください。

厳選した外部資料については、data/sources.json を参照してください。

学びのループ

過去の判断や落とし穴が関係する場合は、learnings.consolidated.md があれば参照してください。必要な履歴を確認する場合、または利用可能な代替手段として使う場合に限り、learnings.md を使用します。それ以外の場合は、どちらも参照しません。

適用後、記憶しておく価値のあるパターン、防止すべきミス、または意外だった分野の事実に遭遇した場合は、agents-skills-feedback-loop/scripts/append_learning.py を使って、日付付きの箇条書きを learnings.md に 1 件追記します。SKILL.md 自体は変更しないでください。