対象読者： ソフトウェアエンジニア、開発者、およびプロジェクトでのClaude Code活用に関心がある方。

要約： CLAUDE.mdに、プロジェクトのあらゆる指示を詰め込むべきではありません。CLAUDE.mdは、Claudeがプロジェクト全体で継続的に参照するコンテキストやルールに適しています。Skillsは、特定のタスクを実行するときだけ必要となるチェックリストや手順に適しています。CLAUDE.md・Skillsを正しく使い分けることで、指示を分かりやすく整理・保守でき、コンテキストの肥大化や不要なトークン消費を抑え、Claudeがタスクに関連する指示に集中しやすくなります。

まずは、次の原則で考えると分かりやすいでしょう。

プロジェクト全体のRule → CLAUDE.md
Procedure → Skill

Claude Codeを使い始めたばかりの頃、Claudeにプロジェクトを理解させる最も簡単な方法の一つは、次のファイルを作成することです。

CLAUDE.md

例えば：

# Project Rules
Use TypeScript
Use pnpm instead of npm
Follow existing naming conventions
Database access must go through the repository layer
Run tests after changing business logic

最初のうちは、この方法でも十分に機能します。

しかし、チームが次のような内容を追加し続けると、次第に問題が出てきます。

• コーディング規約
• Pull Requestのレビュー手順
• APIチェックリスト
• バグ分析手順
• セキュリティレビュー
• Unit Test作成手順
• Release Note作成手順
• Migrationチェックリスト

数十行だったCLAUDE.mdが、いつの間にか数百行のファイルになってしまうことがあります。

この段階で考えるべきなのは、

「Claudeに十分な指示を与えたか？」

ではなく、

「Claudeは本当にこの指示をすべてのタスクで必要としているのか？」

という問いです。

ここが、CLAUDE.mdとSkillsを使い分ける重要なポイントです。

1. CLAUDE.MDはプロジェクト全体に共通するコンテキストとルールに使う

CLAUDE.mdは、Claudeがプロジェクトで作業する際に継続して参照する必要がある情報やルールを記述する場所です。プロジェクトレベルのCLAUDE.mdはセッション開始時に読み込まれるため、プロジェクト全体に共通する情報を置くのに適しています。

例えば：

# Project

Backend service for Order Management System

## Stack

Node.js
TypeScript
PostgreSQL
pnpm

## Architecture

Controller
→ Service
→ Repository
→ Database
Controllers must not access repositories directly

## Development Rules

Use pnpm
Follow existing naming conventions
Do not change public API contracts without confirmation
Update tests when changing business logic

Claudeが次のような作業をしている場合でも、

• バグ修正
• リファクタリング
• API実装
• テスト作成

上記の情報は引き続き関係する可能性があります。

このような内容がCLAUDE.mdに適しています。

2. SKILLSは特定のタスクを実行するための手順に使う

例えば、チームにPull Requestのレビュー手順があるとします。

1 要件を確認する
2 変更されたファイルを確認する
3 ビジネスロジックを確認する
4 エラーハンドリングを確認する
5 セキュリティ上の問題を確認する
6 テストカバレッジを確認する
7 受け入れ条件と照合する
8 指摘事項を重要度ごとに分類する
9 レビューレポートを作成する

この手順は、次のタスクでは必要です。

Review Pull Request

しかし、

Fix typo in README

や、

Explain this function

では必要ありません。

レビュー手順全体をCLAUDE.mdに入れる代わりに、次のようなSkillを作成できます。

.claude/
 └── skills/
      └── review-pr/
           └── SKILL.md

例えば：

---
name: review-pr
description: Review a Pull Request for correctness, risks and test coverage
---

When reviewing a Pull Request:

1 Read the requirement
2 Inspect changed files
3 Check business logic
4 Check error handling
5 Check security risks
6 Evaluate test coverage
7 Compare with acceptance criteria

Output:

## Critical
## Major
## Minor
## Suggestions
## Final Recommendation

Claude Codeは、タスクに適している場合にSkillを利用でき、ユーザーが/skill-nameで直接呼び出すこともできます。さらに重要なのは、Skillの本文は常にコンテキストを占有する基本指示とは異なり、そのSkillを使用するときだけ読み込まれるという点です。

これが両者の本質的な違いです。

CLAUDE.md
↓
Claudeがプロジェクト内で常に知っておくべきこと

Skill
↓
特定のタスクが発生したときに、Claudeがその実行方法を知るためのもの

3. なぜすべてをCLAUDE.MDに入れるべきではないのか？

よくあるパターンは次のような流れです。

Claudeが間違える
↓
指示を追加する
↓
Claudeがまた間違える
↓
さらに指示を追加する
↓
CLAUDE.mdがどんどん長くなる

しかし、CLAUDE.mdが大きければ大きいほど、Claudeがプロジェクトを深く理解できるとは限りません。

