【Claude Code】settings.json × CLAUDE.md 完全ガイド — 設定ファイルの使い分けと実践テンプレート

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

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

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

この記事では、settings.jsonの設定項目・CLAUDE.mdとの使い分け・hooks/permissionsによる事故防止まで、カスタマイズの全体像を実践パターンで整理します。

そんな時に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化に至るまでの実践パターンを紹介します。

settings.json vs CLAUDE.md 使い分け早見表

まずは結論から。「どっちに書けばいいの？」で迷ったら、この表を見てください。

やりたいこと	settings.json	CLAUDE.md
mainへのpushを禁止	permissions.deny で強制ブロック	---
ファイル保存後に自動lint	hooks.PostToolUse で自動実行	---
危険コマンドの禁止（rm -rf等）	permissions.deny で強制ブロック	---
コーディングスタイル指定	---	ルールとして記述
コミットメッセージ規約	---	ルールとして記述
設計方針・アーキテクチャ	---	原則として記述
テスト実行ルール	hooks で自動化	方針をルールとして記述
環境変数の設定	env で注入	---

判断基準はシンプル: 機械的に強制したいこと → settings.json、柔軟な判断が必要なこと → CLAUDE.md。

この記事で学べること

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

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

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

レイヤー	ファイル	影響範囲
グローバル	~/.claude/CLAUDE.md	全プロジェクト共通
プロジェクト	プロジェクトルート/CLAUDE.md	そのプロジェクトのみ
設定	~/.claude/settings.json	hooks, permissions等

グローバルの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           # 行動ルール（優先度付き）
├── hooks/             # カスタムhookスクリプト
└── 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: 実行前チェック

PreToolUseは「ツールが実行される前に介入する」hookです。たとえば、保護ブランチからの直接pushをブロックするような使い方ができます。

現在の運用では、ブランチ保護はpermissions.denyで網羅的にカバーしているため、PreToolUseは空配列（[]）にしています。denyリストに"Bash(git push --force:*)"や保護ブランチへのpushパターンを列挙することで、hookを使わずとも同等の保護が実現できます。

以前は以下のようなインラインhookでブランチチェックを行っていました。

{
  "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"
          }
        ]
      }
    ]
  }
}

このアプローチでも問題なく動作しますが、permissions.denyと役割が重複するため、現在はdenyリストに一本化しています。hookはより複雑な条件分岐が必要なケース（環境変数によるルール切り替えなど）で活躍します。

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": [
      "Read",
      "Write",
      "Edit",
      "MultiEdit",
      "Bash",
      "Task",
      "Skill",
      "WebSearch",
      "mcp__serena",
      "mcp__*"
    ],
    "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ファイルの役割をRULES.mdのルール優先度システムとSkillsに移行し、独立した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も廃止し、同等の機能はSkillの引数やRULES.mdのTriggers定義で実現しています。当時の設計を参考として残しておきます。

# 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
│   ├── hooks/
│   └── settings.json
├── codex/
└── scripts/
    └── setup-skills.sh

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 ~/.codex/skills
ln -sf $SKILLS_REPO ~/.gemini/antigravity/skills

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

settings.json 設定リファレンス

「settings.jsonで何が設定できるの？」という疑問に答えるリファレンスです。

設定ファイルの種類と優先順位

Claude Codeには3種類の設定ファイルがあります。

ファイル	パス	管理者	用途
user settings	~/.claude/settings.json	ユーザー	個人の全プロジェクト共通設定
project settings	.claude/settings.json	チーム	プロジェクト固有設定（Git管理推奨）
managed settings	~/.claude/managed-settings.json	組織管理者	組織ポリシー（最優先で適用）

優先順位: managed-settings.json > project settings.json > user settings.json

managed-settings.json は組織のセキュリティポリシーを強制するためのファイルです。ここに書いた deny ルールは、他の設定で上書きできません。個人開発なら ~/.claude/settings.json だけで十分ですが、チーム開発では .claude/settings.json をリポジトリに含めて共通ルールを統一するのがおすすめです。

