端末交換を Claude Code と進めて分かった dotfiles の育てかた

業務用 Mac の端末交換を、dotfiles リポジトリと Claude Code で進めました。10 月 16 日に新端末を受け取り、18 日に作業を閉じるまで 2 日弱です。bootstrap.sh は 4 手順で終わりましたが、残作業は 40 項目近くあり、時間がかかったのは「入れた後」のほうでした。つまずいた箇所と、移行後に dotfiles を使いながら育てるための運用をまとめます。

手元にあった dotfiles

dotfiles は、ホームディレクトリにある . で始まる設定ファイル（.zshrc・.vimrc など）のことです。これらを Git リポジトリにまとめておくと、新しい端末でも clone すれば同じ環境を再現でき、変更の履歴も残ります。実体はリポジトリに置き、ホームからはシンボリックリンクを張るのが定番の構成です。

~/.zshrc -> dotfiles/stow/zsh/.zshrc
~/.vimrc -> dotfiles/stow/vim/.vimrc

交換前の時点で、リポジトリは次のツールで組んでいました。

管理対象は設定ファイルだけではありません。シェルとターミナル（fish・tmux・Ghostty）、エディタ（Neovim・VS Code の設定と拡張の一覧）、Git の設定とディレクトリごとのアカウント切り替えに加えて、macOS の defaults 設定、Claude Code の settings.json、移行と差分チェック用の Skills、移行手順のドキュメントも入れています。数年に 1 度は来る端末交換のたびに手で設定し直すのが面倒だったことと、人に環境を共有するときにリポジトリのリンクを渡せば済むようにしたかったことが、dotfiles を始めた理由です。

bootstrap.sh を叩けばだいたい揃うはずでした。メンテナンスまで手でやるのは続かないと考え、今回の移行作業は最初から Claude Code に任せる前提で進めました。

Issue を作業台帳にする

移行を始める前に、dotfiles リポジトリに「端末交換（2026-10-16）の記録と残作業」という Issue を 1 本立てました。中身は次のチェックリストです。

• 旧端末で済ませたこと
• 新端末で済ませたこと
• 残作業
• 気づいたこと

何かを直したら、そのコミットのハッシュを Issue に書き戻します。「何をなぜ変えたか」が後から追えるので、次の端末交換では「この Issue を見て、同じ問題が起きていないか確認して」と Claude Code に頼めます。

リポジトリに入れないものは Google Drive に逃がしました。~/Documents の中身などは、旧端末から Drive に上げておきます。秘密情報は「Google Drive から取得する」「Keychain に登録し直す」「再認証すれば済む」の 3 段階に分け、どれに当たるかをドキュメントに書いておきました。

「入れた後」のつまずき

自動化できたのはアプリや設定を「入れる」ところまでで、つまずきはその先にありました。

fish の起動とプロンプトの遅さを測って直す

以前から気になっていた fish の遅さも、この機会に直しました。測ってみると原因は複数ありました。

• gcloud の設定ファイルが、cd するたびに mise のフックを走らせていた。やっていたのは bin を PATH に足すことだけなので、直接足すようにした
• Homebrew の vendor_conf.d でも mise と direnv が有効化され、二重になっていた
• mise activate の出力をキャッシュし、uv の補完は遅延生成にした
• Enter を押すたびのカクつきは、プロンプトのたびに 205MB ある mise の実行ファイル（mise hook-env）を起動していたのが原因だった。ディレクトリを移動したときだけ更新するように変えた

体感の遅さには具体的な原因があります。測ってから直すと、どこに手を入れればよいかが数字で分かります。

Chrome のブックマークが旧端末とともに消える

いちばん痛かった失敗です。新端末に同期されたブックマークは、いちばん新しいものでも 2022 年のものでした。旧端末側で同期が止まっていたことに気づかず、ブックマークを書き出す前に端末を返却していました。新端末を受け取ったその日に旧端末を返していたので、取り戻せません。

対応として、ブックマークの書き出しと「返却前に引き継がれているか確認する」項目を移行手順書（docs/migration.md）に足しました。「同期されているはず」は確認するまで信用しない、そして返却は最後に、が教訓です。

毎日触るものから先に整える

失敗とは別に、順番の後悔もあります。bootstrap.sh はアプリのインストールから始まる作りで、macOS の defaults 設定と Google 日本語入力は後回しになっていました。その結果、キーリピートが遅く、トラックパッドも日本語入力も手に馴染まないまま移行作業を進めることになり、作業そのものが進みにくくなりました。

