🧰

AI時代のdotfiles: Claude Code/Codexの設定を持ち運び、面倒な管理を任せる

に公開1件

2020年に作ってほぼ放置していた dotfiles を、2026年10月に Claude Code と Codex に手伝ってもらって作り直しました。この記事では、その作業で得た教訓を中心にまとめます。

扱うのは次の2点です。1つ目は、Claude Code / Codex / Herdr の設定をバックアップとして持ちつつ、別の Mac にも持ち運べるようにする方法です。2つ目は、人間が面倒で放置しがちな構成やパッケージマネージャー周りの管理を、エージェントに任せるときの前提条件です。

ここでいう「AI ツール設定」は、指示ファイル(CLAUDE.md / AGENTS.md)、hooks、skill、plugin、MCP の設定を指します。

リポジトリは private のため、コードは抜粋で載せます。

対象読者

  • Claude Code や Codex の設定が増えてきて、別の Mac に持っていく方法に困っている方
  • dotfiles を「全部 symlink」で管理していて、ツールが設定を書き換えて困ったことがある方
  • 溜まった設定の棚卸しをエージェントに任せたいが、何を用意すれば安全か知りたい方

TL;DR

  1. AI ツールの設定は、ファイルの性質で「symlink / テンプレートとしてコピー / 一覧だけ持って再インストール / 持たない」の4つに分けて持つ
  2. 取得元が別にあるもの(skill、plugin、パッケージ)は、中身ではなく「何を入れるか」だけをスクリプトにして持つ
  3. エージェントに棚卸しを任せるなら、先に make check と冪等な deploy という安全網を用意する
  4. まずは、いま ~/.claude と ~/.codex に何があるかを4分類で仕分けるところから始める

なぜ今、dotfiles を見直したか

放置していた理由は単純で、直したい箇所は分かっていても、何が入っていて何が書いてあるかを突き合わせる作業が面倒だったからです。

状況が変わったのは、エージェントが日常の道具になってからです。指示ファイル、hooks、skill、plugin は人間の好みではなくエージェントの振る舞いを決めるので、Mac を替えても同じものが動く状態にしたくなりました。そして、この棚卸しをエージェント自身に任せれば、溜まっていた負債も一緒に片付くのではと考えました。

結果として、整理の PR 10本が1日でマージまで進みました。zsh の起動時間は、PR に書かせた計測で約1.3秒から約0.15秒になっています。

ここから先は、片付けた中身よりも、作業から得た教訓を書きます。

全体像: make install 一発で再現する

入口は Makefile に集約しています。新しい Mac での手順は次のとおりです。

git clone git@github.com:<ユーザー名>/dotfiles.git ~/dotfiles
cd ~/dotfiles
make install
gh auth login
codex login
claude

make install は、次のターゲットを書いた順に実行します。

make install の実行順。エージェント本体(agents)を先に入れ、設定の配置(deploy)、skill と plugin の復元が後に続く

agents では Claude Code と Codex を、Homebrew や npm ではなく公式のネイティブインストーラーで入れています。Claude Code のドキュメントでは、ネイティブインストールはバックグラウンドで自動更新され、Homebrew 版は手動更新だと説明されています。エージェント本体は更新が速いので、更新の手間を道具に任せられる入れ方を選びました。

https://code.claude.com/docs/en/setup

教訓1: 設定は「誰が書き換えるか」で4つに分ける

dotfiles の定番は、リポジトリに置いて $HOME へ symlink を張る方法です。AI ツールの設定も最初は全部これで済ませようとしましたが、ファイルによって、誰が書き換えるか、どこに正本があるかが違うため、うまくいきませんでした。

整理すると、次の4つになりました。

持ち方 対象 理由
symlink(リポジトリが正) CLAUDE.md、settings.json、AGENTS.md、hooks、自作 skill ツールが書き換えない。書き換えても差分として見たい
テンプレートとしてコピー ~/.codex/config.toml 実行中に端末固有の状態が書き足される
一覧だけ持って再インストール 公開 skill、marketplace と plugin、Homebrew、mise 中身は取得元が持っている
持たない API キー、認証情報、会話履歴、ログ、キャッシュ 機密か、端末固有か、再生成できる

