置換を1回で全部終わらせようとして、あとで何が起きたか分からなくなる。これ、かなりありがちな失敗だ。Claude Code に大量の修正を投げると、ファイルのあちこちを同時に触れて、差分がでかくなり、どこで壊れたのか追いにくくなる。巻き戻したいのに、戻す単位すら見えない。そこで効くのが段階コミットだ。小さく直して、小さく確かめて、小さくコミットする。これだけで手戻りの痛さがかなり減る。
たとえば、プロジェクト内の文言を「旧サービス名」から「新サービス名」に置き換える、フォルダ名を整理する、説明文の表記ゆれを直す、不要ファイルをまとめて消す。こういう作業を Claude Code に任せるとき、いきなり「全部やって」で済ませると危ない。実際、筆者は過去に、似た名前のファイルをまとめてリネームさせたあとで、関連参照の修正まで一気に走らせてしまい、どの変更がどの影響を生んだのか見えなくなったことがある。diff が肥大化して、結局、途中まで戻してやり直しだ。あれはだるい。
やり方は単純だ。ひとつの巨大タスクを、意味のある小片に分ける。Claude Code には、その都度「この範囲だけ」「ここまでで止める」「変更を確認してから次へ進む」と指示する。置換なら、まず検索と影響範囲の確認だけをさせる。次に、実際の修正を一部だけ入れる。最後に確認して、問題なければコミットする。コミットがあると、戻す単位がはっきりする。これは CLI で作業するならかなり重要だ。
たとえば、こんな流れにする。
git status
git checkout -b rename-service-name
Claude Code への最初の指示は、いきなり変更ではなく調査から始める。
「旧サービス名」がどのファイルに出てくるか洗い出して。まずは変更しないで、影響範囲だけ一覧にして。
ここで一覧が出たら、次に本体を小分けにする。
まずは docs/ 配下の文書だけ置換して。コードは触らないで。
変更後に差分を要約して、問題がなければ止まって。
確認して問題なければ、その場でコミットする。
git add docs/
git commit -m "docs: rename old service name"
次はコード側だ。
次に src/ 配下だけ置換して。関連するテスト名やコメントも必要な範囲だけ直して。
大きく壊れそうな箇所は勝手に広げず、保留にして報告して。
また確認して、必要ならテストを走らせる。
git add src/
git commit -m "refactor: update service name in code"
こうしておくと、もし2段目で変な置換が混ざっていても、1段目の文書修正はそのまま残せる。全部を一度に直した場合、戻すのはかなり面倒だ。段階コミットは、その面倒を先に潰すやり方である。
このとき大事なのは、「作業単位」を人間が決めることだ。Claude Code は指示が雑だと、広く触ろうとする。検索置換ひとつでも、コメント、テスト、README、設定ファイルまでまとめて見に行くことがある。便利ではあるが、置換の責任範囲がぼやける。だから、最初に範囲を切る。文書だけ、コードだけ、設定だけ、画像だけ、こう分けていくと、巻き戻しやすさが全然違う。
非エンジニアの作業でも同じだ。たとえば、案件ごとの文書フォルダを整えるとき、ファイル名の統一、重複ファイルの整理、古い下書きの退避を一気にやると、後から「どれを消したか」が分からなくなる。そんなときは、まず名前の修正だけ、次に重複候補の一覧作成、最後に削除候補の確認、の順に分ける。Claude Code にも「削除はまだしないで」とはっきり言う。ここを曖昧にすると、確認前に進む。そこは遠慮なく止めていい。
このフォルダ内の重複っぽいファイルを洗い出して、削除はしないで一覧だけ作って。
そのあと、残す候補と迷う候補を分けて。
段階コミットで気をつけたいのは、コミットを細かくしすぎて意味がなくなることだ。1ファイルずつ、1行ずつコミットすると、あとで追う側がつらい。小さく切るが、意味のあるかたまりにする。たとえば「文書側の表記統一」「コード側の名前変更」「テスト更新」のように、あとから見返して理解できる粒度がちょうどいい。
もうひとつ、Claude Code に「全部終わるまで止まらない」と投げると、途中の確認ポイントが消える。これは本当に危ない。人間が見ないまま広げた変更は、差分の中で問題が埋もれる。筆者は以前、表記修正とついでのコード整理を一緒に頼んで、関係ない関数名まで連鎖的に変えられかけたことがある。意図が通じていれば便利だが、通じていないと、修正の境界が崩れる。だから、各段階で止める。Claude Code にも止まれと書く。曖昧にしない。
この段階の変更だけで止まって。次の範囲には進まないで。
変更内容を3行で要約して、気になる点があれば先に挙げて。
大規模な置換で段階コミットが効くのは、戻せるからだけではない。自分の判断も整理されるからだ。どこまで直したか、どこから危ないか、どの範囲なら安心して戻せるかが見える。Claude Code を使うほど、この境界管理が効いてくる。作業量そのものは減らなくても、事故の後処理が劇的に軽くなる。
置換作業を雑に一発で終わらせるのは気持ちいいが、後で高くつく。小さく切って、確認して、コミットして、次へ進む。この順番を守るだけで、Claude Code はかなり扱いやすくなる。巻き戻しが効く作業は、だいたい強い。