新端末ではまず手元の操作感（キーリピート・トラックパッド・日本語入力）から整え、そのあとでアプリを入れる順番に bootstrap.sh を直しています。本間さんの記事「毎日触るか、時間が縮むか。AI 開発環境の一軍の選び方」は、Mac のキーリピート設定から話を始め、「毎日触るか」を一軍を選ぶ基準の 1 つにしています。移行作業も同じで、毎日触るものが整ってからのほうが速く進みます。

細かいところでは、次のような発見もありました。

• ズームや Finder のサイドバーなど、defaults で書けない設定がある。これらは手順をドキュメントに残した
• ダークモードは defaults に書いても画面が切り替わらないため、System Events でも切り替えるようにした
• 標準ショートカットのウインドウ配置は一部のアプリでしか効かなかったので、Raycast に寄せた
• Raycast の Clipboard History も試したが、使い慣れた Clipy に戻した

移行後も dotfiles は直し続ける

移行を閉じたあとも、使っているうちに足りないものが見つかります。

設定が前提にしているものもリポジトリに入れる

Neovim を開くと plug#begin のエラーが出ました。init.vim は stow で配置されていたものの、プラグインマネージャの vim-plug 本体が入っていなかったためです。設定ファイルはあっても、設定が前提にしているものがリポジトリになかったことになります。vim-plug がなければ起動時に取ってくる処理を足しました（vim-plug の README にある書き方です）。

let data_dir = has('nvim') ? stdpath('data') . '/site' : '~/.vim'
if empty(glob(data_dir . '/autoload/plug.vim'))
  silent execute '!curl -fLo '.data_dir.'/autoload/plug.vim --create-dirs https://raw.githubusercontent.com/junegunn/vim-plug/master/plug.vim'
  autocmd VimEnter * PlugInstall --sync | source $MYVIMRC
endif

意図がずれたら言い直す

tmux のコピーモードで、Vim と同じく yy で 1 行コピーしたくなりました。最初に「yy を使いたい」と伝えたところ「Vim の yy」と受け取られ、Neovim 側を調べてもらう流れになりました。そちらはもう動いていたので、tmux のコピーモードの話だと言い直して認識が合いました。

実装は、tmux のキーテーブルで 2 打鍵のキーを作る形です。選択範囲があれば y 1 回でコピーし、なければ次の y を待つテーブルに切り替えます。

bind-key -T copy-mode-vi y if-shell -F "#{selection_present}" "send-keys -X copy-pipe-and-cancel pbcopy" "switch-client -T copy-mode-vi-y"
bind-key -T copy-mode-vi-y y send-keys -X copy-pipe-line-and-cancel "pbcopy"

動作確認も Claude Code に任せました。別の tmux サーバーを立て、Python の pty で本物のキー入力を流して確かめています。推測ではなく実際に動かした結果で判断してもらうと、「たぶん動きます」で終わらずに済みます。

入れたらその場で Brewfile にも足す

業務の途中で poppler が必要になったときは、brew install で入れると同時に Brewfile にも足しました。毎回 dotfiles 側で「これを入れて」と頼むのは面倒なので、環境を触ったらリポジトリに戻すまでを 1 セットにしています。戻さなかった変更は、次の端末交換で消えます。

それでも戻し忘れは出るので、環境とリポジトリのずれを洗い出す Claude Code の Skills（drift スキル）を作りました。「環境とずれてない？」と聞くだけで動き、Git・Homebrew・アプリ・mise・stow・fish・tmux・VS Code を順に調べます。結果は次の 3 種類で報告されます。

[OK] 未コミットの変更なし
[--] ずれている（リポジトリか環境に反映が要る）
[??] ずれではないが人が確かめる

スキルは調べて報告するだけで、直すのは頼まれてからにしています。ずれのどちらを正とするかは、その場の判断が要るためです。

まとめ

Claude Code と進めるときは、エラーをそのまま貼れば原因の特定から修正・確認まで任せられます。「教えて」と「やって」を言い分けると、どこまで手を動かしてもらうかを調整できます。意図がずれたらすぐに言い直し、Brewfile・設定ファイル・ドキュメントへ戻すところまでを 1 セットにすると、dotfiles は端末交換のたびに少しずつ育っていきます。

gaipack では、こうした開発環境づくりも含めて AI 駆動開発の実践知を社内で蓄積しています。開発チームへの Claude Code の定着についても、お気軽にご相談ください。