CLAUDE.md・Rules・Hooks・Skills・Agents — Claude Code の設定ファイル五種

五つはそれぞれ何を担うのか

Claude Code を入れた直後に見えるのは対話欄ひとつだけだ。それでも仕事にはなるが、数日使うと同じことを毎回書き直している自分に気づく。このプロジェクトはこう起動する、あのフォルダは触るな、コミット前にテストを回せ。

その繰り返しを消す仕組みが五つある。名前は似ているが性格はまるで違う。分かれる軸は二つ、いつ読まれるのかと、指示なのか強制なのかだ。

まず全体像から始めよう。下の表がこの記事の要約そのものだ。

my-project/
├── CLAUDE.md                  # 毎セッション最初に読まれる説明書
└── .claude/
    ├── settings.json          # フックを書く場所
    ├── rules/
    │   ├── testing.md
    │   └── api.md             # paths で条件を付けられる
    ├── skills/
    │   └── deploy/SKILL.md    # /deploy で呼ばれる
    └── agents/
        └── code-reviewer.md   # レビューを別ウィンドウでやらせる

CLAUDE.md — セッション開始時に最初に読まれるファイル

名前のとおりファイルひとつだ。プロジェクトのフォルダに CLAUDE.md という名前で置いておくと、Claude Code は起動のたびその中身を先に読んでから対話を始める。

なぜ必要か。言語モデルは前の対話を覚えていない。覚えているように見えるのは、保存しておいた内容を毎回プロンプトと一緒に送っているからで、その保存内容がこのファイルだ。昨日教えたビルドコマンドを今日また教えたくないなら、ここに書く。

何を書くか。書かなければまた説明することになるものを書く。同じ間違いを二度目に見たとき、同じ訂正を前のセッションでも打ったとき、新しいメンバーなら同じことを聞いたはずの内容のときが追加の合図だ。具体的にはプロジェクトが何をするものか、何で作られているか、どのコマンドで実行・テスト・デプロイするか、そして絶対にしてはいけないことだ。

ファイルは四箇所に置け、広い範囲から狭い範囲の順にすべて連結して読まれる。組織へ配る管理ポリシーのファイル、アカウント全体に効く ~/.claude/CLAUDE.md、チームと共有するプロジェクトの CLAUDE.md、そして自分だけの CLAUDE.local.md だ。最後のものは .gitignore に入れてコミットされないようにする。

白紙から書き始めるのが難しければ、ターミナルで /init と打てばよい。Claude がコードベースを走査して、ビルドコマンド・テスト方法・見つけた慣行を含む下書きを作ってくれる。すでにファイルがあれば上書きせず改善案を出す。

ここで初心者が最も多くやる失敗は長さだ。自己紹介のように長く書いてしまうのだが、公式ドキュメントはファイルあたり 200 行未満を勧めている。このファイルは毎セッション丸ごとコンテキストに載るので、長いほどトークンを食い、長いほど守られる確率が下がる。表現も検証できるくらい具体的なほうがよい。コードをきれいに整形しろ、より、インデントは半角二つを使う、のほうが実際に守られる。

そして必ず知っておくべき事実がひとつある。CLAUDE.md は設定ではなく文脈だ。システムプロンプトの一部ではなくユーザーメッセージとして届くので、Claude は読んで参考にするだけで、必ず守る保証はない。無条件で止めたいものがあるなら、それは後で出てくるフックの役目だ。

ファイルが実際に読まれたか確かめるには、セッションで /context と打ってメモリファイルの一覧を見る。開いて直すなら /memory だ。

他のツール向けに AGENTS.md をすでに使っているなら、Claude Code はそのファイルを読まない。CLAUDE.md を作って一行目に @AGENTS.md と書いて取り込めば、一本で管理できる。

# my-shop

## プロジェクト
Next.js 15 と Supabase で作ったオンライン注文ページ。

## コマンド
- 開発サーバー: `npm run dev`
- テスト: `npm test`
- デプロイ: `vercel deploy --prod`

## ルール
- 金額計算は `src/lib/price.ts` の一箇所だけで行う。
- コミット前に必ず `npm test` を実行する。
- `.env` ファイルは絶対に開かないしコミットもしない。

Rules — CLAUDE.md が長くなったらここへ分ける

200 行未満に保てという話は、そのままあふれた分をどこへ送るかという問題になる。その場所が .claude/rules/ だ。

作り方は単純だ。プロジェクトに .claude/rules/ フォルダを作り、その中へ主題ごとに markdown ファイルを入れる。testing.md、api-design.md、security.md のように、ファイル名だけで何のルールか分かるようにしておく。サブフォルダに分けても全部見つけて読む。

ここまでなら CLAUDE.md を複数ファイルに割っただけと変わらない。本当の違いは次の機能で出る。

ファイルの先頭に paths を書くと条件付きになる。下の例のようにグロブパターンを書いておくと、Claude がそのパターンに合うファイルを実際に開いたときだけ、そのルールがコンテキストに載る。フロントエンドを直している間、API ルール三十行が場所を取らないということだ。

