第5章 CLAUDE.md・Skills・Hooks ── Claude Code を自分色に育てる

2026/04/26

第5章 CLAUDE.md・Skills・Hooks ── Claude Code を自分色に育てる

Claude Code はインストールした瞬間から使えるが、その真価は「育てた後」に現れる。プロジェクトの文脈を覚えさせ、繰り返しのワークフローを自動化し、絶対に破ってはいけないルールを強制する。これを実現する三つの仕組みが、CLAUDE.md・Skills・Hooks だ。それぞれに明確な役割があり、組み合わせることで Claude Code はチームの開発文化を体現したアシスタントへと変わる。

Section 1: CLAUDE.md ── 永続的なコンテキストの基盤

「新しいチームメンバーへのオンボーディング資料」として設計する

CLAUDE.md はプロジェクトルートに置く特別なマークダウンファイルで、Claude Code がセッションを開始するたびに自動的に読み込まれる。技術的な説明だけすれば「永続コンテキスト」だが、より実践的な比喩は「新しいチームメンバーへのオンボーディングドキュメント」だ。

経験豊富な開発者が初日に入社したとき、何を知りたいか？プロジェクトの全体像、ローカル環境の立ち上げ方、コードレビューで指摘される慣習、やってはいけないこと──これらだ。CLAUDE.md も同じ観点で書く。Claude Code は賢いが、あなたのプロジェクト固有の文脈は知らない。教えてやる必要がある。

`/init` で自動生成してから育てる

白紙から書くのが億劫なら、まず /init コマンドを使う。Claude Code がコードベースを自律的にスキャンし、ディレクトリ構造・依存関係・既存のテスト方針などを読み取って CLAUDE.md の草稿を生成する。これをベースに、チームの暗黙知を加筆していくのが現実的な運用だ。

推奨構成と実践例

以下は TypeScript/React プロジェクト向けの実践的な CLAUDE.md 例だ。長くなりすぎると Claude が重要なルールを見落とすため、500行を超えたら削るというガイドラインを持つチームも多い。

# MyApp CLAUDE.md

## プロジェクト概要
React + TypeScript の SPA。バックエンドは FastAPI（Python）。
認証は AWS Cognito、インフラは Terraform で管理。

## 開発環境
- Node.js 22.x（nvmrc 参照）
- `npm run dev` でフロント起動（port 3000）
- バックエンドは `docker compose up` で起動（port 8000）
- 環境変数は `.env.local` をコピーして使う（`.env.example` 参照）

## コードスタイル
- コンポーネントは関数コンポーネント + hooks のみ（クラスコンポーネント禁止）
- 状態管理は Zustand。Context API は認証状態のみ許可
- CSS は Tailwind のみ。インラインスタイルは原則禁止
- import 順序は ESLint の `import/order` ルールに従う

## テスト方針
- ユニットテストは Vitest + React Testing Library
- コンポーネントテストは `*.test.tsx` としてコンポーネントと同階層に配置
- E2E は Playwright（`/e2e` ディレクトリ）
- テストなしの PR はマージ不可

## 禁止事項
- `any` 型の使用（`unknown` を使うこと）
- `console.log` の本番コードへの混入
- `main` への直接 push（必ず PR を経ること）
- `.env` ファイルのコミット

## よく使うコマンド
- `npm run lint` : ESLint + TypeScript チェック
- `npm run test:watch` : テスト watch モード
- `npm run build` : プロダクションビルド（CI と同等）

書くべきこと・書かないこと

書くべきは「Claude Code が知らなければ間違いを犯すこと」だ。プロジェクト固有のアーキテクチャ決定、チームが長年議論して決めたコーディング規約、ローカル環境のクセ──これらは必ず書く。

書かないほうがいいのは「一般的なベストプラクティス」だ。「変数名はわかりやすく」「関数は小さく保つ」といった内容は Claude Code が既に知っている。冗長な記述はコンテキストを圧迫し、本当に重要なルールの「重み」を希薄にする。

Section 2: Skills ── 再利用可能なワークフローの定義

SDK 不要、マークダウンだけで定義できる

