dotfiles を AI エージェント向けに再設計する — Claude Code / Codex 時代の開発環境最適化

AI が 1,339 回、人間が 80 回。

これは筆者が自分のシェル操作ログを集計したときに目にした数字です。Claude Code を日常的に使うようになった 2026 年、ターミナルを操作している主体はもはや人間ではなく AI エージェントになっていました。

しかし、筆者の dotfiles は依然として「人間のために」設計されたままでした。fzf 連携の cd が応答を待ち続け、cp -i の確認プロンプトでエージェントが停止し、vim が非対話起動でブロックする——10 年物の設定ファイルが、AI の前で次々と壊れ始めたのです。

この記事では、そうした経験をもとに「AI ファーストな dotfiles」へ移行した実践的な手順と、シェル起動時間を 0.5 秒 → 0.01 秒 に短縮した具体的な改善内容を解説します。

dotfiles と CLI AI エージェントの基礎

dotfiles とは何か

dotfiles とは ~/.zshrc、~/.zshenv、~/.gitconfig など、ファイル名がドット（.）で始まる設定ファイル群の総称です。現代のソフトウェアエンジニアの多くは、これらを GitHub リポジトリで管理し、新しいマシンにも一括展開する運用を採用しています。

# 典型的な dotfiles リポジトリの構成
# ~/.dotfiles/
# ├── zsh/
# │   ├── .zshrc
# │   └── .zshenv
# ├── git/
# │   └── .gitconfig
# └── install.sh

CLI AI エージェントはどうシェルを使うのか

Claude Code や Codex は、非対話シェルを長時間自律的に動かし続けます。「人間が 1 コマンドを打つ」前提で設計された設定が、このような連続操作環境と根本的にミスマッチを起こすのは必然です。

Anthropic の公式発表によれば、2026 年時点で Claude Code は社内 R&D 自動化の 26% を担い、約 3 万体のエージェントが稼働しています。CLI AI エージェントは「試験的な機能」ではなく、開発現場の中心に据えられています。

人間向け dotfiles が AI を詰まらせる 4 つのパターン

1. 対話的待ち受け（インタラクティブ地雷）

fzf を使ったインタラクティブな cd や git add、あるいは cp -i / mv -i / rm -i 系のエイリアスは、AI エージェントが対話できないため処理が止まります。

# 例：よくある fzf 連携の cd（AI には毒）
fcd() {
  local dir
  dir=$(find . -type d | fzf) && cd "$dir"
}

2. ブロッキングエディタ

EDITOR が vim や nvim のままだと、git commit のメッセージ編集などで AI がブロックします。エージェントはエディタのキーバインドを知っていても、TTY の外からは操作できません。

3. AI の学習知識と手元コマンドのズレ

GNU 版コマンドを BSD 版と異なる挙動になるようエイリアスしたり、独自のラッパー関数を定義していると、AI が期待する出力と実際の出力が食い違います。AI は自分の知識通りに動作することを前提にしているからです。

4. 肥大化したシェル環境

筆者の dotfiles をシェルスナップショットで確認すると 14,284 行 に達していました。大量の設定読み込みは AI エージェントが一連のコマンドを実行するたびに余計なコストを生み出します。

設計の原則：AI をデフォルトに、人間をオプトインに

環境変数と TTY 検出による判別

Claude Code は実行時に $CLAUDECODE 環境変数を、Codex は $CODEX_SANDBOX をそれぞれ設定します。TTY 検出と組み合わせることで、AI エージェントと人間を確実に判別できます。

# AI エージェントを検出する関数
_is_ai_agent() {
  [[ -n "$CLAUDECODE" || -n "$CODEX_SANDBOX" ]]
}

# TTY 判別（インタラクティブセッションかどうか）
_is_interactive() {
  [[ -t 0 && -t 1 ]]
}

「非人間なら即リターン」パターン

.zshrc の冒頭にガードを 1 行入れるだけで、劇的な改善が得られます。

# ~/.zshrc の冒頭に追加
# AI エージェント（または非インタラクティブ）なら人間向け設定をスキップ
if _is_ai_agent || ! _is_interactive; then
  # 最小限の環境変数のみ設定
  export EDITOR=true
  export PAGER=cat
  return
fi

# ---- ここから下は人間向け設定 ----
eval "$(starship init zsh)"
source ~/.zsh/fzf-integration.zsh
# ... 以下略

この 1 ブロックを追加するだけで、筆者の環境ではシェル起動時間が 0.5 秒 → 0.01 秒 に短縮されました。計測方法は次のコマンドで確認できます。

