【Claude Code カスタマイズ】settings.jsonとCLAUDE.mdで自分専用AI開発環境を作る方法

「Claude Code、賢いんだけど...毎回同じこと言い直すの、ちょっとしんどくない？」

「テスト通してからコミットして」「mainには直接pushしないで」「ファイル読んでから編集して」。 プロジェクトのお作法を何度伝えても、新しい会話が始まればゼロからやり直し。AIって記憶力いいはずなのに、セッションまたぐと全部忘れてくれます（人間の上司かな？）。

Claude CodeにはCLAUDE.mdという仕組みがあって、ここにプロジェクトのルールを書いておけば毎回読み込んでくれる。公式ドキュメントにもサラッと載っています。でも、「何をどこまで書けばいいのか」は、あまり語られていません。

自分好みにClaude Codeをカスタマイズしたい、でもどう設計すればいいか分からない...心当たりありませんか？

そんな時にGitHubで盛り上がっていたのがSuperClaude Framework。CLAUDE.mdの書き方からMODEの切り替えまで体系化されたOSSで、「これだ」と思って導入しました。正直、最初は「ここまでやる必要ある？」と半信半疑だったんですが、使い始めたらClaude Codeの挙動が明らかに変わった。mainへのpushは止まるし、ブレスト中にコード書き始めなくなるし。

その後、Claude CodeにSkills機能が追加されたタイミングで、SuperClaudeの中でも特に効いていた仕組みをSkill化。「開発効率と精度を上げてくれる部分はSkillに、ルールと原則はCLAUDE.mdに」という整理をして、今のdotfiles構成に落ち着きました。Skill化の際に直面したSKILL.mdの肥大化問題とその解決策については、別の記事で詳しく紹介しています。

今回は、SuperClaudeの導入からSkill化に至るまでの実践パターンを紹介します。

この記事で学べること

• CLAUDE.mdの設計パターン（参照分離・ルール優先度システム）
• settings.jsonのhooksで「うっかり事故」を自動で防ぐ方法
• MODEファイルで状況に応じたAIの振る舞いを切り替える手法
• dotfilesに含めて環境再現性を確保する構成

前提：Claude Codeの設定ファイル構造

Claude Codeのカスタマイズは、主に3つのレイヤーで行います。

グローバルのCLAUDE.mdは「自分の開発スタイル」、プロジェクトのCLAUDE.mdは「そのリポジトリのお作法」。この2段構えがカスタマイズの出発点です。

CLAUDE.mdの設計パターン：参照分離

「CLAUDE.mdに全部書く」のは最初のうちだけ。ルールが増えてくると1ファイルが肥大化して、メンテナンスが地獄になります（1000行超えたCLAUDE.mdを見た時の絶望感、想像してください）。

SuperClaudeが採用しているのが参照分離パターンです。

# CLAUDE.md（エントリポイント）

# SuperClaude Framework

Enhanced Claude Code framework with skill-based behavioral modes.

## Core Principles

@PRINCIPLES.md

## Behavioral Rules

@RULES.md

## MCP Server Reference

Use `/mcp-guide` skill for MCP server selection guidance.

@PRINCIPLES.mdという記法で外部ファイルを参照します。CLAUDE.md自体はたったの数行。エントリポイントとして「何がどこにあるか」を示すだけの役割に徹しています。

実際のディレクトリ構成

~/.claude/
├── CLAUDE.md          # エントリポイント（参照のみ）
├── PRINCIPLES.md      # ソフトウェア工学の原則
├── RULES.md           # 行動ルール（優先度付き）
├── FLAGS.md           # フラグシステム定義
├── MODE_Brainstorming.md
├── MODE_Introspection.md
├── MODE_Orchestration.md
├── MODE_Task_Management.md
├── MODE_Token_Efficiency.md
└── settings.json      # hooks, permissions

なぜ分離するのか？ 最初は「全部1ファイルでいいじゃん」と思ってました。実際やってみると、ルールを1行直したいだけなのに800行のCLAUDE.mdをスクロールする羽目になって、「これ、設定ファイルのリファクタリングが必要な設定ファイルって何なんだ」と。

分離してからは快適です。

1. 関心の分離: 原則・ルール・モードは別の関心事。変更理由が違うファイルは分ける（SOLID原則のSそのもの。AIの設定にSOLID適用してる時点で病気かもしれない）
2. 部分更新が楽: ルールだけ修正したい時にRULES.mdだけ触ればいい
3. チーム共有しやすい: 「PRINCIPLES.mdだけチームで共有」「RULES.mdは個人カスタマイズ」という運用ができる

