focused-fix

集中的な修正

カテゴリ： エンジニアリング 分野： デバッグとメンテナンス

概要

集中的な修正スキルは、バグ修正において、規律ある最小限の変更を徹底します。バグ修正中にコードをリファクタリングしたり改善したりするのではなく、問題を解決するために必要な最小限の変更箇所を特定します。これにより、リスクを抑え、コードレビューを簡素化し、スコープの拡大を防ぎます。

次の場合に使用

• ユーザーが「最小限の変更でバグを修正して」「集中的にバグを修正して」「最小限の修正範囲を定めて」と依頼した場合
• バグ報告をトリアージし、変更するファイルを最小限に絞る必要がある場合
• PR のスコープが拡大するおそれがある場合（無関係なリファクタリング、スタイル変更、「ついで」の修正など）
• ホットフィックスやリリースを妨げる問題に対して、低リスクでレビューしやすい変更セットが必要な場合
• ユーザーが「X を直す最小限の変更は何か？」または「このバグの修正にはどのファイルを変更する必要があるか？」と尋ねた場合

まず確認すること

修正範囲を定める前に、以下の情報を確認します。不足している、または曖昧な情報によって結果が変わる場合は質問し、結果に影響しない場合は妥当なデフォルトを使い、使用した内容を伝えます。

• 観測可能な不具合： 正確な症状、再現手順、期待される動作と実際の動作（分析対象となるバグの説明と、修正で解決すべき内容。原因の推測ではありません）。
• コードベースのパスとファイル形式： 検索するディレクトリと拡張子（--path／--extensions に設定します）。
• 最小限の修正か構造的な修正か： リファクタリングではなく、集中的な修正であることを確認します（対象外の「ついでに」行う変更を却下するかどうかを判断します）。

リスト全体ではなく、この依頼で特に重要な情報を2、3点尋ねます。ユーザーがすぐに結果を求めている場合は、前提を冒頭に明記したうえで結果を提示します。

クイックスタート

# Analyze a bug description to identify minimal change scope
python scripts/change_scope_analyzer.py --bug "Login fails when email has + character" --path ./src

# Analyze with JSON output
python scripts/change_scope_analyzer.py --bug "API returns 500 on empty array input" --path ./src --format json

# Analyze with specific file extensions
python scripts/change_scope_analyzer.py --bug "CSS overflow on mobile" --path ./src --extensions .css .scss .html

ツールの概要

ツール	目的	主なフラグ
change_scope_analyzer.py	バグ修正に必要な変更ファイルを最小限に絞り込む	--bug、--path、--extensions、--format

change_scope_analyzer.py

コードベースとバグの説明を照合して、以下を特定します。

• バグに関連する可能性が最も高いファイル（キーワード照合、インポートの追跡）
• 推定される変更範囲（ファイル数、行数）
• 変更のリスク評価
• 推奨する修正方法（最小限または構造的）

ワークフロー

集中的なバグ修正のワークフロー

1. 明確なバグの説明を書く — 再現手順、期待される動作と実際の動作
   • 検証： 原因の推測ではなく、観測可能な不具合が説明されていること
2. change_scope_analyzer.py を実行して範囲を特定する
   • 検証： 分析結果に具体的なファイルと推定行数が示されていること
3. 推奨されたファイルと修正方法を確認する
   • 検証： 推奨方法が「最小限」であること。「構造的」と示された場合は中止し、リファクタリング用の PR を別途作成します
4. バグ修正に必要な変更のみを行う
   • 検証： git diff --stat が分析ツールの推奨値と一致するか、それより小さいこと
5. 無関係な変更が入り込んでいないことを確認する
   • 検証： git diff に、書式だけの変更、無関係なインポート、「ついで」の編集が含まれていないこと
6. 変更範囲を絞った変更セットで PR を提出する
   • 検証： コミットメッセージに修正したバグが明記され、回帰テストが含まれていること

範囲の検証

1. 変更後に分析ツールを再実行します
2. 実際の変更を推奨された範囲と比較します
3. 範囲外の変更があれば、別の PR に分けます
   • 検証： 分析ツールの推奨に含まれていないファイルを変更した場合、1行の理由を添えるか、変更を元に戻すこと

参考ドキュメント

• 集中的な修正の方法論 - 原則、アンチパターン、判断フレームワーク

よくあるパターン

行うこと

• 報告されたバグそのものを修正する
• 修正の回帰テストを追加する
• 修正が有効な理由をコミットメッセージに記載する
• 差分をできるだけ小さく保つ

行わないこと

• バグ修正中に周辺コードをリファクタリングする
• 同じ PR で「関連する」問題も修正する
• 変更したファイルの書式やスタイルを変更する
• バグ修正を装って機能を追加する

アンチパターン

アンチパターン	失敗モード	対処法
バグ修正 PR での「ついでに」リファクタリング	影響範囲が急拡大し、レビュー時間が倍増します。無関係なリグレッションが本当の修正に隠れてしまいます	リファクタリング用に別の PR を作成し、fix: ではなく refactor: のタグを付けます
変更対象ファイルの再フォーマットや自動保存によるスタイル変更	差分が読みにくくなり、空白文字だけの 200 行に本当の修正が埋もれてしまいます	コミット前にスタイル変更を元に戻します。新規ファイルのみ保存時にフォーマットするようエディターを設定します
誤ったレイヤーで症状を修正する	バグが別の形で再発し、回避策の負債が蓄積します	根本原因のレイヤーまでたどります。analyzer のキーワード一致の出力は手掛かりであり、答えではありません
「修正内容は明らかだから」とリグレッションテストを省略する	6 か月後のリファクタリングで、バグが気づかれないまま再発します	すべての fix: コミットに、失敗した後に成功するテストを少なくとも 1 つ追加します
change_scope_analyzer.py の出力を絶対的なものとして扱う	analyzer はキーワードやインポートに基づくもので、意味解析ではありません。そのため、動的ディスパッチ、リフレクション、設定駆動のパスを見落とします	出力を出発点として使い、対象範囲を確定する前に呼び出し元とテストを grep で検索します
修正を依存関係のアップグレードとまとめる	1 つの PR に異なる 2 つのリスクが含まれます。ロールバックが必要になった場合、両方とも元に戻ってしまいます	まずアップグレードを別途マージし、その後、アップグレード済みのベースラインに対して修正します