# シェル起動時間の計測
time zsh -i -c exit

実践ステップ①：AI をデフォルト化する

インタラクティブ設定を人間専用ブロックへ移す

# ~/.zshrc の構造例
# -------------------------------------------
# AI / 非インタラクティブ共通設定
# -------------------------------------------
export PATH="$HOME/.local/bin:$PATH"
export EDITOR=true          # AI がブロックしないよう true にする
export PAGER=cat            # less でなく cat をデフォルトに
export GIT_PAGER=cat

# AI エージェント / 非インタラクティブなら終了
if [[ -n "$CLAUDECODE" || -n "$CODEX_SANDBOX" || ! -t 1 ]]; then
  return
fi

# -------------------------------------------
# 人間専用設定（インタラクティブのみ）
# -------------------------------------------
eval "$(starship init zsh)"
eval "$(zoxide init zsh)"
source "$(brew --prefix)/opt/fzf/shell/key-bindings.zsh"

# エイリアス（eza などリッチ系は人間専用）
alias ls='eza --icons'
alias ll='eza -la --icons'

EDITOR の扱い

EDITOR=true は一見奇妙ですが、true は必ず終了コード 0 で即終了するコマンドです。AI エージェントが git commit などを実行しても、エディタが開くことなくスムーズに処理が続きます。人間がコミットメッセージを編集したい場合は、明示的に git commit -m "message" を使うか、環境変数を上書きします。

# ~/.zshrc の人間専用ブロックに追加
export EDITOR=nvim
export VISUAL=nvim

実践ステップ②：AI の知識と環境を一致させる

実際の開発現場では「AI が知っている通りにコマンドが動く」ことそのものに大きな価値があります。AI が ls -la を実行してもエイリアスで予期しない出力が返ってきたり、grep が色付き出力を前提に結果を解析しようとして失敗するケースは珍しくありません。

推奨プリインストールツール

AI エージェントが最も頻繁に使う現代的なツールをあらかじめ用意しておくことをベストプラクティスとして推奨します。

# macOS（Homebrew）の場合
brew install ripgrep fd jq yq bat git-delta

# Ubuntu/Debian の場合
apt install -y ripgrep fd-find jq

rg（ripgrep）、fd、jq はモデルの学習データに豊富に含まれており、AI が積極的に活用します。これらが存在しない環境では、AI は grep -r、find、python3 -c "import json" などの回り道を選びます。

CLAUDE.md / AGENTS.md を dotfiles に同梱する

コーディング規約や使ってほしいツールの情報を CLAUDE.md に記述し、dotfiles として管理することで、すべての作業ディレクトリに展開できます。

<!-- ~/.claude/CLAUDE.md の例 -->
# 開発規約

## コマンド規約
- ファイル検索には `fd` を使う（`find` より高速）
- テキスト検索には `rg` を使う（`grep` より高速）
- JSON 処理には `jq` を使う

## Git 規約
- コミットメッセージは Conventional Commits 形式
- feat / fix / docs / refactor / test / chore

実践ステップ③：Nix / home-manager による co-location 設計

設定とインストールを 1 ファイルにまとめる

Nix と home-manager を使うと、「このツールをインストールして、その設定はこう書く」という宣言をひとつのファイルで管理できます。ツールを削除すれば関連設定も自動的に消えるため、設定の肥大化が構造的に防がれます。

# ~/.config/home-manager/home.nix（抜粋）
{
  # AI 向け共通設定
  my.ai = {
    editor = "true";   # ブロッキングを避けるため
    pager  = "cat";
  };

  # 人間向け設定（インタラクティブ時のみ有効）
  my.human = {
    editor = "nvim";
    plugins = [ "fzf" "starship" "zoxide" ];
  };

  # 共通ツール（AI・人間ともに使用）
  home.packages = with pkgs; [
    ripgrep fd jq bat git-delta
  ];
}

この設計を適用した結果、シェルスナップショットが 14,284 行 → 339 行 に縮小しました。段階的に理解を深めていきましょうと言うと抽象的に聞こえますが、実際には「宣言していないものは存在しない」という Nix の哲学が、設定の自然なミニマル化を促します。

Nix を使わない場合の代替

Nix の導入ハードルが高い場合は、ディレクトリ分割 + source 戦略が現実的な選択肢です。

# ~/.zshrc の構造（Nix なし版）
source ~/.zsh/common.zsh      # AI・人間共通

_is_ai_agent && return        # AI はここで終了

source ~/.zsh/human.zsh       # 人間専用（fzf、starship 等）
source ~/.zsh/aliases.zsh     # 人間向けエイリアス

