【保存版】dotfiles運用の最終形：Shell / Ansible / AI（Claude CLI）を組み合わせた壊れない開発環境

    graph LR
    A[この記事] --> B[Shell/Ansible/AIの<br>役割分担が分かる]
    A --> C[冪等性の概念が<br>腹落ちする]
    A --> D[自分の構成を<br>設計できる]
    A --> E[Claude CLI活用の<br>プロンプト集]
  

    graph TB
    subgraph "dotfilesの本質"
        A[設定ファイルのバックアップ] --> B[環境の再現性]
        B --> C[開発思想の言語化]
        C --> D[自分専用OSの設計図]
    end
  

    graph LR
    subgraph GUI
        G1[マウス操作] --> G2[スクリーンショットで記録]
        G2 --> G3[手順書が陳腐化]
    end

    subgraph CLI
        C1[コマンド入力] --> C2[スクリプトとして保存]
        C2 --> C3[Git管理で履歴追跡]
    end
  

    #!/bin/bash
set -euo pipefail

DOTFILES_DIR="$(cd "$(dirname "$0")" && pwd)"

# シンボリックリンクを作成
ln -sf "$DOTFILES_DIR/.zshrc" "$HOME/.zshrc"
ln -sf "$DOTFILES_DIR/.vimrc" "$HOME/.vimrc"
ln -sf "$DOTFILES_DIR/.gitconfig" "$HOME/.gitconfig"
ln -sf "$DOTFILES_DIR/.tmux.conf" "$HOME/.tmux.conf"

# 必要なディレクトリを作成
mkdir -p "$HOME/.config/nvim"
ln -sf "$DOTFILES_DIR/nvim/init.lua" "$HOME/.config/nvim/init.lua"

echo "Dotfiles installed successfully!"
  

    # ❌ 冪等性がない（2回実行すると二重追記）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

# ⚠️ 部分的な冪等性（存在チェック）
if ! grep -q 'export PATH="$HOME/.local/bin:$PATH"' ~/.zshrc; then
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
fi
  

    # OS判定
if [[ "$OSTYPE" == "darwin"* ]]; then
  # macOS
  brew install ripgrep
elif [[ -f /etc/debian_version ]]; then
  # Debian/Ubuntu
  sudo apt-get install -y ripgrep
elif [[ -f /etc/redhat-release ]]; then
  # RHEL/CentOS
  sudo dnf install -y ripgrep
fi
  

    sequenceDiagram
    participant User
    participant Shell
    participant Ansible
    participant System

    Note over User,System: Shellの場合
    User->>Shell: install.sh 実行（1回目）
    Shell->>System: ファイル追記
    System-->>Shell: 成功
    User->>Shell: install.sh 実行（2回目）
    Shell->>System: ファイル追記（二重追記！）
    System-->>Shell: 成功（だが状態が壊れる）

    Note over User,System: Ansibleの場合
    User->>Ansible: playbook 実行（1回目）
    Ansible->>System: 状態を確認 → 変更を適用
    System-->>Ansible: changed
    User->>Ansible: playbook 実行（2回目）
    Ansible->>System: 状態を確認 → すでに目的の状態
    System-->>Ansible: ok（変更なし）
  

    # Shell: 手順を記述
ln -sf ~/dotfiles/.zshrc ~/.zshrc
  

    # Ansible: 状態を宣言
- name: .zshrc のシンボリックリンクを作成
  ansible.builtin.file:
    src: "{{ dotfiles_dir }}/.zshrc"
    dest: "{{ ansible_env.HOME }}/.zshrc"
    state: link
  

    flowchart TD
    Start([タスクを定義]) --> Q1{シンボリックリンク<br>作成だけ？}
    Q1 -->|はい| Shell[Shell で十分]
    Q1 -->|いいえ| Q2{パッケージ<br>インストールが必要？}
    Q2 -->|はい| Q3{複数OS対応<br>が必要？}
    Q3 -->|はい| Ansible[Ansible 推奨]
    Q3 -->|いいえ| Q4{冪等性が<br>重要？}
    Q2 -->|いいえ| Q4
    Q4 -->|はい| Ansible
    Q4 -->|いいえ| Shell
  

    graph TB
    subgraph "❌ 危険なパターン"
        A1[Claude CLI] -->|"全自動で"| B1[設定ファイル生成]
        B1 -->|"そのまま"| C1[本番適用]
        C1 -->|"結果"| D1[意図しない変更]
    end

    subgraph "✅ 安全なパターン"
        A2[Claude CLI] -->|"生成"| B2[設定ファイル案]
        B2 -->|"人間がレビュー"| C2[修正・承認]
        C2 -->|"適用"| D2[意図通りの変更]
    end
  

    真実のソース