ルール優先度システム：全部同じ重みにしない

RULES.mdで特に気に入っているのが優先度システムです。

ルールを山ほど書いても、Claude Codeは全部を同じ重みで解釈しがちです。「テスト書いて」と「本番DB触らないで」が同じ優先度だと困りますよね（後者は人が死ぬやつ）。

## Rule Priority System

**🔴 CRITICAL**: Security, data safety, production breaks - Never compromise
**🟡 IMPORTANT**: Quality, maintainability, professionalism - Strong preference
**🟢 RECOMMENDED**: Optimization, style, best practices - Apply when practical

### Conflict Resolution Hierarchy

1. Safety First: Security/data rules always win
2. Scope > Features: Build only what's asked
3. Quality > Speed: Except in genuine emergencies
4. Context Matters: Prototype vs Production requirements differ

各ルールに🔴 CRITICALや🟡 IMPORTANTのラベルを付けて、さらに「ルール同士が矛盾した時の解決順序」まで定義しています。

実際のルール例

## Git Workflow

**Priority**: 🔴 **Triggers**: Session start, before changes, risky operations

- Always Check Status First: Start every session with `git status` and `git branch`
- Feature Branches Only: Create feature branches for ALL work
- Verify Before Commit: Always `git diff` to review changes before staging

✅ Right: `git checkout -b feature/auth` → work → commit → PR
❌ Wrong: Work directly on main/master branch

ポイントは**Triggers（発動条件）**を明記していること。これがないと、コードレビューの最中に突然「セッション開始時にはgit statusを実行します！」とか言い出す。いや、今それじゃないんだわ。

✅ Right / ❌ Wrongの具体例も地味に効きます。「feature branchで作業してね」だけだと3回に1回は無視されてたのが、悪い例を見せたらほぼ守るようになった。AIも人間と同じで、ダメなパターンを具体的に見せられると「あ、これやっちゃいけないんだ」と理解するらしい。

settings.json：hooksで「うっかり事故」を自動ブロック

CLAUDE.mdは「お願い」ですが、settings.jsonのhooksは「強制」です。AIが「うっかり」やらかす前に、プログラムで止めます。hooksを活用した品質管理の詳細はHooks × Skillsで品質ゲートを自動化するで掘り下げています。

PreToolUse: 実行前チェック

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git push:*)",
        "hooks": [
          {
            "type": "command",
            "command": "BR=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo \"\"); case \"$BR\" in dev|develop|main|master) echo '⛔ Blocked: pushing from protected branch' 1>&2; exit 2;; esac; exit 0"
          }
        ]
      }
    ]
  }
}

これは「保護ブランチからの直接pushを物理的にブロックする」hookです。Claude Codeがgit pushを実行しようとした瞬間に、現在のブランチをチェックして、mainやdevだったらexit 2で中断します。

CLAUDE.mdに「mainにpushしないで」と書いても、長い会話の途中でトークン圧縮が走ると記憶が薄れて無視されることがあります。hookなら100%止まる。「お願いだから守って」と「物理的に不可能」の差、身に染みて分かりました。

PostToolUse: 実行後の自動処理

{
  "PostToolUse": [
    {
      "matcher": "Write|Edit|implement",
      "hooks": [
        {
          "type": "command",
          "command": "npm run format:fix && npm run lint:fix"
        }
      ]
    }
  ]
}

ファイルを書き込んだ後に自動でフォーマットとlint修正を走らせます。「フォーマットして」と毎回お願いしなくて済むのは地味にデカい。1日に何十回もEdit走るので、その度にフォーマット指示のトークンが浮く。塵も積もれば、API請求書を見る時の胃痛が少し軽くなるくらいの効果はあります。

permissions: 許可・拒否リストで事故を構造的に防止

{
  "permissions": {
    "allow": [
      "Write",
      "Edit",
      "Bash",
      "mcp__serena__*",
      "mcp__morphllm-fast-apply__*"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(curl:*)",
      "Bash(brew:*)"
    ]
  }
}

denyリストがなかなか長くなりますが、ここは手を抜かないほうがいい。rm -rf /を一発叩かれたら取り返しがつかないので（AIがそこまでやるとは思わないけど、保険は大事）。

実際の運用ではcurlやbrewもブロックしています。「ちょっとこのライブラリ入れますね」とAIが勝手にパッケージをインストールし始めるのを防ぐためです。依存関係は人間が判断するもの。