安全性：AI に破壊的コマンドを渡さないために

実際の開発現場で見落とされがちなのが、rm コマンドの扱いです。AI エージェントが rm -rf を実行した場合、人間と同様に取り消しができません。

参考になるアプローチとして、rm を自作ゴミ箱コマンド（例：gomi）にエイリアスする方法があります。

# ~/.zsh/common.zsh（AI・人間共通）
# rm の代わりにゴミ箱に移動する
if command -v gomi &>/dev/null; then
  alias rm='gomi'
fi

興味深いのは「AI をあえて誤解させたまま使わせる」という発想です。AI は rm を「ファイルを削除するコマンド」として認識していますが、実際にはゴミ箱に移動するだけです。AI の意図（削除したい）は達成されつつも、実際には取り消し可能な状態が保たれます。サンドボックスや権限設定と組み合わせることで、防衛の多層化が実現します。

コミュニティ事例：他の開発者はどうしているか

AI ファーストな dotfiles はコミュニティでも急速に広まっています。

yulonglin/dotfiles は AI 安全研究者向けに設計されており、Claude Code・Codex・Gemini CLI のすべてに対応した環境変数検出ロジックを実装しています。AIの種類を問わず共通の安全網を張るアプローチが参考になります。

atxtechbro/dotfiles はさらに踏み込んで「エージェントの並列化」「原則強制」「自己修復スタック」を dotfiles に組み込んでいます。AGENTS.md をリポジトリに同梱し、複数のエージェントが同じコーディング規約を共有する仕組みは、チーム開発への応用でも有効です。

これらの事例から読み取れる共通パターンは次の 3 点です。

1. 環境変数による AI 検出を全エージェント対応で実装する
2. CLAUDE.md / AGENTS.md を dotfiles で管理し、規約を宣言的に共有する
3. 破壊的操作をデフォルトで安全側に倒す（ゴミ箱、ドライラン等）

よくある質問（FAQ）

Q: 人間向け設定はすべて捨てる必要がありますか？

A: 不要です。「AI をデフォルト、人間をオプトイン」設計にすれば共存できます。eza は明示的に eza -la と打てば使えますが、ls のエイリアスはデフォルトに戻す——という粒度の制御が現実的です。

Q: どこから手を付けるのが最短ですか？

A: まず ~/.zshrc の冒頭に TTY 検出ガードを 1 ブロック追加するだけで大きく改善します。その後、fzf 系や確認プロンプト系エイリアスを人間専用ブロックへ移動させましょう。Nix への移行は最後のステップで構いません。

Q: Claude Code と Codex で設定は変わりますか？

A: 環境変数名が異なるだけです（$CLAUDECODE vs $CODEX_SANDBOX）。両者を || でまとめて検出し、同じ判定ロジックで処理できます。CLAUDE.md を dotfiles で管理すれば、両エージェントに同じ規約を適用できます。

Q: チーム全体に展開するときの注意点は？

A: 個人の dotfiles はあくまで個人環境のものです。チーム全体に規約を共有したい場合は、リポジトリルートの CLAUDE.md / AGENTS.md に記述するのが適切です。dotfiles はその土台（ツールの存在・コマンドの挙動）を整えるものと位置づけると役割が明確になります。

まとめ：dotfiles は「人間の道具」から「協働環境」になった

dotfiles は長らく「自分だけが使う設定ファイル」でした。しかし 2026 年現在、そのシェルを動かしている主体の大半は AI エージェントです。設定が人間専用のままであれば、AI は常にその摩擦と戦い続けます。

今日できる最小の一歩は、~/.zshrc に TTY ガードを 1 ブロック追加することです。たった数行で、シェル起動時間と詰まりの大半は解消されます。計測して初めて「0.5 秒が 0.01 秒になった」という効果が見えます。

段階的なアプローチとして、次の順序を推奨します。

1. 今日：~/.zshrc に AI 検出ガードを追加し、EDITOR=true / PAGER=cat を設定
2. 今週：インタラクティブ設定を人間専用ブロックに移動し、rg / fd / jq をインストール
3. 今月：Nix/home-manager、または source 戦略によるディレクトリ分割でコードを整理
4. 以降：CLAUDE.md を dotfiles で管理し、複数エージェント間での規約共有を確立

AI エージェントは優秀ですが、環境が整っていなければその能力を発揮できません。dotfiles を「人間と AI が共に快適に動ける協働環境」として再設計することが、2026 年以降の開発効率を左右するインフラ投資になるのです。