├── 設計意図 → 人間の頭 + README.md
├── あるべき状態 → Ansible playbook
└── 実際の設定 → Git管理されたdotfiles
  

    dotfiles/
├── README.md                    # 設計意図・使い方
├── install.sh                   # エントリーポイント（軽量）
├── Makefile                     # タスクランナー
│
├── ansible/
│   ├── site.yml                 # メインplaybook
│   ├── inventory/
│   │   └── localhost.yml        # ローカル用インベントリ
│   ├── group_vars/
│   │   └── all.yml              # 共通変数
│   └── roles/
│       ├── common/              # 共通設定
│       │   └── tasks/
│       │       └── main.yml
│       ├── shell/               # シェル設定
│       │   ├── tasks/
│       │   │   └── main.yml
│       │   └── files/
│       │       ├── .zshrc
│       │       └── .zprofile
│       ├── neovim/              # Neovim設定
│       │   ├── tasks/
│       │   │   └── main.yml
│       │   └── files/
│       │       └── init.lua
│       ├── tmux/                # tmux設定
│       │   ├── tasks/
│       │   │   └── main.yml
│       │   └── files/
│       │       └── .tmux.conf
│       └── git/                 # Git設定
│           ├── tasks/
│           │   └── main.yml
│           └── templates/
│               └── .gitconfig.j2
│
├── scripts/                     # 補助スクリプト
│   ├── bootstrap.sh             # Ansible前の準備
│   └── update.sh                # 更新用
│
└── .claude/                     # Claude CLI用プロンプト
    └── commands/
        ├── review.md            # レビュー用
        └── generate-role.md     # role生成用
  

    graph TB
    subgraph "エントリーポイント"
        A[install.sh] -->|"Ansible準備"| B[bootstrap.sh]
    end

    subgraph "メイン処理"
        B --> C[Ansible playbook]
        C --> D[roles/common]
        C --> E[roles/shell]
        C --> F[roles/neovim]
        C --> G[roles/tmux]
    end

    subgraph "補助"
        H[Claude CLI] -.->|"生成支援"| C
        H -.->|"レビュー"| I[人間]
        I -->|"承認"| C
    end
  

    # roles/shell/tasks/main.yml
- name: .zshrc のシンボリックリンクを作成
  ansible.builtin.file:
    src: "{{ role_path }}/files/.zshrc"
    dest: "{{ ansible_env.HOME }}/.zshrc"
    state: link
    force: yes
  

    # Makefile
.PHONY: check apply

check:  ## 変更内容を確認（dry-run）
	ansible-playbook ansible/site.yml --check --diff

apply:  ## 変更を適用
	ansible-playbook ansible/site.yml
  

    # ansible/site.yml
- hosts: localhost
  roles:
    - { role: common, tags: ['common'] }
    - { role: shell, tags: ['shell', 'zsh'] }
    - { role: neovim, tags: ['neovim', 'editor'] }
    - { role: tmux, tags: ['tmux'] }
  

    # Neovim設定だけ更新
make apply TAGS=neovim

# Makefile内
apply:
	ansible-playbook ansible/site.yml $(if $(TAGS),--tags $(TAGS),)
  

    # 新しいroleの雛形を生成
claude "Ansibleのroleを生成してください。

## 要件
- role名: nodejs
- 目的: Node.jsとnpmをインストールし、グローバルパッケージを管理
- 対応OS: macOS (Homebrew), Ubuntu (apt)
- 冪等性を担保すること

## 出力形式
- tasks/main.yml
- defaults/main.yml（変数のデフォルト値）
- vars/main.yml（OS別の変数）

## 追加要件
- Node.jsのバージョンは変数で指定可能に
- pnpmもインストール
- グローバルパッケージのリストは変数で定義"
  

    # エラーログを渡して修正案を得る
cat ansible-error.log | claude "このAnsible実行ログのエラーを分析し、
修正案を提示してください。

## 出力形式
1. エラーの原因（1-2文で簡潔に）
2. 修正すべきファイルと変更内容
3. 修正後のYAMLコード