Skills は ~/.claude/skills/ 以下に置くマークダウンファイルだ。プロジェクト固有のものは <プロジェクトルート>/.claude/skills/ に置くこともできる。SDK を書く必要はなく、「このタスクをどう処理してほしいか」を自然言語と構造化されたマークダウンで記述するだけだ。

CLAUDE.md との決定的な違いはロードのタイミングにある。CLAUDE.md はセッション開始時に常時読み込まれるが、Skills は「必要なときだけロードされる」。description フィールドに書いた内容とユーザーのタスクが意味的にマッチしたとき、自動的にアクティベートされる。コンテキストウィンドウを必要以上に消費しないため、多数のスキルを定義しても無駄が生じない。

具体的なスキル例

1. PR 作成ワークフロー（create-pr.md）

---
name: create-pr
description: Pull Request を作成する。コミットメッセージの確認、PR テンプレートの適用、レビュアーの自動アサインを行う。
---

# PR 作成ワークフロー

## 手順
1. `git log main..HEAD --oneline` で変更内容を確認する
2. 変更内容から適切な PR タイトルを生成する（50文字以内、命令形）
3. `.github/PULL_REQUEST_TEMPLATE.md` を読み込み、テンプレートに従って本文を記述する
4. `gh pr create` で PR を作成する
5. CODEOWNERS ファイルを参照してレビュアーを自動アサインする

## PR タイトルの命名規則
- feat: 新機能
- fix: バグ修正
- refactor: リファクタリング
- docs: ドキュメント変更のみ

## 注意事項
- Draft PR にするかユーザーに確認すること
- マイルストーンとラベルも設定すること

2. React コンポーネントリファクタリング（refactor-component.md）

---
name: refactor-component
description: React コンポーネントをリファクタリングする。パフォーマンス最適化、型定義改善、カスタムフックへの抽出を行う。
---

# React コンポーネントリファクタリング

## チェックリスト
- [ ] Props に `interface` で型定義がされているか
- [ ] useEffect の依存配列は正しいか（eslint-plugin-hooks で確認）
- [ ] 再レンダリングの多いコンポーネントに `memo` が適用されているか
- [ ] ロジックは custom hooks に分離されているか（コンポーネントは表示に専念）
- [ ] テストは更新されたか

## リファクタリング後の確認
リファクタリング完了後、必ず以下を実行する：
`npm run lint && npm run test -- --run`

3. デバッグワークフロー（debug-workflow.md）

---
name: debug-workflow
description: バグを調査する。エラーメッセージの解析、再現手順の確認、根本原因の特定、修正方針の提案を行う。
---

# デバッグ手順

1. エラーメッセージとスタックトレースを全文読む（途中で止めない）
2. エラーが最初に発生しているファイルと行番号を特定する
3. 該当コードの直近 git log を確認し、いつから壊れたか調べる
4. 最小限の再現コードを作成する
5. 修正案を提示する前に、根本原因を一文で説明する

## よくある罠
- エラーログを表面だけ見て原因を決めつけない
- 「おそらくこれが原因」で修正を始めない。必ず確認してから手を動かす

Section 3: Hooks ── 絶対に外せないルールを強制する

「LLM に頼むと稀に忘れることを Hooks で強制する」

Claude Code は優秀だが、確率的なシステムだ。1000回に1回、lint チェックをスキップしてコミットしてしまうかもしれない。本番環境向けのコード修正で console.log を消し忘れるかもしれない。この「稀に起きる忘れ」が許容できないとき、Hooks を使う。

Hooks は CLAUDE.md でも Skills でも制御できない領域をカバーする。これらは Claude Code の「お願い」ではなく、シェルコマンドとして機械的に実行される強制ルールだ。CI のローカル版だと思えばいい。

フックイベントの種類

Claude Code は 18 のフックイベントを提供しているが、日常的に使う主要なものは以下だ：

イベント	タイミング
`PreToolUse`	ツール実行前（拒否・変更が可能）
`PostToolUse`	ツール実行後（結果への追加処理）
`Stop`	Claude が応答を完了したとき
`SessionStart`	セッション開始時

具体的な Hooks 設定例