主要な設定項目一覧

{
  // パーミッション設定
  "permissions": {
    "allow": ["Read", "Write", "Edit", "Bash", "mcp__*"],
    "deny": ["Bash(rm -rf:*)", "Bash(sudo:*)"]
  },

  // Hooks設定（PreToolUse / PostToolUse）
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [{ "type": "command", "command": "npm run format:fix" }]
      }
    ]
  },

  // 環境設定
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

permissions の記法パターン

deny / allow で使えるパターン記法をまとめます。

パターン	意味	例
ToolName	ツール全体	"Write"
ToolName(arg:*)	引数のプレフィックスマッチ	"Bash(git push:*)"
ToolName(exact_arg)	引数の完全一致	"Read(./.env)"
mcp__server__*	MCPサーバーの全ツール	"mcp__gh__*"
mcp__server__tool	MCPサーバーの特定ツール	"mcp__gh__merge_pull_request"

よくある質問（FAQ）

Q: settings.json と CLAUDE.md の使い分けは？

settings.json = 強制（プログラムで制御）。permissions と hooks はClaude Codeが必ず従います。 CLAUDE.md = 指示（自然言語）。コーディングスタイルや設計方針など、柔軟な判断が必要なルールに使います。

「mainにpushしない」のように絶対に破ってほしくないルールは settings.json の deny + hooks で。「テストを書いてからコミットして」のように状況に応じた判断が必要なルールは CLAUDE.md で。

Q: managed-settings.json は個人開発でも必要？

個人開発なら不要です。~/.claude/settings.json で十分カバーできます。managed-settings.json は組織のIT管理者が「全社員のClaude Codeにこのポリシーを強制する」ために使うファイルです。

Q: settings.json をシンボリックリンクで管理できる？

できます。dotfilesリポジトリから ln -sf ~/dotfiles/claude-code/settings.json ~/.claude/settings.json でリンクを張れば、複数マシンで同じ設定を再現できます。Nix（home-manager）で自動化する方法は本記事のdotfiles管理セクションを参照してください。

Q: model の設定はどうする？

Claude Codeのモデル設定は settings.json ではなく、CLI実行時のフラグ（--model）または環境変数 ANTHROPIC_MODEL で指定します。settings.json の env フィールドに "ANTHROPIC_MODEL": "claude-sonnet-4-6" と書くことで、デフォルトモデルを変更できます。

settings.json vs CLAUDE.md 使い分けフローチャート

「このルール、settings.jsonに書くべき？CLAUDE.mdに書くべき？」と迷った時のための判断フローです。

ルールを追加したい
│
├─ そのルールは「絶対に破ってほしくない」？
│   │
│   ├─ YES → プログラムで強制できる？
│   │   │
│   │   ├─ YES（コマンド実行のブロック等）
│   │   │   → settings.json の permissions.deny または hooks に追加
│   │   │   例: git push --force のブロック、rm -rf の禁止
│   │   │
│   │   └─ NO（判断が必要なルール）
│   │       → CLAUDE.md に 🔴 CRITICAL ルールとして記載
│   │       例: 「本番DBに直接クエリを実行しない」
│   │
│   └─ NO → 状況に応じた柔軟な対応が必要？
│       │
│       ├─ YES
│       │   → CLAUDE.md に 🟡 IMPORTANT または 🟢 RECOMMENDED で記載
│       │   例: 「テストを書いてからコミット」「命名規則」
│       │
│       └─ NO（自動実行したい定型処理）
│           → settings.json の hooks（PostToolUse）に追加
│           例: ファイル保存後の自動フォーマット

判断基準の要約:

判断軸	settings.json	CLAUDE.md
強制力	プログラムで100%強制	自然言語の指示（遵守率は高いが100%ではない）
適用範囲	コマンド実行・ツール使用の制御	コーディングスタイル・設計方針・ワークフロー
変更頻度	低（設定したらほぼ変えない）	中〜高（プロジェクトに応じて調整）
例	deny, hooks	ルール、原則、Triggers

