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

約16分で読めます by ぽんたぬき
Claude Code の設定を dotfiles で管理する完全ガイド|カスタマイズで AI 開発を効率化する

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

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

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

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

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

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


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

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

3 つのスコープ

スコープ 場所 git 管理 用途
User ~/.claude/ 個人管理 全プロジェクト共通の個人設定
Project ./.claude/ チームで共有 リポジトリごとのチーム設定
Local CLAUDE.local.md 除外(.gitignore) 個人の一時的な上書き

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スクリプトなど

移行手順

# 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 を使う場合:

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 を参考にしながら、自分の作業スタイルに合ったカスタマイズを段階的に深めていきましょう。


参考リンク

関連記事

ブラウザクローンデータとは?二段階認証が突破される仕組みと今すぐできる対策

ブラウザクローンデータとは?二段階認証が突破される仕組みと今すぐできる対策

ブラウザクローンデータとは?二段階認証が突破される仕組みと今すぐできる対策 「二段階認証を設定しているから、うちのアカウントは大丈夫」——そう思っている方に、少し不安な話をしなければなりません。 ダークウェブの闇市場では今、IDとパスワードのリストより「ログイン済みの状態ごとコピーしたブラウザクローンデータ」のほうが高値で取引されています。NordVPNの調査(2025年6月〜2026年6月)によ...

【2026年】MUJIアプリで最大2726万件の個人情報漏洩|不正アクセスの手口と企業・利用者が今すぐやるべき対策

【2026年】MUJIアプリで最大2726万件の個人情報漏洩|不正アクセスの手口と企業・利用者が今すぐやるべき対策

【2026年】MUJIアプリで最大2726万件の個人情報漏洩|不正アクセスの手口と企業・利用者が今すぐやるべき対策 最終更新日:2026年10月31日 2026年10月30日、株式会社良品計画は公式アプリ「MUJIアプリ」への不正アクセスを発表しました。漏洩した可能性のある情報は最大約2,726万件にのぼり、退会済み会員のデータも含まれることが明らかになっています。 「自分のデータは大丈夫なのか」...

Claude Code拡張にSSHバックドア混入 — Cursor Marketplaceを襲ったサプライチェーン攻撃の全貌と対処法

Claude Code拡張にSSHバックドア混入 — Cursor Marketplaceを襲ったサプライチェーン攻撃の全貌と対処法

Claude Code拡張にSSHバックドア混入 — Cursor Marketplaceを襲ったサプライチェーン攻撃の全貌と対処法 「拡張機能を入れただけ」で、第三者が自分のマシンへSSHログインできる状態になる。2026年10月29日、Cursor Marketplaceで配布されたClaude Code for VS Code v2.1.313で実際に起きたことです。まず最初にやるべき1コマ...

AIエージェントの請求が青天井になる前に——Paperclipで実践するエージェント予算・コスト管理

AIエージェントの請求が青天井になる前に——Paperclipで実践するエージェント予算・コスト管理

AIエージェントの請求が青天井になる前に——Paperclipで実践するエージェント予算・コスト管理 AIエージェントを本番投入したチームが次に直面するのは、「月末の請求書」です。タスクを自律的にこなしてくれる便利さの裏側では、トークンが静かに積み上がり続けています。本記事では、AIエージェントのコスト管理に特化したOSSツール「Paperclip」を軸に、予算設計からガバナンス実装まで、実運用で...

コメント

0/2000