Claude Code の設定を dotfiles で管理する完全ガイド｜カスタマイズで AI 開発を効率化する

はじめに：デフォルト設定のまま使い続けていませんか？

Claude Code を使い始めて数週間が経つと、こんな不満を感じる方が多いはずです。

• 承認プロンプトが頻発して集中が途切れる（承認疲れ）
• トークン残量が見えず、作業中に突然リミットに到達する
• 同じ指示を毎回手で打ち込んでいる

これらはすべて、設定のカスタマイズで解決できます。この記事では ~/.claude/ の設定を dotfiles で管理する方法を、実際の設定ファイル付きでステップバイステップに解説します。

前提環境：Claude Code インストール済み、Git の基本操作が分かる、macOS / Linux 所要時間の目安：Step 1〜3 で約 30 分

Step 0：設定体系を 5 分で理解する

手順に入る前に、Claude Code の設定体系を押さえておきましょう。ここを飛ばすと後で必ず詰まります。

3 つのスコープ

CLAUDE.md と settings.json の違い

最も混同されやすいポイントです。

• CLAUDE.md = Claude への「指示書」。コーディング規約・設計方針・行動ルールを書く。全スコープの内容が連結されて Claude に渡される
• settings.json = Claude Code 本体の「動作設定」。使用モデル・権限制御・hooks を設定する。スカラー値は高優先度スコープで上書き、配列は結合される

「指示を書いたのに Claude が守らない」という悩みの多くは、settings.json に書くべき内容を CLAUDE.md に書いてしまっている（またはその逆）が原因です。

権限の評価順序：deny → ask → allow

deny はいかなる allow でも打ち消せません。「許可したはずのコマンドが通らない」ときは、より上位のスコープで deny が設定されていないか確認してください。

Step 1：dotfiles リポジトリを作り、~/.claude/ を移す

ディレクトリ構成

~/dotfiles/
└── .claude/
    ├── CLAUDE.md         # Claudeへの指示書
    ├── settings.json     # Claude Code本体の設定
    ├── commands/         # カスタムスラッシュコマンド
    ├── agents/           # サブエージェント定義
    └── scripts/          # statusLineスクリプトなど

移行手順

# 0. stowをインストール（未インストールの場合）
if ! command -v stow &> /dev/null; then
    apt-get install -y stow 2>/dev/null || \
    brew install stow 2>/dev/null || \
    yum install -y stow 2>/dev/null
fi

# 1. 既存設定をバックアップ
cp -r ~/.claude ~/.claude.bak

# 2. dotfilesリポジトリのディレクトリを作成
mkdir -p ~/dotfiles/.claude/{commands,agents,scripts}

# 3. 既存の設定ファイルを移動
mv ~/.claude/CLAUDE.md ~/dotfiles/.claude/
mv ~/.claude/settings.json ~/dotfiles/.claude/

# 4. 既存の.claudeディレクトリを削除（stowがシンボリックリンクを管理するため手動ln -sfは不要）
rm -rf ~/.claude

# 5. stowでシンボリックリンクを張る
cd ~/dotfiles && stow --target=$HOME .

# 6. 確認
ls -la ~/.claude  # -> ~/dotfiles/.claude へのシンボリックリンクが表示される

GNU Stow を使う場合：

# stowが未インストールの場合はインストール
if ! command -v stow &> /dev/null; then
    apt-get install -y stow 2>/dev/null || \
    brew install stow 2>/dev/null || \
    yum install -y stow 2>/dev/null
fi

# dotfilesディレクトリが存在することを確認してからstow実行
mkdir -p ~/dotfiles
cd ~/dotfiles && stow --target=$HOME .

.gitignore に入れるべきもの

# 絶対にコミットしてはいけないもの
.claude/.credentials.json
.claude/secrets/

# ローカル状態（共有しても意味がない）
.claude/.history
.claude/todos/

API キーや認証情報はファイルの「置き場所の名前」まで記録するにとどめ、値そのものは絶対にコミットしないでください。

Step 2：auto モードで「承認疲れ」を解消する

auto モードとは

2026 年 8 月 14 日から、Pro / Max / Team プランの新セッションで auto がデフォルトになりました。