MODEファイル：状況に応じた振る舞いの切り替え

Claude Codeに「いつも同じテンション」で対応されると、ちょっと困ることがあります。「この機能どう思う？」って相談したいだけなのに、3秒後にはファイル作り始めてる。逆に、設計が固まって「もう黙ってコード書いて」って時に限って「この実装方針でよろしいですか？」と聞いてくる。お前のタイミング感覚どうなってるんだ。

SuperClaudeにはこの課題に対応するMODEファイルという仕組みがあります。

MODE_Brainstorming.md    # 協調的な探索モード
MODE_Introspection.md    # メタ認知・自己分析モード
MODE_Orchestration.md    # ツール最適化モード
MODE_Task_Management.md  # タスク管理モード
MODE_Token_Efficiency.md # トークン節約モード

Brainstorming Mode

# Brainstorming Mode

**Purpose**: Collaborative discovery for interactive requirements exploration

## Activation Triggers

- Vague project requests: "I want to build something..."
- Exploration keywords: brainstorm, explore, discuss, not sure
- Manual flags: `--brainstorm`, `--bs`

## Behavioral Changes

- Socratic Dialogue: Ask probing questions to uncover hidden requirements
- Non-Presumptive: Avoid assumptions, let user guide discovery
- Collaborative Exploration: Partner in discovery rather than directive

「まだ何を作るか固まってない」というフェーズで、Claude Codeが勝手にコードを書き始めないようにするモードです。質問を投げかけて、一緒に要件を掘り下げてくれる。導入前は「ちょっと考えたいだけなのに...」と思いながら生成されたコードをCtrl+Zする日々だったので、これは精神衛生上かなり助かりました。

Orchestration Mode

# Orchestration Mode

**Purpose**: Intelligent tool selection for optimal task routing

## Tool Selection Matrix

| Task Type     | Best Tool      | Alternative      |
| ------------- | -------------- | ---------------- |
| UI components | Magic MCP      | Manual coding    |
| Deep analysis | Sequential MCP | Native reasoning |
| Pattern edits | Morphllm MCP   | Individual edits |
| Symbol ops    | Serena MCP     | Manual search    |

MCP（Model Context Protocol）サーバーが複数ある環境で、「どのツールを使うのが最適か」を判断するモードです。Resource ManagementのZone設計（Green/Yellow/Red）でトークン消費量に応じた行動制御もできます。このように複数のSkillやツールを統括する設計は、Skillオーケストレーションの考え方にも通じています。

Token Efficiency Mode

長い会話でコンテキストが圧迫されてきた時に切り替えるモードです。シンボルと略語を使って30-50%のトークン削減を狙います。ちなみにこの30-50%、「大した差じゃないでしょ」と思うかもしれませんが、コンテキストウィンドウの終盤でこの余裕があるかないかで、会話を続行できるかリセットされるかが変わります。リセット = それまでの文脈が全部消える。つらい。

## Symbol Systems

| Symbol | Meaning   | Example                         |
| ------ | --------- | ------------------------------- |
| →      | leads to  | `auth.js:45 → 🛡️ security risk` |
| ✅     | completed | Task finished successfully      |
| ∵      | because   | `slow ∵ O(n²) algorithm`        |
| »      | sequence  | `build » test » deploy`         |

最初は「記号だらけで読みにくくないか」と思いましたが、慣れると情報密度が高くて快適です。build → test → deployの流れがbuild » test » deployで伝わるなら、それでいい。人間が読むわけじゃないし（自分でたまに読み返すと暗号文に見えるのは内緒）。

FLAGSでモードを柔軟に発動させる

MODEファイルを直接指定する以外に、フラグシステムで柔軟に発動させる仕組みもあります。

# FLAGS.md（抜粋）

## Mode Activation Flags

--brainstorm # Brainstormingモード起動
--introspect # Introspectionモード起動
--orchestrate # Orchestrationモード起動
--task-manage # Task Managementモード起動

## Analysis Depth Flags

--think # 標準分析（~4Kトークン）
--think-hard # 深い分析（~10Kトークン）
--ultrathink # 最大深度分析（~32Kトークン）

## MCP Server Flags

--serena # Serena MCP有効化
--morph # Morphllm MCP有効化
--c7 # Context7 MCP有効化
--all-mcp # 全MCP有効化

--think-hardで分析の深さを指定したり、--serenaで特定のMCPサーバーを有効化したり。組み合わせて使えるので、タスクの複雑さに応じて段階的にリソースを投入できます。