主に3つの問題があります。

3.1. 不要なコンテキストを消費する

CLAUDE.mdは、セッション開始時に読み込まれるコンテキストの一部です。Skillの説明も起動時のコンテキストに含まれますが、Skillの本文は、そのSkillが利用されるときにだけ読み込まれます。

もしCLAUDE.mdに、

PR Review Process
Security Checklist
Release Note Process
Migration Process
Bug Analysis Process

がすべて含まれている場合、現在のタスクが単に、

Fix typo in README

であっても、これらの指示がコンテキストを消費することになります。

コンテキストウィンドウが大きいからといって、関係のない情報で埋めるべきではありません。

3.2. 指示が多すぎると、重要なルールが埋もれやすくなる

Anthropicは、各CLAUDE.mdを200行未満に抑えることを推奨しています。長いファイルはコンテキストを消費し、指示への追従性を下げる可能性があります。これは推奨値であり、上限ではありません。詳しくはWrite effective instructionsを参照してください。

例えば、必要な情報を入力した後も「Submit」ボタンが無効のままになる不具合を修正するとします。APIやデータベースは変更しないタスクです。

このタスクで必要なのは、次のような指示です。

• 既存のコンポーネント規約と状態管理の方式に従う。
• ボタンの有効／無効の判定条件に関わるロジックだけを修正する。
• 不具合の再現テストを追加し、関連テストを実行する。

しかし同時に、次のような指示までコンテキストに入っている場合があります。

Release procedure
PR Review procedure
Security checklist
Migration rules
API checklist
Testing workflow

この例ではTesting workflowが直接関係します。一方、データベースやAPIを変更しないため、Migration rulesとAPI checklistは現時点では不要です。Release procedureとPR Review procedureはリリースやレビューの段階で必要になります。一般的なセキュリティルールは常に守る必要がありますが、認証・認可に特化した詳細なチェックリストは、このボタンの状態不具合には直接関係しません。

Claudeは、今すぐ適用すべき指示、後の工程で必要になる指示、今回の変更範囲に含まれない指示を区別しなければなりません。問題は単なるトークン数ではなく、現在のタスクに重要な指示が、まだ必要のない指示と混在していることです。

3.3. プログレッシブローディングのメリットを活かせない

Skillsは、ClaudeがSkillの存在を認識しつつ、必要になったときだけ完全な内容を読み込めるように設計されています。

すべての手順を直接CLAUDE.mdに入れてしまうと、このメリットを活かせません。

次のように、

すべてを読み込む
↓
Claudeが必要な部分を探す

のではなく、

プロジェクトのルールを読み込む
↓
タスクを認識する
↓
必要なSkillを読み込む

という形にできます。

4. チェックリスト：指示はどこに置くべきか？

すべての指示をあらゆるタスクでClaudeに適用する必要はありません。用途や適用範囲に応じて、CLAUDE.mdとSkillを使い分けましょう。

簡単な見分け方：

次のように自問してください。「Claudeは、プロジェクトのほとんどのタスクでこの指示を知っておく必要があるか？」

• はい → CLAUDE.md：プロジェクトで作業する際にClaudeが覚えておくべき基本情報、共通規約、制約事項を記述します。
• いいえ → Skillを検討：特定のタスク向けのワークフロー、手順、チェックリストなら、Skillが適しています。

覚えておくポイント：

CLAUDE.mdは、Claudeにプロジェクト内での作業方針を伝えます。Skillは、特定の作業をどう進めるかを示します。

注：これは基本的な区別です。プロジェクトの一部にのみ適用する指示については、第6節で詳しく説明します。

5. CLAUDE.MDを保守しやすい構造にリファクタリングする

例えば、もともと次のような構造だったとします。

CLAUDE.md
├── Project architecture
├── Coding convention
├── API checklist
├── Testing procedure
├── Bug analysis procedure
├── PR review procedure
├── Security checklist
└── Release note procedure

これを次のように整理できます。

project/
│
├── CLAUDE.md
│
└── .claude/
    └── skills/
        ├── analyze-bug/
        │   └── SKILL.md
        │
        ├── review-pr/
        │   └── SKILL.md
        │
        ├── security-review/
        │   └── SKILL.md
        │
        └── release-note/
            └── SKILL.md

CLAUDE.mdを、プロジェクト全体のコンテキストとルールを保持するハブ（Hub）として扱います。

一方、Skillsは各タスク専用の作業手順を保持するスポーク（Spoke）になります。

                 review-pr
                    │
                    │
analyze-bug ─── CLAUDE.md ─── security-review
                    │
                    │
               release-note

Hub & Spokeモデルのインフォグラフィック：

• 中央：CLAUDE.md – プロジェクト全体のコンテキスト / ルール
• 周囲：.claude/skills/ – タスク別の作業手順

変更前：一つのファイルでClaudeにすべてを教えようとする構成

