【要約】Claude Codeのフォーマッタフックが1行修正を316行diffに肥大化させた話と復旧手順 [Zenn_Python] | Summary by TechDistill
> Source: Zenn_Python
Execute Primary Source
// Problem
開発者がClaude Codeを用いてPythonコードの微修正を行った際、意図しない大規模な差分が発生した。修正の意図は極めて限定的であったが、結果としてコードの整合性を損なうノイズが混入した。
- ・対象：1箇所のf-stringプレフィックスの削除。
- ・事象：316行に及ぶコードの行折り返し差分が発生。
- ・原因：Claude CodeのPostToolUseフックが、ファイル編集のたびにRuffによる整形を強制したため。
- ・背景：プロジェクトにpyproject.tomlがなく、Ruffのデフォルト設定（88文字）が既存のスタイルを破壊した。
// Approach
汚染されたコミットを修正するため、Gitの履歴操作と、AIの自動フックを回避する手法を組み合わせた。AIの自動実行プロセスをバイパスすることで、最小限の修正のみを適用することを目指した。
- ・ファイルの復元：git checkout HEAD~1を用いて、汚染されたファイルを整形前の状態へ戻した。
- ・フックの回避：Editツールを使わず、Pythonのバイト置換で直接ファイルを書き換えた。これによりPostToolUseの発火を防いだ。
- ・コミットの修正：git commit --amendを実行し、クリーンな差分のみを反映した。
- ・整合性検証：py_compile、ruff check、import疎通の3段階で動作を担保した。
// Result
316行あった差分を、意図した1行の修正のみにまで削減することに成功した。これにより、コードレビューのコストを最小化し、プロジェクトのコードスタイルを維持した。
- ・差分の削減：276行の挿入と121行の削除から、1行の挿入と1行の削除へと劇的に改善した。
- ・品質の確保：構文エラーやインポートエラーがないことを確認し、コードの整合性を維持した。
- ・運用の教訓：AIエージェント利用時のgit diff --statによるサニティチェックの重要性が明確になった。
Senior Engineer Insight
> AIエージェントの導入は開発速度を上げるが、自動化された副作用がレビューコストを爆発させるリスクを孕む。特に「保存時整形」と「AIの編集」の組み合わせは、既存のスタイルを無視したノイズを量産しやすい。CI/CDやpre-commitでのチェックに加え、AIエージェントのフック設定がプロジェクトの規約と整合しているかを厳格に管理すべきである。