DotfilesとGNU StowでClaude Code設定を管理する

コーディングエージェントの設定をdotfilesリポジトリで追跡することは効率的な方法です。私はGitとGNU Stowを使ってこれを実現し、以下の2つのメリットを得ています：編集しすぎて壊れたスキルをロールバックできることと、新しい開発マシンにワンコマンドでセットアップを複製できることです。

以下にその方法を詳しく説明します。

AI設定は今やコードベース

「Claude Codeの設定」といえば、かつては設定ファイルとCLAUDE.mdがあれば十分でした。しかし、今ではスキル、フック、プラグイン、スラッシュコマンド、サブエージェント、ワークフロー、MCPサーバー定義が含まれます。おそらく他にもいくつかあるでしょう。新機能がリリースされるたびにファイルが追加され、その数は増え続けています。

モデルとコーディングエージェントは急速に変化し、それに伴ってワークフローも変わります。リリースのたびにプロンプトの調整とスキルの更新が必要です。ある時点で、これは単なる設定ではなく、小さなコードベースになりました。ほとんどすべてがプレーンテキストとJSONであり、一つのディレクトリに収まっているため、バージョン管理に最適です。

問題が起きたらロールバック

一度の編集ミスで、以前の状態に戻したいと思うことがあります。独自のLyraプロンプトを使用していて、段階的に変更を加えたが、数バージョン戻したい場合、この設定があればそれまでの作業を失わずに済みます。

誰かが共有したスキルを見つけ、カスタマイズして数週間調整し続けたとします。ある日突然動作しなくなり、正常に動作していたときの状態を思い出せないことがあります。さらに悪いのは、AIにスキル自体を起草または更新させる場合（ClaudeがClaudeの設定を編集する）で、新しいバージョンが突然壊れることがあります。

バージョン管理がないと、最新の更新で作業が失われますが、Gitがあればgit diffで変更を確認し、git revertで正常に動作していたバージョンに戻せます。これで何度も助けられました。

新しいマシンにワンコマンドで

マシン移行の容易さはdotfilesが人気を博した元々の理由であり、今ではさらに重要です。シェルエイリアスやエディタ設定はすでにこの方法で移行しています。~/.claudeをリポジトリに追加すれば、AI設定全体を単一のスクリプトで新しいマシンに展開でき、Claude Codeにワークフローを一から教え直す必要がありません。

Dotfilesとは？

Dotfilesはホームディレクトリにある隠し設定ファイルで、.zshrc、.gitconfig、そして今では.claude/などです。Dotfilesリポジトリはこれらすべてを含む小さなGitプロジェクトで、それらを適切な場所にリンクまたはコピーするスクリプトも含みます。あなたのマシンの個性がバージョン管理されます。私の構造を見たい場合は、GitHub（yurikoval/dotfiles）で確認できます。

Dotfilesの管理方法

これを実現する方法はいくつかあり、何もしないよりはましです。

最も簡単な方法は、~/.claude内でgit initを実行し、変更をコミットしていくことですが、Claudeの設定のみを追跡します。Atlassianは、ホームディレクトリを作業ツリーとするベアリポジトリを推奨しており、シンボリックリンクを完全に回避します。ツールを重視するなら、yadmはGitをラップし、マシンごとの代替設定と暗号化を内蔵したdotfilesマネージャーです。

私はGNU Stowを使い続けています。Stowはdotfilesリポジトリからホームディレクトリにパッケージをシンボリックリンクします。stow claudeで~/.claudeがリンクされ、stow -D claudeでクリーンに削除されます。

重要なのはツールではなく習慣です。実験する前、特にAIに自身の設定を書き換えさせる前にコミットすることで、失敗した反復はgit revertで簡単に元に戻せます。

プッシュする前の注意点：dotfilesリポジトリは、APIキーがGitHubに漏洩する典型的な経路です。MCPサーバー定義や.zshrcのエクスポートはキーを収集しがちです。追跡するファイルに秘密情報を含めないようにしてください。私はMacでKeychain、1Password CLI、direnvを使って開発用秘密情報を管理する方法について記事を書いています。