フラグ同士が矛盾した時の優先順位も定義してあります。

## Flag Priority Rules

Safety First: --safe-mode > --validate > optimization flags
Depth Hierarchy: --ultrathink > --think-hard > --think
MCP Control: --no-mcp overrides all individual MCP flags

安全系のフラグが常に最優先。深夜テンションで--ultrathink --no-mcpとか入力しても、安全チェックだけは絶対にスキップされない。深夜の自分を信用しない仕組み、大事です。

dotfilesに含めて環境ごと管理する

ここまで育ててきたClaude Codeの設定、せっかくなのでdotfilesリポジトリに含めて管理しています。

dotfiles/
├── claude-code/
│   ├── CLAUDE.md
│   ├── PRINCIPLES.md
│   ├── RULES.md
│   ├── FLAGS.md
│   ├── MODE_Brainstorming.md
│   ├── MODE_Introspection.md
│   ├── MODE_Orchestration.md
│   ├── MODE_Task_Management.md
│   ├── MODE_Token_Efficiency.md
│   └── settings.json
└── ...

Nixで管理しているので、新しいマシンでもnix run .#update一発でClaude Codeの設定が再現されます。「前のMacではうまくいったのに...」が発生しない。以前MacBook買い替えた時に丸1日かけて環境構築した記憶があるので、あの苦行が二度と発生しないだけで元が取れてます。

Claude CodeにSkills機能が追加されてからは、SuperClaudeの中で「これはSkillにしたほうが再利用しやすい」と感じた仕組み――ブログ公開フロー、SNS告知、コード分析あたり――を順次Skill化しました。開発効率と精度を上げてくれる部分をSkillに切り出して、CLAUDE.mdは本当にルールと原則だけに絞る。今のclaude-code/ディレクトリ構成はその結果です。Skillの設計思想や自作方法はSkillsの設計思想と自作ガイドで体系的にまとめています。

Skillsは別リポジトリに切り出して、シンボリックリンクで複数のAIエージェント間で共有する構成にしています。

# setup-skills.sh（抜粋）
# 複数ツールでSkillsを共有
ln -sf $SKILLS_REPO ~/.claude/skills
ln -sf $SKILLS_REPO ~/.clawdbot/skills
ln -sf $SKILLS_REPO ~/.codex/skills
ln -sf $SKILLS_REPO ~/.gemini/antigravity/skills

Claude Code、OpenClaw（Clawdbot）、Codex、Antigravity...気がついたらAIエージェントが4つも住みついていて、それぞれにSkillsをコピーして回るのはさすがに無理。一箇所で管理してシンボリックリンクで配る方式にしました。AIツールのためにAI以前の技術（シンボリックリンク）を使ってるのは、なんとも言えない味わいがあります。

運用してみて分かったこと

効いている施策

まだ改善の余地がある部分

• MODEの自動切り替え: 今は手動でフラグを付ける必要がある。文脈から自動判定できたらもっと楽
• ルールの遵守率: Token Efficiencyモード時に一部のルールが薄れる傾向がある。トークン圧縮と遵守率のトレードオフは未解決。長い会話でのコンテキスト消失問題についてはauto-compact対策と状態管理の設計パターンでも詳しく扱っています
• settings.jsonのdenyリスト: 書けば書くほど安全になるけど、メンテナンスコストも増える。パターンマッチの粒度設計が難しい

まとめ

Claude Codeのカスタマイズは、「CLAUDE.mdにルールを書く」だけだと思われがちですが、実際は3層の仕組みを組み合わせることで、かなり実用的な開発環境になります。

1. CLAUDE.md（参照分離）: 原則・ルール・モードを別ファイルに分離して管理
2. settings.json（hooks/permissions）: プログラムで事故を防止。「お願い」ではなく「強制」
3. MODEファイル（行動モード切り替え）: 状況に応じたAIの振る舞いを定義

全部dotfilesに入れてNixで管理すれば、新しいマシンでも同じAI開発環境が再現できます。

SuperClaudeをGitHubで見つけて導入し、使いながら自分たちの運用に合わせてカスタマイズし、Skills機能が来たタイミングでSkill化。振り返ると結構な道のりですが、AIとの共同作業が日常になった今、「AIの動き方を設計する」のは「IDEの設定をカスタマイズする」のと同じ感覚なんですよね。vimrcを3日かけて調整するのと、やってることは変わりません（沼の深さも）。

→ お問い合わせはこちら