仕分けの判断は、次の順に分岐させると迷いません。

設定ファイルを仕分ける順序。上から順に当てはめると4分類のどれかに落ちる

特に判断の決め手になったのは、3つ目の問い「ツールが実行中に書き換えるか」です。

私の環境では、Codex は実行中に project の trust や plugin、model の更新などを ~/.codex/config.toml に書き足していました。この設定は、symlink にすると端末固有の状態がリポジトリに混ざります。かといって、deploy のたびにテンプレートで上書きすると、書き足された内容が消えます。最初の deploy.sh は後者の作りで、make deploy のたびに設定が消えました。

今は、対象がなければコピーし、あれば触らない関数にしています。なお、Codex の公式ドキュメントには設定ファイルの置き場は書かれていますが、実行中に Codex 自身が書き足すことは書かれていません。ここは私の環境での観察です。

https://learn.chatgpt.com/docs/config-file/config-basic

install_template() {
  # Codex は実行中に端末固有の状態を書き足すので、一度置いたあとは上書きしない。
  # テンプレートを反映し直したいときは、対象を消してから deploy する
  if [[ -e "$target" ]]; then
    return
  fi
  ...
}

同じ skill を2つのエージェントに読ませるなら、実体は1か所に置く

自作 skill は .agents/skills/ に置き、3段の symlink でつないでいます。Claude Code と Codex で置き場が違っても、実体が1つなら、片方で直した内容がもう片方にも反映されます。

1か所に書いた skill を Claude Code と Codex の両方が読む。矢印は実体からリンクへの向き

教訓2: 取得元があるものは、中身ではなく一覧を持つ

最初の版では、公開されている skill を中身ごとリポジトリにコピーしていました。数千行が入り、更新にも追従できません。今は gh skill install で、Claude Code と Codex の両方に入れる一覧だけを持っています。gh skill は取得元を SKILL.md の frontmatter に記録するので、gh skill update で最新に追従できます。

https://cli.github.com/manual/gh_skill_install

install_skills() {
  local repo=$1; shift
  for skill in "$@"; do
    for agent in claude-code codex; do
      gh skill install "$repo" "$skill" --agent "$agent" --scope user --force
    done
  done
}

Claude Code の plugin も同じ考え方で、claude plugin list --json を jq で見て、未登録・未インストールのものだけを足すスクリプトにしています。何度実行しても同じ結果になる(冪等な)スクリプトにしておくと、新しい Mac でも既存の Mac でも同じコマンドで済みます。

一覧方式には、ツールの癖への対処を1か所に集められる利点もあります。たとえば、ある CLI が起動のたびに skill を上書きして取得元の情報を消す、skill が特定の版の CLI を前提にする、といった癖です。前者は環境変数で止めて更新を make skills-update に一本化し、後者は skill と CLI をセットで入れてセットで更新するようにしました。

パッケージマネージャーは、役割を決めて、エージェントのシェルからも見えるようにする

人間にとって面倒だったのは、道具ごとの役割分担を決めて維持することでした。いまの分担は次のとおりです。

管理対象 道具
CLI とアプリ Homebrew(Brewfile)
Go、Rust、Terraform と、それらで書かれた開発ツール mise
Python uv
Node Homebrew
zsh plugin sheldon
skill gh skill
Claude Code の plugin claude plugin(スクリプトで冪等に復元)

Node を mise に任せていない理由は、mise で Node の版を上げると、npm -g で入れた CLI が消えるからです。

役割分担でいちばん悩んだのは、mise に「バージョン指定ファイルをどこまで読ませるか」でした。最初は Go と Node も対象にしましたが、Go では、mise が go.mod の go 1.25.1 を必要なバージョンと解釈して、未インストールの版を要求し、警告が出ました。Node では、.nvmrc があるリポジトリでだけ mise 版に切り替わり、npm -g の CLI が分かれました。結局 idiomatic_version_file_enable_tools を Terraform だけに絞っています。実際に使ってみて初めて、妥当な範囲が分かる設定でした。

https://mise.jdx.dev/configuration/settings.html