## 注意
- 冪等性を壊さないこと
- OS固有の問題であれば when 句で対応
- shell/command モジュールは最終手段"
  

    # 既存roleのレビュー
cat roles/shell/tasks/main.yml | claude "このAnsible taskファイルをレビューしてください。

## チェック項目
1. セキュリティリスク（パーミッション、シークレット管理）
2. 冪等性（何度実行しても安全か）
3. 可読性（タスク名、コメント）
4. ベストプラクティス（shell/commandの多用、ハードコード）

## 出力形式
- 問題点: 重要度（高/中/低）と説明
- 改善案: 具体的なコード修正
- 良い点: 1-2個（モチベーション維持のため）"
  

    # 複雑な設定ファイルの説明を生成
cat .zshrc | claude "この.zshrcの内容を分析し、
各セクションの目的を説明してください。

## 出力形式
1. 全体の構成（目次形式）
2. 各セクションの説明（何をしているか、なぜ必要か）
3. 改善提案（あれば）

## 注意
- 初学者にも分かる説明
- 不要な設定があれば指摘"
  

    <!-- .claude/commands/review-role.md -->
# Ansible Roleレビュー

以下のAnsible roleをレビューしてください。

## チェック項目
1. 冪等性が担保されているか
2. shell/command モジュールを不必要に使っていないか
3. 変数のデフォルト値が適切か
4. タスク名が意図を示しているか

## 出力
- 問題点と改善案を箇条書きで
  

    # 使い方
cat roles/neovim/tasks/main.yml | claude /review-role
  

    # ❌ アンチパターン
if [[ "$OSTYPE" == "darwin"* ]]; then
  if command -v brew &> /dev/null; then
    if ! brew list ripgrep &> /dev/null; then
      brew install ripgrep
    fi
  else
    echo "Homebrew not found, installing..."
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    brew install ripgrep
  fi
elif [[ -f /etc/debian_version ]]; then
  if ! dpkg -l ripgrep &> /dev/null; then
    sudo apt-get update
    sudo apt-get install -y ripgrep
  fi
fi
  

    # ✅ 改善後
- name: ripgrep をインストール
  ansible.builtin.package:
    name: ripgrep
    state: present
  become: "{{ ansible_os_family != 'Darwin' }}"
  

    # ❌ アンチパターン
claude "Neovimの設定を最適化して" > ~/.config/nvim/init.lua
# そのまま適用して、既存設定が消える...
  

    # ✅ 改善後
claude "Neovimの設定を最適化して" > /tmp/init.lua.new
diff ~/.config/nvim/init.lua /tmp/init.lua.new
# 差分を確認してから手動でマージ
  

    # ❌ アンチパターン
- name: ripgrep をインストール
  ansible.builtin.shell: |
    if ! command -v rg &> /dev/null; then
      brew install ripgrep
    fi
  args:
    executable: /bin/bash
  

    # ✅ 改善後
- name: ripgrep をインストール (Homebrew)
  community.general.homebrew:
    name: ripgrep
    state: present
  when: ansible_os_family == 'Darwin'
  

    # ❌ アンチパターン
- file:
    src: "{{ dotfiles_dir }}/.zshrc"
    dest: "{{ ansible_env.HOME }}/.zshrc"
    state: link
  

    # ✅ 改善後
- name: zsh設定ファイルをホームディレクトリにリンク（dotfilesで一元管理するため）
  ansible.builtin.file:
    src: "{{ role_path }}/files/.zshrc"
    dest: "{{ ansible_env.HOME }}/.zshrc"
    state: link
    force: yes  # 既存ファイルがあっても上書き
  

    graph TB
    A[設計なし] -->|"場当たり的な設定"| B[再現不可能]
    C[設計あり] -->|"意図を持った設定"| D[再現可能]
    D --> E[自動化可能]
    E --> F[共有可能]
  

    【新記事】dotfiles運用の最終形

Shell × Ansible × Claude CLI の役割分担を整理しました。

- Shellの限界と「冪等性」の概念
- Ansibleを個人用途で使う判断基準
- AIを"実行者"にしてはいけない理由
- コピペ可能なClaude CLIプロンプト集

「自分専用OS」の設計思想を持つエンジニアへ。

#dotfiles #Ansible #ClaudeCLI #開発環境