Claude Code の CLAUDE.md / rules / skills / commands / hooks を使い分ける

Posted at 2026-11-05

Claude Code には、AI の振る舞いを設定する場所が 5 種類あります。似ているようで読み込まれるタイミングも、継承のされ方も違います。

どれに何を書くかを整理したうえで、実際に動かして確かめた挙動（公式ドキュメントに書かれていない部分）をまとめます。

検証バージョン: Claude Code 2.1.311 / macOS 15.7.3
検証日: 2026-11-02
公式仕様ではなく実測です。 バージョンによって変わる可能性があります

5 つの置き場所と役割

種類	置き場所	読み込まれるタイミング	向いている内容
CLAUDE.md	リポジトリルート、`~/.claude/CLAUDE.md`	常時	プロジェクトの前提、守ってほしいこと全般
rules	`.claude/rules/.md`、`~/.claude/rules/.md`	`paths:` に一致するファイルを触ったとき（`paths:` なしなら常時）	「この種類のファイルを触るときだけ」の規約
skills	`.claude/skills/<name>/SKILL.md`	`description` が今のタスクに合致したとき	手順書。やり方が決まっている作業
commands	`.claude/commands/<name>.md`	ユーザーが `/<name>` と打ったとき	定型タスクの起動口
hooks	`settings.json` に登録したスクリプト	ツール実行の前後、セッション開始時など	機械的な強制。禁止・自動実行

ざっくりした判断軸:

常に意識してほしい → CLAUDE.md
特定のファイルを触るときだけ → rules
「〜をやって」と言われたときの手順 → skills
自分が明示的に呼びたい → commands
守られないと困る（＝お願いでは不十分） → hooks

最後の 1 行が重要で、CLAUDE.md に「本番ブランチに直接コミットしないで」と書いても、確実には守られません。確実に止めたいなら hooks です。

それぞれの最小例

CLAUDE.md

ただの Markdown です。リポジトリルートに置けば、そのリポジトリでの作業中ずっと読み込まれます。

# CLAUDE.md

## このリポジトリについて
TypeScript のモノレポ。パッケージは packages/ 配下。

## 守ること
- テストを通してからコミットする
- 依存を増やすときは理由を PR に書く

~/.claude/CLAUDE.md に置くと全プロジェクトで読まれます。個人の好み（言語、文体、進め方）はこちらが向いています。

rules — パス連動で読み込む

CLAUDE.md との違いは paths: フロントマターで発火条件を絞れることです。

---
paths:
  - "**/src/**/*.tsx"
---

# React コンポーネントの規約

- 色・余白はテーマ経由で参照する。ハードコードしない
- 1 ファイル 1 コンポーネント

これで .tsx を触ったときだけ注入されます。CLAUDE.md に全部書くとコンテキストが膨らむので、領域ごとに切り出すのに便利です。

paths: を書かなければ常時読み込まれます（＝ CLAUDE.md とほぼ同じ挙動）。

skills — 手順書

SKILL.md にフロントマターで name と description を書きます。description がトリガーなので、ここを具体的に書くかどうかで呼ばれる確率が変わります。

---
name: db-migration
description: DB マイグレーションを追加するときに使う。ファイル命名、ロールバックの書き方、
  ローカル検証コマンドを含む。スキーマを調べるだけのときは使わない。
---

# マイグレーション追加

1. `migrations/` に新規ファイルを作る。**既存ファイルは書き換えない**
2. up と down の両方を書く
3. `npm run migrate:check` を通す

「〜のときは使わない」まで書いておくと誤発火が減ります。

commands — スラッシュコマンド

/<ファイル名> で呼べます。$ARGUMENTS に引数が入ります。

---
description: 現在の差分をレビューする
argument-hint: [PR番号。省略時は作業ツリーの差分]
---

レビュー対象: $ARGUMENTS（省略時は現在の差分）

1. `.claude/rules/review.md` を読む
2. 差分を取得して観点ごとに確認する
3. 指摘は `file:line` を添え、[バグ] / [懸念] / [参考] でラベル分けする

指摘がなければ「指摘なし」と書く。無理に指摘を作らない。

hooks — 機械的に止める

settings.json に登録します。PreToolUse でツール実行前に割り込めます。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$HOME\"/.claude/hooks/guard.sh",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

スクリプト側は 標準入力に JSON が渡され、終了コード 2 でブロック（stderr が AI に渡る）します。

#!/usr/bin/env bash
set -u
payload="$(cat)"
tool="$(printf '%s' "$payload" | jq -r '.tool_name // empty')"
case "$tool" in Edit|Write) ;; *) exit 0 ;; esac