コピペで使える設定テンプレート

「結局どう書けばいいの？」という方向けに、すぐに使えるテンプレートを用意しました。プロジェクトの要件に応じてカスタマイズしてください。

settings.json テンプレート

個人開発向けの推奨設定です。~/.claude/settings.json に配置します。

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "MultiEdit",
      "Bash",
      "Task",
      "Skill",
      "WebSearch"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Bash(sudo:*)",
      "Bash(git push --force:*)",
      "Bash(curl:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run format:fix 2>/dev/null; exit 0"
          }
        ]
      }
    ]
  },
  "env": {}
}

カスタマイズのポイント:

• deny リストはプロジェクトに応じて追加。"Bash(brew:*)" や "Bash(pip install:*)" など、パッケージの勝手なインストールを防ぐパターンが有効
• PostToolUse の command はプロジェクトのフォーマッターに合わせて変更（prettier --write や ruff format など）
• MCP サーバーを使う場合は allow に "mcp__*" を追加

CLAUDE.md スターターテンプレート

参照分離パターンを使ったテンプレートです。~/.claude/CLAUDE.md（グローバル）またはプロジェクトルートの CLAUDE.md に配置します。

# プロジェクト名

技術スタック・フレームワークの概要を1行で。

## コマンド

npm run dev # 開発サーバー
npm run build # 本番ビルド
npm run lint # Lint
npm run test # テスト

## 重要なルール

1. テストを通してからコミットする
2. main/masterブランチに直接pushしない
3. 既存のコーディングスタイルに従う

## ディレクトリ構成

src/ # ソースコード
tests/ # テスト
docs/ # ドキュメント

## 参照（グローバル CLAUDE.md の場合）

@PRINCIPLES.md # 開発原則
@RULES.md # 行動ルール（優先度付き）

カスタマイズのポイント:

• プロジェクト用 CLAUDE.md にはそのリポジトリ固有の情報（コマンド、ディレクトリ構成、命名規則）を記載
• グローバル CLAUDE.md には個人の開発スタイル（原則、ルール）を記載し、@参照で外部ファイルに分離
• ルールが10個を超えたら RULES.md への分離を検討
• 🔴 CRITICAL / 🟡 IMPORTANT / 🟢 RECOMMENDED の優先度ラベルを活用すると遵守率が向上

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

効いている施策

施策	体感効果	コメント
ルール優先度	⭐⭐⭐	🔴CRITICALは本当に破らなくなった
hooksのブロック	⭐⭐⭐	100%効く。CLAUDE.mdの「お願い」とは別物
PostToolUse自動lint	⭐⭐	地味に便利。フォーマット指示が不要に
MODEの切り替え	⭐⭐	ブレストと実装の境界が明確に（現在はSkillsに移行）
参照分離	⭐⭐	メンテナンスが格段に楽

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

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

まとめ

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

1. CLAUDE.md（参照分離）: 原則・ルールを別ファイルに分離して管理
2. settings.json（hooks/permissions）: プログラムで事故を防止。「お願い」ではなく「強制」
3. Skills（行動の体系化）: MODEファイルの役割を引き継ぎ、状況に応じた振る舞いをSkillとして定義

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

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

あわせて読みたい

• 【Claude Code】Hooksで自動テスト・lint・危険コマンドブロックを仕込む — hooks設定の実践パターン
• 【Claude Code】Hooks安全設計 — PreToolUse/PostToolUseの防御パターン集 — 本番事故を防ぐhooks設計
• 【Claude Code Skills】設計思想と自作ガイド — MODEファイルの後継としてのSkills
• 【Claude Code Skills】SKILL.mdの書き方と設計パターン — Skillsの設計指針
• 【2026年版】AIコーディングツール完全比較 — Claude Code・Codex・Antigravityの選び方

→ 気軽に相談する

---

Claude Code Skills設計 完全ガイド — この記事を含む6本の記事で、Skills設計・オーケストレーション・状態管理を体系的に解説しています。