実際の計測では、危険なコマンドのブロック率が auto モード：89%、手動承認：14% という結果が報告されています。「自動化＝危険」という直感とは逆に、適切なブロックリストを持つ auto モードの方が安全なのです。

settings.json に明示的に設定する

プラン変更やチーム環境での再現性のため、デフォルトに任せず明示的に指定することを推奨します。

// ~/.claude/settings.json
{
  "permissions": {
    "defaultMode": "auto"
  },
  "viewMode": "focus"
}

"viewMode": "focus" は、自動実行中の出力を集約して表示を整理します。auto モードとの組み合わせで監視負荷を大きく下げられます。

deny リストで「絶対やらせないこと」を先に決める

deny を固めてから allow を広げる順番が重要です。

{
  "permissions": {
    "defaultMode": "auto",
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)",
      "Bash(curl *production*:*)",
      "Bash(sudo:*)"
    ]
  }
}

Step 3：statusLine でトークン使用率を常時可視化する

「あと何割使えるか」が常に見えているだけで、作業の計画の立て方が根本から変わります。

スクリプトを作成する

# ~/dotfiles/.claude/scripts/statusline.sh
#!/usr/bin/env bash

INPUT="$1"

# JSONから値を取得
USED=$(echo "$INPUT" | jq -r '.context_window.used_percentage // 0')
MODEL=$(echo "$INPUT" | jq -r '.model.display_name // "unknown"')
USED_INT=${USED%.*}

# 使用率に応じて色を変える
if [ "$USED_INT" -ge 80 ]; then
  COLOR="\033[31m"   # 赤
elif [ "$USED_INT" -ge 60 ]; then
  COLOR="\033[33m"   # 黄
else
  COLOR="\033[32m"   # 緑
fi
RESET="\033[0m"

echo -e "${COLOR}[${USED_INT}%]${RESET} ${MODEL}"

# 実行権限を付与
chmod +x ~/dotfiles/.claude/scripts/statusline.sh

settings.json に登録する

{
  "statusLine": "~/dotfiles/.claude/scripts/statusline.sh"
}

表示が崩れるときのチェックリスト

1. 実行権限があるか → chmod +x を確認
2. シェバン行があるか → #!/usr/bin/env bash を1行目に
3. 絶対パスで指定しているか → ~ が展開されない環境では /home/user/... に変更
4. 出力の末尾に余分な改行がないか → echo -n または printf を使う

Step 4：繰り返し作業をカスタムスラッシュコマンドで定型化する

コマンドの作り方

~/.claude/commands/ 以下に Markdown ファイルを置くだけです。ファイル名がそのままコマンド名になります。

~/.claude/commands/
├── address.md        # /address コマンド
└── reply-review.md   # /reply-review コマンド

実用例 1：/address（レビュー指摘への対応）

<!-- ~/.claude/commands/address.md -->
以下のレビュー指摘に対して修正を行ってください。

修正方針：
- 指摘の意図を正確に把握してから実装する
- 既存のテストが壊れていないことを確認する
- 修正範囲は指摘箇所のみに限定し、無関係な変更は加えない

レビュー指摘：
$ARGUMENTS

実用例 2：/reply-review（レビューコメントへの返信）

<!-- ~/.claude/commands/reply-review.md -->
以下のコードレビューコメントに対する返信文を作成してください。

返信のトーン：丁寧かつ簡潔に、修正した内容または対応しない理由を明示する。

コメント：
$ARGUMENTS

「自分だけのコマンド」を見つける方法

直近 1 週間で 3 回以上 Claude に打ち込んだ指示を洗い出してみてください。その指示が最有力候補です。

Step 5：専用エージェントで Git 操作を任せる（応用編）

スラッシュコマンドが「定型プロンプトの実行」なのに対し、~/.claude/agents/ に置くサブエージェントは別の文脈で動作する専門家です。現在の作業コンテキストを汚さずに、特定タスクを切り離して実行できます。

rebaser：散らかったコミットを整理する

---
name: rebaser
description: 作業中のコミット履歴を整理する。squash・reorder・reword を適切に使い分ける
tools:
  - Bash
  - Read
permissions:
  allow:
    - "Bash(git rebase*:*)"
    - "Bash(git log*:*)"
    - "Bash(git diff*:*)"
  deny:
    - "Bash(git push*:*)"
---