path="$(printf '%s' "$payload" | jq -r '.tool_input.file_path // empty')"
case "$path" in
  */generated/*)
    echo "ブロック: generated/ は自動生成物です。生成元を直してください。" >&2
    exit 2 ;;
esac
exit 0

ポイントは ブロック理由を stderr に書くことです。これが AI に渡るので、「なぜダメか」「代わりに何をすべきか」まで書くと、そのまま正しい行動に修正してくれます。

迂回口（ALLOW_X=1 のような環境変数）も用意しておくと、本当に必要なときに詰まりません。

実測して分かったこと

ここからが本題です。ドキュメントだけでは分からず、実際に動かして確かめた挙動です。

1. rules の `paths:` は「cwd からの相対パス」で照合される

絶対パスではありません。3 パターン試しました。

検証用のルール:

---
paths:
  - "ruletest/**"
---
合言葉は KOTOBA2255 である。

cwd	`paths:`	読んだファイル	結果
`work/`	`/ruletest/`	`work/ruletest/a.txt`	発火した
`work/`	`ruletest/**`	`work/ruletest/a.txt`	発火した
`work/ruletest/`	`ruletest/**`	`./a.txt`	発火しない

3 行目が決定的です。絶対パスには /ruletest/ が含まれているのに発火しません。つまりどこで Claude Code を起動したかでルールが効いたり効かなかったりします。

モノレポや Git サブモジュールで「ルートから起動することもあれば、サブディレクトリに降りて起動することもある」なら、両方の形を列挙する必要があります。

paths:
  - "**/packages/ui/**"   # ルートから起動したとき
  - "**/src/theme/**"     # packages/ui の中で起動したとき

後者はプレフィックスを剥がした形ですが、単純に剥がすと **（＝全ファイル）になって全プロジェクトで誤発火することがあります。そのプロジェクト特有のサブパスを選ぶのがコツです。言語のパッケージパス（**/src/main/kotlin/com/example/** など）は識別子として優秀でした。

2. 継承のされ方が種類によって違う

ここが一番ハマりました。

種類	祖先ディレクトリの `.claude/` から継承されるか
`CLAUDE.md`	される
`rules/`	される（`paths:` なしのもので確認）
`skills/` / `agents/` / `commands/`	されない

つまり repo/ の中で起動すると、repo/../.claude/skills/ は読まれませんが repo/../.claude/rules/ は読まれます。

これに気づかず、古いディレクトリに残っていた rules が延々と読み込まれ続けていました。ディレクトリを整理したつもりで中身だけ移したため、旧ファイルと新ファイルが二重に注入されている状態でした。

~/.claude/（ユーザースコープ）に置けば cwd に関係なく全部効きます。起動位置が定まらないなら、ここに集約するのが確実です。

3. `paths:` の無い rules は常時注入される

これ自体は仕様どおりなのですが、副作用があります。

rules/ ディレクトリに README.md や UPSTREAM.md を置いてはいけません。 ルールとして読み込まれます。

実際、ルールの出所を記録した UPSTREAM.md を rules/ に置いていたら、毎回「# このディレクトリの出所」という見出しの指示として注入されていました。メタ情報は rules/ の外に置きましょう。

設定が効いているか確かめる方法

推測せずに測れます。ヘッドレスモード（claude -p）で、注入されている指示の見出しを列挙させるだけです。

cd /path/to/repo
printf 'packages/ui/src/theme/colors.ts を Read ツールで読んでください。
読んだあと、システムコンテキストに「ルール」として注入されている
Markdown 文書の H1 見出しをすべて列挙してください。
~/.claude 配下を自分で Read してはいけません。箇条書きのみ。\n' \
  | claude -p --allowedTools Read

出力例:

- 調査ルール
- レビュールール
- React コンポーネントの規約

ポイント:

ルールはファイルを触って初めて発火するので、プローブ用に 1 ファイル読ませる
--allowedTools Read で絞り、「~/.claude を自分で読むな」と明示する。そうしないと AI が設定ファイルを直接読んで「ある」と答えてしまい、検証になりません
起動ディレクトリを変えて同じプローブを流すと、cwd 依存の挙動がそのまま見えます

ルールの中に推測できない固有の文字列（実測値や合言葉）を入れておくと、それを答えさせるだけで確実に判定できます。

まとめ

やりたいこと	使うもの
常に意識してほしい前提	CLAUDE.md
特定のファイルを触るときだけの規約	rules（`paths:` 付き）
決まった手順を再現したい	skills
自分で呼び出す定型タスク	commands
確実に止めたい・自動実行したい	hooks

実測で得た注意点:

rules の paths: は cwd 相対。起動位置が変わるなら複数パターンを列挙する
rules と CLAUDE.md は祖先ディレクトリから継承されるが、skills / commands は継承されない
paths: 無しの rules は常時注入される。rules/ に README 類を置かない
効いているかどうかは claude -p で測れる。推測しない

特に 2 番は、設定を整理したあとに「古い場所に残ったファイル」が静かに効き続けるので要注意です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up