変更後：基本コンテキストの層と、必要なときに読み込むワークフローを組み合わせた構成

6. CLAUDE.MDとSKILLS以外の選択肢もある

実際のClaude Codeには、他にも注目すべき2つの仕組みがあります。

Rule

指示がルールであっても、特定のファイル群にのみ適用する場合は、.claude/rules/ に配置し、paths で適用範囲を限定します。

これにより、プロジェクト全体ではなく、関連するファイルを扱う場合にのみそのルールを適用できます。

.claude/
└── rules/
    ├── frontend.md
    ├── backend.md
    └── testing.md

Claude Codeは、パスごとに適用範囲を限定するルールをサポートし、該当するファイルを扱うときに読み込みます。

.claude/rules/frontend.mdの内容例（Markdown＋YAML frontmatter）：

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

# React conventions

- Use function components and TypeScript.
- Follow the existing component naming conventions.

Hooksは、Claude Codeで特定のイベントが発生したとき、設定済みの処理を自動的に実行する仕組みです。Claudeがその処理を自主的に行うかどうかに依存しません。

「ソースコードを修正した後、必ずformatterを実行する」という要件がある場合、

Always run formatter after editing files

とCLAUDE.mdに書くだけでは、確実な実行を保証する方法としては十分ではありません。

Hooksは特定のライフサイクルイベントで動作し、決められた処理を実行させたい場合に適しています。

設定例（.claude/settings.json、JSON）：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "file=$(jq -r '.tool_input.file_path // empty'); if [ -n \"$file\" ]; then pnpm exec prettier --write --ignore-unknown \"$file\"; fi"
          }
        ]
      }
    ]
  }
}

次のように分類できます。

Claudeが常に知っておく必要がある
→ CLAUDE.md

特定のファイルを扱うときだけ知る必要がある
→ .claude/rules/

特定のタスクの実行方法を知る必要がある
→ Skills

ライフサイクルイベントで実行する必要があるアクション
→ Hooks

このように、Claude Codeの各仕組みには異なる役割と適用範囲があります。CLAUDE.mdはプロジェクトの基本情報を、Rulesはファイルの範囲に応じたルールを、Skillsは専門的なタスクの手順を、Hooksはイベントに応じて自動実行する処理を担います。

ただし、実際には新しい指示をどこに置くか迷うこともあります。

では、CLAUDE.mdを肥大化させずに、適切な仕組みを選ぶにはどうすればよいでしょうか？

次のセクションでは、ここまでの内容をデシジョンツリーにまとめ、指示や処理の適切な配置先を素早く判断できるようにします。

7. シンプルなデシジョンツリー

新しい指示を追加する前に、次のように考えます。

この指示はほぼすべてのタスクに適用される？
│
├─ はい → CLAUDE.md
│
└─ いいえ
    │
    ├─ 特定のファイル群だけに適用される？
    │      └─ はい → .claude/rules/
    │
    ├─ 特定タスクの手順やチェックリスト？
    │      └─ はい → Skill
    │
    └─ 自動実行が必要なアクション？
           └─ はい → Hook

このデシジョンツリーだけでも、CLAUDE.mdをプロジェクト内のあらゆる指示を詰め込む「プロンプト保管庫」にしてしまうことを防げます。

8. まとめ

Claudeが間違えたとき、よくある反応は「指示を追加する」というものです。

しかし、Claude Codeを最適化するうえで重要なのは、単により良い指示を書くことだけではありません。

それと同じくらい重要なのは、その指示をどこに置き、いつClaudeに渡すべきかという問いです。

保守しやすい構成の一例は次の通りです。

Minimal CLAUDE.md
        +
Scoped Rules
        +
Task-specific Skills
        +
Deterministic Hooks

それぞれの役割は次の通りです。

• CLAUDE.md：プロジェクト全体のコンテキストと共通ルールを保持する。
• .claude/rules/：ルールを保持し、pathsで対象ファイルを限定する。
• Skills：タスクごとの手順や知識を保持する。
• Hooks：特定のライフサイクルイベントで実行する必要のあるアクションを処理する。

一つだけ原則を覚えるなら、次のように考えると分かりやすいでしょう。

CLAUDE.mdは、Claudeがプロジェクト内でどのように作業すべきかを定義する。Skillは、Claudeが特定のタスクをどのように実行すべきかを定義する。

最終的な目的は、Claudeにできるだけ多くのことを覚えさせることではありません。

重要なのは、適切なコンテキストと適切な指示を、必要なタイミングでClaudeに与えることです。

あなたのプロジェクトのCLAUDE.mdは、現在何行くらいありますか？すべての作業手順を一つのファイルにまとめていますか？ それとも、すでにSkillsへの分割を始めていますか？

参考資料

• CLAUDE.md / Project Memory
• Claude Code Skills
• Claude Code Context Window
• Claude Code Hooks Guide