AI 時代の配慮として、エージェントが叩くシェルの PATH も設計に入れています。対話シェルでは mise activate zsh を使い、エージェントやスクリプトのような非対話のプロセス向けには、.zprofile で PATH に入れた shim を使います。人間とエージェントが同じツールを見ていないと、「こちらでは動いたのに」が増えるからです。

教訓3: 棚卸しを任せるなら、安全網を先に用意する

任せられた理由は、エージェントの能力よりも、先に安全網を用意したことにあると考えています。

  1. make check(shellcheck、zsh -n、jq empty)と make deploy-test。エージェントが自分の変更を自分で確かめられる
  2. 同じものを GitHub Actions で回す。マージ前に壊れたことが分かる
  3. 指示ファイル。PR の作り方、確認の基準、機密の扱い
  4. 機密を持たない設計。dotfiles を丸ごとエージェントに読ませても困らない
  5. 仕事用や Mac 固有の設定を別ファイルに分け、必要な Mac でだけ読む形にする。共通部分を安心して触らせられる

make deploy-test は、一時ディレクトリを HOME にして deploy.sh を2回実行します。2回目に何か出力があれば、冪等でないとして失敗させる仕組みです。

deploy-test:
	@home="$$(mktemp -d)"; \
	HOME="$$home" DOTPATH="$(DOTPATH)" bash "$(DOTPATH)/scripts/deploy.sh" >/dev/null; \
	HOME="$$home" DOTPATH="$(DOTPATH)" bash "$(DOTPATH)/scripts/deploy.sh" | grep . && { echo 'deploy.sh is not idempotent.' >&2; exit 1; }; \
	...

進め方は、変更を小さな PR に分けて積み、各 PR の本文に「マージ後の作業」と「確認したこと」を書かせる形にしました。検証は、一時的な ZDOTDIR や一時 HOME を使わせて、自分のホームを汚さないようにしています。コード中のコメントは why だけにする、と指示ファイルに書いておくと、後で別のエージェントが触るときの判断材料にもなります。

指示ファイルも dotfiles で育てる

CLAUDE.md と AGENTS.md も symlink で管理しています。エージェントの失敗を見て直したルールが、次の Mac にも引き継がれます。直したルールの1つは、強い強調語(「必ず」「禁止」)を普通の指示に書き換えたことです。Anthropic のガイドでは、新しいモデルは強い表現に過剰に反応しやすいと説明されています。そのため「CRITICAL: You MUST use this tool when...」のような書き方は、普通の指示に戻すよう勧められています。機密情報の扱いだけは、例外なく守らせるために強調したまま残しています。

https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/claude-prompting-best-practices

教訓4: エージェントは「書いたこと」と「反映されていること」の差を拾う

棚卸しを任せて分かったのは、エージェントが得意なのは「設定ファイルに書いてあること」と「実環境で起きていること」を突き合わせる作業だということです。

見つかったのは、おおよそ3種類でした。

  • 動いているので気づかなかった死んだ設定(存在しないファイルを読みに行くもの)
  • 書いたつもりだったのに、別の plugin に上書きされて反映されていない設定
  • 昔コピペしたままの危険な既定(証明書の検証を切る curl のオプションなど)

人間は「書いたこと」を覚えていて、「実際に反映されていること」は確かめません。エージェントは実際にシェルを起動して計測するので、この食い違いをよく拾いました。

エージェントも壊す。戻せる作りにしておく

うまくいった話だけではありません。エージェントの変更が原因の不具合が、3件出ています。deploy による設定の上書き、mise の読む対象が広すぎたことによる警告、移行でコマンドを1つ消したことによる別のコマンドの破損です。

この3件から得た教訓は2つあります。

1つ目は、バックアップを取る deploy にしておくと、エージェントが壊しても戻せることです。実際、消えた Codex の設定は、deploy.sh が退避したファイルから復元できました。

2つ目は、静的チェックの限界です。make check と deploy-test は構文と冪等性までで、「実行時にツールが書き換える」「実環境で警告が出る」類の不具合は検出できませんでした。そこで次の図のように、実際に使って気づいた違和感を次の PR に回す短いサイクルにしています。

静的チェックで確かめ、実際に使った違和感を次の PR にする。F から B に戻る矢印が、静的チェックの限界を補っている

Herdr と wt で、複数のエージェントを並べる