paths のないルールファイルは条件なしでセッション開始時に全部読まれる。優先度は .claude/CLAUDE.md と同じだ。

パターンはよくあるグロブ構文だ。**/*.ts はすべての TypeScript ファイル、src/**/* は src 配下すべて、*.md はルートの markdown、src/components/*.tsx はそのフォルダの React コンポーネントだけを指す。src/**/*.{ts,tsx} のように波括弧で拡張子をまとめることもできる。

プロジェクトではなく自分に付くルールもある。~/.claude/rules/ に置けば、この機械のすべてのプロジェクトに効く。読む順は個人ルールが先、プロジェクトルールが後なので、プロジェクト側のほうが強い位置を持つ。

区別はひとつ覚えれば足りる。ルールは常時、または該当ファイルを触ったときに自動でコンテキストへ載る。一方、次に出てくるスキルは呼んだときだけ載る。常に守るべき一文ならルール、特定の作業のときだけ要る手順ならスキルだ。

---
paths:
  - "src/api/**/*.ts"
---

# API 実装ルール

- すべてのエンドポイントは入力値を検証する。
- エラー応答は決められた形式ひとつだけを使う。
- 新しいエンドポイントには OpenAPI コメントを付ける。

Hooks — 守ってくれと頼む代わりにコードで止める

前の二つはどちらも指示だった。Claude は読んで参考にするが、守らないこともある。必ず守られなければならないものがあるなら性格の違う装置が要る。それがフックだ。

フックは決めた出来事が起きるたび自動で実行されるシェルコマンドだ。Claude が判断して実行するのではなく、条件が合えば無条件で走る。だからこれだけが強制なのだ。

書く場所は .claude/settings.json だ。構造は三層。どの出来事に掛けるか、その出来事の中で何にだけ掛けるか、そして実行するコマンドは何かだ。

出来事の名前は多いが、最初は五つ知っていれば十分だ。SessionStart はセッションが始まるとき、UserPromptSubmit は自分がプロンプトを送るとき、PreToolUse はツールが実行される直前、PostToolUse は実行された直後、Stop は Claude が回答を終えるときだ。

matcher はその出来事の中で対象を絞る値だ。ツール系の出来事ではツール名で絞る。Bash と書けば Bash ツールだけ、Edit|Write のように縦棒で並べれば両方に掛かる。空にするか * を書けば全部に掛かる。

実行されたコマンドは標準入力で JSON を受け取る。どの出来事か、どのツールか、そのツールにどんな引数が入ったかが入っている。下の例がその値を読んで強制プッシュを止めるフックだ。

肝心なのは終了コードだ。この値がフックの判断そのものになる。0 で終われば通過、2 で終わればそのツール呼び出しが取り消され、stderr に書いた文が Claude へ理由として渡される。それ以外の値はエラーとして記録されるが作業はそのまま進む。

実際に何に使うか。ファイルを直した後に自動でフォーマッタを回す、特定フォルダの変更を止める、作業が終わったら通知を送る、といった用途が多い。CLAUDE.md に「コミット前にテストを回せ」と書いたのに何度も飛ばされるなら、その一文はフックへ降ろすべき一文だ。

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/no-force-push.sh"
          }
        ]
      }
    ]
  }
}

#!/bin/bash
# フックは標準入力で JSON を受け取る。tool_input.command に実行されるコマンドが入っている。
cmd=$(jq -r '.tool_input.command // ""')

if [[ "$cmd" == *"push --force"* || "$cmd" == *"push -f"* ]]; then
  # 終了コード 2 は遮断。stderr に書いた文がクロードへ理由として渡される。
  echo "このリポジトリでは強制プッシュは禁止です。--force-with-lease を使ってください。" >&2
  exit 2
fi

exit 0

Skills — 繰り返す手順をスラッシュコマンドに

チャット欄に同じ指示のかたまりを繰り返し貼っているなら、あるいは CLAUDE.md の一節が事実ではなく手順に育っているなら、それがスキルへ移す合図だ。

作り方はフォルダひとつとファイルひとつ。.claude/skills/ の下に名前でフォルダを作り、その中に SKILL.md を置く。そのフォルダ名がそのままコマンドになり、/名前 で呼ばれる。

SKILL.md は二部構成だ。三本線ではさむ frontmatter と、その下の本文。frontmatter の項目はすべて任意だが、description は事実上必須だ。Claude がこの説明を読んでいつこのスキルを使うか判断するからで、何をするのかといつ使うのかを併せて書く。

本文には Claude が従う指示をそのまま書く。ここでスキルの本当の利点が出る。本文はスキルが実際に使われるときだけ読まれるので、長く書いても普段のコンテキストをまったく食わない。CLAUDE.md に長い手順を入れると毎セッション費用がかかるが、スキルはゼロだ。

呼び方は二つ。直接 /名前 と打つか、description に合う依頼をして Claude に読み込ませるかだ。自動呼び出しを避けて手動だけにしたいなら、frontmatter に disable-model-invocation を true と書く。

本文で感嘆符とバッククォートでコマンドを囲むと、その場所に実行結果があらかじめ埋まった状態で渡る。下の例の git diff がそれだ。Claude がスキルを読む時点ですでに変更内容が入っている。