~/.claude/settings.json に以下のように記述する：

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "if echo \"$CLAUDE_TOOL_INPUT\" | grep -q 'git commit'; then npm run lint || exit 1; fi"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "FILE=$(echo \"$CLAUDE_TOOL_INPUT\" | jq -r '.file_path // empty'); if [[ \"$FILE\" == *.ts || \"$FILE\" == *.tsx ]]; then npx prettier --write \"$FILE\"; fi"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "echo \"Session ended: $(date)\" >> ~/.claude/session_log.txt"
          }
        ]
      }
    ]
  }
}

ユースケース詳解

コミット前の lint 強制：PreToolUse で git commit コマンドを検知したとき、npm run lint を実行する。lint が失敗すれば exit code 1 でコミット自体を中断できる。CI で弾かれる前にローカルで防ぐ。

ファイル保存後の自動フォーマット：PostToolUse で Write または Edit ツールの実行後に Prettier を走らせる。Claude Code が生成したコードがそのままリポジトリの書式規約に従うため、「フォーマットしてください」という指示が不要になる。

セッション終了時のサマリー生成：Stop イベントで作業ログを記録する。何を変更したか、残タスクは何かを自動でテキストファイルに出力させ、翌日のコンテキスト復元に使う。

Section 4: CLAUDE.md vs Skills vs Hooks の使い分け

三つの仕組みは相互補完的だが、それぞれの「得意領域」を理解することが重要だ。

	CLAUDE.md	Skills	Hooks
ロードタイミング	常時（セッション開始時）	必要なときだけ	イベント発火時（常時監視）
実行主体	Claude（読んで理解する）	Claude（ガイドに従う）	シェル（機械的に実行）
主な用途	プロジェクト知識・規約	タスク手順の標準化	ルールの強制・副作用処理
失敗時の挙動	Claude が無視する可能性あり	Claude が無視する可能性あり	exit code で強制停止可能

判断フローチャート

flowchart TD
    A[「このルールをどこに書くか？」] --> B{全セッションで常に必要か？}
    B -- Yes --> C{Claude に「理解」してほしいか？}
    B -- No --> D{特定タスクのときだけ必要か？}
    C -- Yes --> E[CLAUDE.md に書く\nプロジェクト文脈・コードスタイル]
    C -- No --> F{イベントに連動して機械的に実行したいか？}
    D -- Yes --> G[Skills に書く\nタスク固有のワークフロー]
    D -- No --> F
    F -- Yes --> H[Hooks に書く\n絶対に破れないルール]
    F -- No --> I[要件を再整理する]

    style E fill:#4A90D9,color:#fff
    style G fill:#27AE60,color:#fff
    style H fill:#E74C3C,color:#fff

組み合わせの実例

現実の開発では、三つを組み合わせて使う。たとえば「コードレビュー依頼から PR マージまで」のフローは以下のようになる：

CLAUDE.md：「このプロジェクトは squash merge を使う」「レビュアーは CODEOWNERS を参照する」という知識
Skills：create-pr.md で PR 作成の具体的な手順を定義
Hooks：PreToolUse で gh pr merge 実行前に必ずテストが通っていることを確認

三つは競合するものではなく、それぞれがカバーする「確実性の層」が違う。CLAUDE.md と Skills は Claude の理解と判断に委ねる層、Hooks は機械的に保証する層だ。重要度が高いルールほど Hooks に書き、そうでないものは CLAUDE.md や Skills に任せる──この考え方がシステム全体を適切に機能させる鍵になる。

次章では、Claude Code を外部サービスと接続する MCP と、複数の Claude インスタンスを協調させる Agent Teams について掘り下げる。

第5章 CLAUDE.md・Skills・Hooks ── Claude Code を自分色に育てる

Section 1: CLAUDE.md ── 永続的なコンテキストの基盤

「新しいチームメンバーへのオンボーディング資料」として設計する

/init で自動生成してから育てる

推奨構成と実践例

書くべきこと・書かないこと

Section 2: Skills ── 再利用可能なワークフローの定義

SDK 不要、マークダウンだけで定義できる

具体的なスキル例

Section 3: Hooks ── 絶対に外せないルールを強制する

「LLM に頼むと稀に忘れることを Hooks で強制する」

フックイベントの種類

具体的な Hooks 設定例

ユースケース詳解

Section 4: CLAUDE.md vs Skills vs Hooks の使い分け

判断フローチャート

組み合わせの実例

`/init` で自動生成してから育てる