Herdr は、コーディングエージェント向けのターミナルマルチプレクサです。

https://github.com/herdrdev/herdr

dotfiles には、Herdr が自動で入れる状態通知のスクリプトも含めています。このファイルには「再インストールや更新で上書きされる」という注記があるので、リポジトリ側を正にして、SessionStart hook から呼びます。

worktree を開く操作は、bin/wt の1本にまとめています。

wt                      # worktree を選んで Herdr で開く
wt new [branch] [base]  # worktree と workspace をまとめて作る
wt del [path]           # workspace ごと片付ける(branch は残す)

開いた workspace には、メインとサブの2体のエージェントと、yazi、lazygit、terminal が並びます。別の pane から名前を指定してプロンプトを送れるので、片方に実装、もう片方にレビュー、という分担もできます。以前は複数のコマンドに分かれていて、移行のたびに壊れていたため、1本にまとめました。

機密情報とトレードオフ

同期しないものは README に明記し、指示ファイルでは、次の3つを例外なく守らせています。機密情報を出力しないこと、コマンドの引数に展開しないこと(エラーメッセージやプロセス一覧に出るため)、存在は有無だけで確認することです。

速さを取っている部分もあります。

  • エージェントの承認プロンプトを減らし、確認の手間より作業の速さを取っている
  • statusLine の npx ccusage@latest と MCP の npx chrome-devtools-mcp@latest は、毎回最新を取りに行く

この分、指示ファイルと「機密を置かない」設計で守っています。ただし、@latest を毎回取る部分は、サプライチェーンの観点では版を固定するほうが安全です。

まだ途中のこと

  • Codex の config.toml は、テンプレートと実際の ~/.codex/config.toml の差分を取り込む手順がありません。持ち運びたい項目を定期的にエージェントに拾わせる運用を考えています
  • make check は構文チェックまでで、macOS 依存の部分(brew bundle、Herdr)は CI で確かめていません。CI を ubuntu で回しているのは、private リポジトリでは macOS ランナーが Linux の10倍の料金だからです

終わりに

ここまでの話は、個人の macOS 環境で、1人が使う前提です。チームで共有する設定や Linux には、そのまま当てはまらない部分があります。たとえば、承認プロンプトを減らす運用は、1人で、機密を置かない設計にしているから成り立っています。

最初の一歩は、手元で ls -l ~/.claude ~/.codex を実行して、実体のファイルと symlink を見分けることです。実体のまま残っているファイルに「誰が書き換えるか」を問うと、4分類のどこに入れるかが決まります。

参考

Discussion

あいちゃん / aichance|AI開発者あいちゃん / aichance|AI開発者

「指示ファイルも dotfiles で育てる」の AGENTS.md の symlink と、移行後に実際の反映を確かめる話に関連する測定です。自作の Agent Relay Check v0.1.3 で、合成データの global AGENTS.md を4通りにして比較しました。記事の環境や private repo を検証したものではありません。

macOS / Node22.23.4 / Codex0.164.0 では、通常ファイル・symlink・リンク先の内容更新はいずれも検出件数1、リンク切れは0でした。ただし全件 INSPECTED のままで、内容更新も件数には出ません。「配置できた」「新しい内容がモデルに届いた」は別に確認する必要がある、という結果でした。

実測表・通常の指示を変えない4対照の再現手順・実行前のソース確認 を公開しました。既存の Node22+ / stable Codex0.163.0 または0.164.0 がある場合、共通ZIPを展開した中で、自分のプロジェクトに対して次を実行できます。

node cli.mjs inspect --project "/path/to/your project"

モデル呼び出しや指示の編集は不要ですが、Codex起動時の通常の通信・メタデータ書込みはあり得ます。対応外の版や確認できない構成は INCONCLUSIVE です。検出は内容・遵守の証明ではなく、実際の合言葉の受領を調べる別手順は既存の gpt-6.1-sol/MAX 認証・利用枠で1回の推論を使います。

次に別Macへ移す/指示を更新する機会に、移行前後の比較が役立つか試していただけたら嬉しいです。共有いただける場合は CLI/Node版・status・other_native_source_count・cleanup_confirmed だけで大丈夫です。privateな指示やパス、認証情報は不要です。