置く場所は三箇所。~/.claude/skills/ は自分のすべてのプロジェクトで、プロジェクトの .claude/skills/ はそのプロジェクトだけで、プラグイン内の skills/ はそのプラグインが有効な場所で使われる。なお以前の .claude/commands/ はスキルへ統合された。既存のファイルはそのまま動く。

ファイルを直せばセッションを開き直さなくてもすぐ反映される。

---
description: 変更内容を要約し、危なそうな箇所を指摘する。何が変わったか尋ねられたときやコミットメッセージが必要なときに使う。
---

## 現在の変更

!`git diff HEAD`

## 指示

上の変更を二、三行で要約し、抜けている例外処理・ハードコードされた値・
一緒に直すべきテストがあれば一覧にする。変更が空なら、そう答えるだけでよい。

Agents — 別の作業を別のウィンドウでやらせる

前の四つが Claude に何をどうしろと伝える装置だったのに対し、最後のひとつは誰がやるかを分ける装置だ。

サブエージェントは自分だけのコンテキストウィンドウを持つ補助の Claude だ。仕事を渡すとそちらのウィンドウで独りで進め、結果の要約だけを返す。コードベースを漁って出た大量の検索結果やファイル内容が自分の対話欄に積もらないということだ。コンテキストウィンドウが埋まるほど回答が悪くなることを思えば、これがなぜ道具なのか分かる。

作り方は markdown ファイルひとつ。.claude/agents/ の下にファイルを置き、frontmatter に四つ書く。name は小文字とハイフンからなる一意の名前、description はいつこのエージェントへ渡すか、tools は使える道具の一覧、model はどのモデルで回すかだ。

name と description は必須で、残りは省ける。tools を空にするとサブエージェントが使える道具をすべて引き継ぐ。読み取り専用にしたいなら Read, Grep, Glob 程度だけ書けばファイルを直せなくなる。model を haiku にすれば安いモデルで回って費用が減り、省けば本対話のモデルを引き継ぐ。

場所は二箇所。~/.claude/agents/ は自分のすべてのプロジェクトで使われ、プロジェクトの .claude/agents/ はそのリポジトリだけで使われる。後者はコミットしておけばチームで共に使い、共に直せる。

自分で作らなくても最初から入っているものがある。Explore はコードベースを漁る読み取り専用のエージェント、Plan はプランモードで調査を担い、General-purpose は探索と修正の両方が要る複合作業を担う。Claude は各エージェントの description を見て渡すかどうかを決めるので、自分で作るときはその説明をいつ使えという文として書くことが大事だ。

新しく作ったのに見えなければセッションを開き直す。agents フォルダ自体がセッション開始時になかった場合にだけ起きることだ。

---
name: code-improver
description: ファイルを走査し、可読性・性能・慣行の観点で改善点を提案する。コードを書いたり直したりした後に使う。
tools: Read, Grep, Glob
model: sonnet
---

あなたはコード改善の専門家だ。見つけた問題ごとに何が問題かを説明し、
現在のコードを示したうえで、直したコードを提示する。

五つのうちどれを選ぶか

名前と形式を全部知っても、実際に詰まるのはここだ。いま手にしているこの一文をどこへ入れるのか。

問いは三つで分かれる。第一に、常に知っておくべき事実なのか、特定の作業の手順なのか。事実なら CLAUDE.md、手順ならスキルだ。第二に、特定のファイルを触るときだけ要るのか。ならば paths を付けたルールだ。第三に、破ってもよい推奨なのか、必ず止めるべきものなのか。後者ならフックだ。

そして四つ目がもうひとつある。この作業が終わったら、その過程のログをまた見ることがあるか。ないならエージェントへ渡して自分の対話欄をきれいに保つ。

よくある失敗も対称に現れる。手順を CLAUDE.md に入れてファイルが 300 行に膨らみ、結局何も守られなくなる場合がひとつ。必ず止めるべきものを CLAUDE.md の一文として書いておいて、守られないともどかしがる場合がもうひとつ。前者はスキルへ、後者はフックへ移せば解ける。

いますぐやること

五つを一度に作る必要はない。順番があり、前のものがあふれたとき次へ移る構造だ。

まず作業中のプロジェクトで /init と打つ。Claude がコードベースを走査して CLAUDE.md の下書きを作ってくれる。出てきた下書きを開いてコマンドが合っているか確かめ、Claude には知りようのないルールを数行、手で足す。初日はここまででよい。

その後は反応型だ。ファイルが 200 行に近づいたら主題ごとに .claude/rules/ へ分け、特定フォルダでだけ通じるものには paths を付ける。同じ指示のかたまりを三度目に貼っていたら .claude/skills/ へ移す。書いておいたのに守られ続けない一文があれば、それはフックへ降ろす一文だ。調査で対話欄がログに埋まったらエージェントを作る。

確認は /context で行う。いまのセッションにどのファイルが実際に載っているか、コンテキストが何パーセント埋まっているかが一画面に出る。書いておいたのに一覧にないなら、内容の問題ではなく場所の問題だ。