現在のブランチのコミット履歴を確認し、以下の方針で整理してください：
- WIPコミットを適切にsquashする
- コミットメッセージがConventional Commitsに準拠しているか確認する
- 変更の順序が論理的になるよう並び替える

reworder：コミットメッセージだけを直す

---
name: reworder
description: コミットメッセージのみを修正する。コードは一切変更しない
tools:
  - Bash
  - Read
permissions:
  allow:
    - "Bash(git log*:*)"
    - "Bash(git commit --amend*:*)"
  deny:
    - "Bash(git add*:*)"
    - "Bash(git checkout*:*)"
---

コードの変更は一切行わず、コミットメッセージの文言のみを改善してください。

Step 6：設定を継続的にメンテナンスする

dotfiles 化した設定は「作って終わり」では腐ります。1〜2 ヶ月ごとの棚卸しをルーティン化してください。

棚卸しチェックリスト

# CLAUDE.mdの行数を確認（200行を超えていたら整理のサイン）
wc -l ~/.claude/CLAUDE.md

# 使っていないコマンドを確認
ls -lt ~/.claude/commands/  # 更新日が古いものは削除候補

# settings.jsonの権限設定を見直す
cat ~/.claude/settings.json

CLAUDE.md を 200 行以下に保つコツ

• プロジェクト固有の規約は ~/.claude/CLAUDE.md ではなく ./.claude/CLAUDE.md へ移す
• 「〜しないでください」という否定形の指示が重複していないか確認する
• 役割が被っている指示をまとめて1文にする

dotfiles を公開する前の確認

# シークレットスキャン（git-secretsなどのツールを推奨）
git secrets --scan

# またはgrepで簡易確認
grep -r "token\|secret\|password\|api_key" ~/dotfiles/.claude/

公開されている dotfiles（例：GitHub で zircote/.claude などを検索）を参考にするときは、そのまま貼り付けず、設定の意図を理解してから取り入れてください。

トラブルシューティング

Q. auto モードは本当に危険ではないのか？

危険なコマンドのブロック率は手動承認（14%）より auto モード（89%）の方が高い、という計測結果があります。ただし、deny リストを事前に設定しておくことが大前提です。業務リポジトリでさらに安全にしたい場合は、cage などのサンドボックスツールの導入を検討してください。

Q. CLAUDE.md に書いた指示が守られないのはなぜ？

よくある原因は 3 つです。①そもそも settings.json に書くべき設定（権限・モデル指定）を CLAUDE.md に書いている、②CLAUDE.md が 200 行を大幅に超えて重要な指示が埋もれている、③プロジェクトスコープの設定がユーザースコープを上書きしている。

Q. 複数マシンで設定が食い違う

dotfiles リポジトリを git pull していないか、シンボリックリンクが張られていないことが多いです。セットアップスクリプト（setup.sh）を dotfiles リポジトリに含めて、ln -sf コマンドを自動化しておくと防げます。

Q. dotfiles 化すると Claude Code のアップデートで壊れないか？

settings.json のスキーマ変更は Claude Code のリリースノートで告知されます。シンボリックリンク自体はアップデートで壊れませんが、1〜2 ヶ月ごとの棚卸し時にリリースノートも確認する習慣をつけてください。

まとめ：今日から始める優先順位

設定のカスタマイズは、一度に全部やろうとせず、段階的に導入するのがベストプラクティスです。

最初の 30 分でやること：

1. dotfiles 化とシンボリックリンク（Step 1）― 環境再現性の基盤
2. auto モード + deny リスト（Step 2）― 承認疲れの即時解消
3. statusLine でトークン使用率表示（Step 3）― 作業計画の質が上がる

次のステップ：

直近 1 週間で 3 回以上打ち込んだ指示を洗い出して、カスタムスラッシュコマンド化してください（Step 4）。繰り返しタスクが多い開発者ほど、ここでの効果が大きいです。

設定を公開している開発者の dotfiles を参考にしながら、自分の作業スタイルに合ったカスタマイズを段階的に深めていきましょう。

参考リンク

• 202608 個人的 claude code 設定（kawarimidoll / Zenn）
• Claude Code 公式ドキュメント：Status Line のカスタマイズ
• Claude Code 公式ドキュメント：権限とセキュリティ設定