【ITニュース解説】Stop the Chaos: Git Stash Checkpoints for Claude Code

開発の世界では、人工知能がコードを生成・編集する新しい時代が到来している。その中でも「Claude Code」のようなツールは、複雑な要求に対してプロジェクト全体のコードベースを考慮しつつ、複数のファイルを同時に修正する能力を持っている。これは非常に強力な機能だが、時には開発者の意図しない変更を引き起こし、プロジェクトが正常に動作しなくなる「破壊」的な状況を生む可能性がある。このような事態が発生した場合、通常の方法では問題発生前の状態に明確に戻る手段がないという課題があった。

この問題に対処する方法として、タスクごとにGitのコミットを頻繁に行うことが考えられる。しかし、これはプロジェクトのバージョン管理履歴（Git history）が細かくなりすぎて見づらくなるという別の問題を引き起こす。そこで提案されるのが、「Git Stash」と「ClaudeのHooks」を組み合わせた自動チェックポイントシステムだ。

「Hooks（フック）」とは、Claude Codeの特定のアクションが発生したときに、あらかじめ設定しておいたコマンドやスクリプトを自動的に実行するための仕組みである。これは、プログラムにおける「イベントリスナー」のようなものだと考えるとわかりやすいだろう。Claude Codeがコードの編集を開始したり、完了したりするなどのイベントを検知し、それに応じて特定の処理を実行できる。

このチェックポイントシステムでは、Claude Codeが1つのまとまったコード生成や編集を完了するたびに、プロジェクトの現在の状態を「Git Stash」として一時的に保存する。スタッシュは、未コミットの変更を一時的に退避させておくGitの機能で、作業中の変更をコミットせずに別の作業に移りたい場合などに便利に使われる。このシステムでは、作成されるチェックポイントは最大10個までと決められており、上限に達した場合は最も古いチェックポイントが自動的に削除される。これにより、常に最新の10個の安全な復元ポイントが保持されることになる。

このシステムを導入するための具体的な手順を説明する。

まず、プロジェクトのディレクトリ構造を準備する。プロジェクトのルートディレクトリに、.claude/という隠しディレクトリを作成し、その中にsettings.local.jsonという設定ファイルと、ログを保存するlogs/ディレクトリを作成する。また、プロジェクトのルートディレクトリにcheckpoint.shというシェルスクリプトファイルも配置する。

次に、.claude/settings.local.jsonファイルを編集して、Claude Codeのフックを設定する。このJSON形式の設定ファイルでは、Claude Codeが「Stop（停止）」したときに特定のコマンドを実行するように設定する。具体的には、"hooks"セクション内の"Stop"イベントに、先ほど作成したcheckpoint.shスクリプトのパスを記述する。このとき、"YOUR_PROJECT_DIR"の部分は、実際にプロジェクトが存在するディレクトリの絶対パスに置き換える必要がある。また、スクリプトの実行にタイムアウト（ここでは30秒）が設定されている。これにより、Claude Codeがコードの編集を終えるたびに、このcheckpoint.shスクリプトが自動的に実行されるようになる。

最後に、checkpoint.shファイルを設定する。これは、チェックポイントの作成と管理を行うシェルスクリプトである。 スクリプトの冒頭では、ログファイルの場所を定義し、ログディレクトリが存在しない場合は作成する。ログは.claude/logs/checkpoint.logに出力される。デバッグレベルや詳細レベルのログ出力設定も可能で、ログファイルが50KBを超えたら古いログをバックアップファイル（.old）として残すログローテーションの機能も含まれている。

スクリプトが実行されると、まずClaude Codeからの入力（JSON形式のデータ）を読み込む。このデータには、フックがすでにアクティブかどうかを示す情報が含まれており、もしすでにアクティブであれば、無限ループを防ぐためにスクリプトはそこで終了する。

次に、現在のディレクトリがGitリポジトリであるかを確認する。Gitリポジトリでなければ、チェックポイントを作成する意味がないため、スクリプトは終了する。また、git status --porcelainコマンドを使って、作業中のファイルに未コミットの変更があるかをチェックする。もし変更が一切なければ、チェックポイントを作成する必要がないため、これもスクリプトは終了する。

変更が検出された場合、スタッシュに保存するメッセージが生成される。もしスクリプト実行時に引数が渡されていればその引数をメッセージとして使用するが、そうでなければ、変更されたファイルの中から最新の更新日時を持つ上位3つのファイル名と、変更されたファイル全体の数を基にメッセージを自動生成する。例えば、「ファイルA, ファイルB, ファイルC (and 5 more)」のような形だ。

このメッセージと現在のタイムスタンプを組み合わせ、「agent: 年月日:時分秒 変更メッセージ」という形式のチェックポイントラベルが作成される。 そして、git stash push --include-untracked -m "$STASH_MESSAGE"コマンドが実行され、現在の未コミットの変更（未追跡ファイルも含む）が、生成されたメッセージとともに新しいスタッシュとして保存される。このスタッシュが作成された後、git stash apply stash@{0}コマンドをすぐに実行し、作成したばかりのスタッシュの内容を現在の作業ディレクトリに再適用する。これにより、チェックポイントが作成されたにもかかわらず、作業中のファイルはスタッシュ作成前とまったく同じ状態に保たれるため、開発者は中断なく作業を継続できる。

最後に、スタッシュの数を管理する。git stash listコマンドで「agent:」というラベルを持つスタッシュ（このシステムで作成されたもの）の数を数え、それが10個を超えていれば、最も古い「agent:」スタッシュをgit stash dropコマンドで削除する。これにより、常に最新の10個のチェックポイントが保持される。 このcheckpoint.shファイルは、作成後にchmod +x checkpoint.shコマンドを実行して、実行権限を付与しておく必要がある。

万が一、Claude Codeによる変更でプロジェクトが破損してしまった場合でも、このシステムがあれば簡単に以前の状態に戻すことができる。まず、git stash listコマンドを実行して、これまでに作成されたチェックポイントの一覧を確認する。それぞれのチェックポイントには、作成日時と変更内容を示すメッセージが付けられているため、どの時点の変更に戻りたいかを判断できる。そして、復元したいチェックポイントがstash@{0}やstash@{1}などと表示されている場合、例えばgit stash apply stash@{0}とコマンドを実行すれば、そのチェックポイントの状態に作業ディレクトリを戻すことができる。

このように、Git StashとClaudeのHooksを組み合わせることで、強力なAIコード生成ツールを安全に利用し、予期せぬ問題からプロジェクトを効果的に保護できる堅牢なチェックポイントシステムを構築できる。開発者は安心してAIによる支援を受けながら、より効率的に開発を進められるようになるだろう。