半年間育てたClaude Codeに関連する設定が消えた日
ある日、使っていた社用PCがハードウェア故障で動かなくなりました。
焦りはしたものの、致命傷ではないだろうとすぐに思い直しました。自分がこの半年作り上げてきたskillsは、以前からGitリポジトリで管理していたからです。
代わりの端末が届き、Claude Codeを起動しました。~/.claude/を覗いた瞬間、血の気が引きました。
残っていたのはskillsだけでした。コマンド実行に割り込むhooksや、権限まわりの調整は、跡形もありませんでした。半年かけて少しずつ育ててきた設定を、どこにもバックアップしていなかったからです。
「コードっぽいもの」だけを版管理していて、無意識に「設定っぽいもの」を管理対象から外してしまっていた。それだけのこととはいえ、また一から設定をやり直すのかと思うと、手が止まり、頭が真っ白になりました。
同じことは二度と繰り返したくない。設定の管理方法を調べはじめ、たどり着いたのがdotfiles管理という手法でした。
dotfilesは、目新しい発想ではなかった
dotfilesとは、.bashrcや.vimrcのような、名前がドットで始まる設定ファイル群の通称です。これらをGitリポジトリで管理し、専用ツールでホームディレクトリに反映する手法自体は、Unix文化の中で以前から広く行われてきました。
ただただ私が、既にある方法を知らないままAIエージェントの設定だけを自己流で半年育てていた、というだけのことでした。
AIエージェントの設定は、特に"消えもの"になりやすい
あとから振り返ると、なぜhooksだけ見落としていたのか、自分でも不思議です。
skillsは.mdファイルの集まりで、見た目もコードに近いので、リポジトリに入れる発想に自然とたどり着きました。一方hooksやpermissionはsettings.jsonの中の一項目で、正直、コードという感覚があまりありませんでした。だからバックアップの対象にも入っていなかったんだと思います。
Claude Codeのsettings.json・CLAUDE.md・hooks・skills・MCPサーバー設定は、使い込むほど増えていきます。
hooksはコマンド実行に割り込む仕組みですし、permissionはエージェントに何を許可するかを決める設定です。どれもエディタのキーバインド設定程度の話では済みません。これらが端末ごとにバラバラだと、同じ指示を出しても挙動が変わってしまいます。
それにもかかわらず、これらの設定は多くの場合その端末のホームディレクトリにしか存在しません。会社PCの故障に限らず、自宅PCの買い替え・クラウド開発環境・WSLの再構築、といった場面で、設定はまるごと消えます。
dotfiles管理をしないと何が起きるか
整理してみると、理由は大きく三つありそうです。
端末を増やすたびに手作業でやり直す
新しいPCをセットアップするたびに、記憶を頼りにhooksを書き直し、使っていたskillsを思い出しながら再作成することになります。作業内容は毎回微妙に違い、「前のPCではこの設定を入れていたはず」という記憶頼みが積み重なります。
変更の理由が残らない
設定ファイルを直接編集していると、「いつ・なぜ変えたか」はその場の記憶だけが頼りです。半年前に足したpermissionの許可設定が何のために追加したものか、あとから分からなくなるのはよくある話です。
チームに展開できない
hooksやpermissionは、そのままセキュリティレビューの対象になり得る設定です。個人のホームディレクトリに閉じている限り、チームで同じ基準を共有する手段がありません。属人化したまま、レビュー観点も個人差が出ます。
dotfiles管理で得られること
これらの課題は、設定ファイルをバージョン管理下に置くことで解決できます。dotfilesをGitリポジトリとして管理し、専用ツールでホームディレクトリに反映する、という一般的なパターンです。
| 課題 | dotfiles管理での解決 |
|---|---|
| 端末ごとに手作業 | 1コマンドで反映、新端末でも同じ状態を再現できる |
| 変更理由が残らない | git logとcommit messageに変更意図が残る |
| チームに展開できない | リポジトリを共有すれば同じhooks/permissionをレビューできる |
副産物として、設定変更もコードと同じくPull Requestベースでレビューできるようになります。hooksでどんなコマンドを許可しているか、他の人の目が入る状態になるのは、AIエージェントの設定としては軽視できないメリットです。
なぜchezmoiか
dotfiles管理ツールにはいくつか選択肢があります。単純なsymlink方式（GNU Stow、bare git repoでの直接管理）と、テンプレートエンジンを持つ方式（chezmoi、yadm）に大別できます。
| ツール | 方式 | 端末ごとの差分 | シークレット |
|---|---|---|---|
| bare git repo | 直接管理 | 分岐なし、手動でif分岐を書くしかない | 別途工夫が必要 |
| GNU Stow | symlink | 分岐なし | 対応なし |
| chezmoi | テンプレート適用＋symlink相当 | Go templateで端末ごとに出し分け | age/gpg暗号化に対応 |
Claude Codeの設定は、この「端末ごとの差分」と「シークレット」の両方に引っかかりやすい領域です。settings.jsonにはOSごとに違うコマンドパスが混ざりますし、MCPサーバーの接続情報にAPIキーが含まれることもあります。symlinkだけで済ませようとすると、この2つを結局は手作業で吸収することになります。
逆に、管理対象がシークレットを含まず端末ごとの差分もないなら、symlinkだけで十分です。テンプレートと暗号化の機能がすぐに必要になるかどうかで選ぶとよいでしょう。
chezmoiは、ソース側のファイルをGo言語のtemplate構文で書いておき、適用時に端末ごとの変数（OS種別・ホスト名など）で展開します。シークレットはage/gpgでの暗号化、あるいは外部シークレットマネージャとの連携にも対応しています。設定ファイルという「平文だが機微情報を含みうるファイル」を扱う上で、この2機能が効いてきます。
本記事はchezmoiを軸に説明しますが、原理は他のdotfilesツールでも同じです。詳細はchezmoi公式ドキュメントを参照してください。
何を、どう管理するか
管理対象にすべきもの
Claude Code関連で、dotfiles管理に向いているのは次のファイル・ディレクトリです。
-
~/.claude/settings.json— permission、hooks、statusline、環境変数 -
~/.claude/CLAUDE.md— グローバルな振る舞いの指示 -
~/.claude/skills/— 自作skill -
~/.claude/hooks/— hooksから呼び出すスクリプト本体 -
~/.mcp.jsonや各プロジェクトの.mcp.jsonのテンプレート
個人的に一番の盲点だったのはsettings.jsonとhooks/でした。skillsは単体のファイル群として意識しやすい一方、settings.json内のhooksやpermissionは見落としがちです。自分が失ったのもここでした。管理対象を選ぶときは「ファイルとして独立しているか」より「再現できないと困るか」で考えるほうが、漏れが少ない気がしています。
管理対象に向いていないもの
一方で、次のものはdotfiles管理に向きません。
-
~/.claude/projects/配下の会話履歴・セッションデータ — 実行時に生成される状態であり、ソースではありません - プラグインのキャッシュ・ロックファイル — インストール時に再生成されるものです
- サードパーティCLIのインストーラが直接書き換えるファイル — ソース側の管理とすぐ食い違う対象です
端末差分の吸収例
たとえばツール管理設定のように、OSやアーキテクチャで内容を変えたいファイルがあります。chezmoiのtemplateでは、こうした分岐を次のように書けます。
# 例: mise config.toml のテンプレート
[tools]
node = "lts"
{{- if eq .chezmoi.os "linux" }}
uv = "latest"
{{- end }}
適用コマンドを実行すると、テンプレートが評価され、実際のホームディレクトリにファイルが生成されます。
$ chezmoi apply
# 出力: source配下のテンプレートが評価され、~/.config/mise/config.toml が生成される
run_スクリプトで初期セットアップも再現する
chezmoiにはrun_once_やrun_after_という命名規則のスクリプトを置ける仕組みがあります。ファイル適用のあとに1回だけ、あるいは適用のたびに実行されるスクリプトです。ツールのインストールや環境情報の生成といった、「ファイルを置くだけでは終わらないセットアップ」をここに寄せられます。
dotfiles/
├── dot_claude/
│ ├── settings.json.tmpl
│ ├── CLAUDE.md
│ └── skills/
├── dot_config/
│ └── mise/config.toml.tmpl
└── .chezmoiscripts/
├── run_once_before_10-install-tools.sh.tmpl
└── run_after_20-generate-environment.sh.tmpl
新しい端末では、リポジトリをcloneして初期化コマンドを叩くだけで、設定ファイルの配置からツールのインストールまでが再現されます。
運用で気をつけたいこと
サードパーティCLIによる直接書き換え
Claude Codeの拡張ツールの中には、インストール時にsettings.jsonを直接書き換えるものがあります。この場合、実ファイルとdotfilesリポジトリのソースがずれます。chezmoiであればステータス確認コマンドで検出できるので、拡張ツールを導入したあとは一度確認する習慣をつけるとよいでしょう。
$ chezmoi status
MM .claude/settings.json
# M: 実ファイルとソースの両方が変更されている状態（ドリフト）
ここを放置すると、何が正で何が野良の変更か、だんだん分からなくなっていきます。実際、少し後回しにしただけで見失いかけたことがあります。
権限に関わる変更は自動化しすぎない
hooksやpermissionの変更は、コードのリファクタリングと違って「動けば良い」では済みません。何を許可し、何を許可しないかの判断が必ず伴います。dotfiles化してPRベースにするメリットは、まさにこの判断を人の目でレビューできる点にあります。自動追従・自動適用を組みすぎて、レビューを飛ばしてしまわないよう、自分では気をつけています。
シークレットは平文でコミットしない
APIキーやトークンを含む設定は、暗号化した上でコミットします。chezmoiであればage、あるいは外部のシークレット管理ツールと組み合わせる方法があります。「動くから」という理由で平文コミットしてしまうと、リポジトリを公開・共有した瞬間に漏洩します。
まとめ
chezmoiでClaude Code関連の設定をdotfiles管理して、前触れなくPCが壊れたとしてもメンタルを保てるようにしましょう！