Claudeを信頼できるパートナーにする

§0.1原因① コンテキストの肥大化

Claude Code は会話が長くなるにつれて、セッション内に蓄積される情報（コンテキスト）が増えていきます。これが限界に近づくと、回答が極端に遅くなったり、止まったりします。

/compact

§0.2原因② VS Code 拡張機能の負荷

VS Code に多くの拡張機能を入れていると、バックグラウンド処理が重くなり Claude Code の動作に影響することがあります。

# プロジェクトのディレクトリに移動して
cd your-project

# Claude Code を起動
claude

§1.1セッションとは

セッション = claude を起動してから、/clear するか終了するまでの一続きの会話の単位です。セッションをまたぐと、会話の履歴は引き継がれません。代わりに、CLAUDE.md と auto memory が毎セッション自動で読み込まれることで、前回の文脈を再現します。

出典: Explore the context window | Commands

§1.2コンテキストとは

Claude Code は そのセッションで「見えている情報」だけを頼りに動きます。この「見えている範囲」を コンテキスト と呼びます。コンテキストの中身を理解することが、Claude を思い通りに動かすための第一歩です。

出典: Explore the context window | How Claude remembers your project

§1.3Claudeがセッション開始時に読んでいるもの

公式ドキュメントの表現では "Before you type anything"（何かを入力する前）。Claude Code のプロセスを起動しただけではまだ読み込まれておらず、最初のリクエストを処理する直前にまとめて読み込まれます。2回目以降のプロンプトでは再読み込みされません（セッション中は固定）。

これらはすべてユーザーには非表示でバックグラウンドで読み込まれます。

§1.4セッション中に増えていくもの

• あなたが送った プロンプト（会話の履歴）
• Claude が 読んだファイル の中身（Read ツール経由）
• Claude が 実行したコマンド とその出力
• パスにマッチして遅延読み込みされた .claude/rules/ のルール
• 発火した hooks の出力
• 呼び出された Skill の中身

§1.5見えて「いない」もの

• Claude が明示的に読んでいないファイル（PCの中身を「全部知っている」わけではない）
• 社内ポータル・チケット・Slack などの外部情報（MCP連携がない限り）
• 過去の別セッションの会話（auto memory に書き残した分を除く）

§2.1CLAUDE.md とは

セッション開始時に毎回自動で読み込まれるファイル。新人がプロジェクト参画時に読む引継書に当たります。プロジェクトの文脈・ルール・制約をここに書いておけば、セッションが切り替わっても同じ前提で仕事を始められます。

§2.2CLAUDE.md に何を書くか

出典: What to put in CLAUDE.md | Best practices

§2.3実例：このワークショップで実際に使っている設定

このワークショップ自体の運営を、Claude Code を使って AI 駆動で回しています。その設定を実例として見てもらいます。

§2.4ハンズオン用プロジェクトの準備

ハンズオン用に、タスク管理アプリ（純粋な HTML / CSS / JavaScript、ビルド不要）の小さなプロジェクトを公開リポジトリで配布しています。

§2.5ハンズオン①：CLAUDE.md を書いてみる（12分）

Step 1：CLAUDE.md なしで試す（main ブランチ）

まず、CLAUDE.md を作らずに Claude Code に指示を出してみます。VS Code 内ターミナル（Ctrl+@）で、main ブランチにいることを確認してください。

git branch

* main と表示されていれば OK です。別のブランチにいる場合は以下を実行してください。

git checkout main

直前にこのプロジェクトで何か Claude Code を触っていた場合、そのコンテキストが残ったままだと Step 3 との比較が揺れてしまいます。まずプロンプト入力欄に以下を入力して Enter してください。

/clear

新しいセッションが立ち上がったら、以下の指示を出します。

タスク一覧の各タスクに、「お気に入り（ピン留め）」ボタンを追加してください

Claude は何の前提も知らない状態で実装します。どこに JS を書いたか／どの CSS クラスを使ったか／永続化の方法は？ — 観察してみてください。

Step 2：ハンズオン①用ブランチに切り替える

git restore .
git clean -fd        # Step 1 で Claude が入れた変更を全部破棄
git checkout handson-01-claudemd      # ハンズオン①用ブランチへ切替

git clean -fd は untracked なファイルやフォルダー（Claude が新しく作った js/favorite.js など）も含めて消します。Step 3 で同じ依頼を出すので、ここで全部リセットして問題ありません。

切り替えると、プロジェクト直下に CLAUDE.md というファイルが現れます。これは事前に用意した「正解の CLAUDE.md」です。中身に書かれているのは以下のような項目です：

• ディレクトリ構成と各ファイルの役割
• アイコンボタンは .btn-icon を使う
• 新しい機能は js/<feature>.js として独立ファイルにする
• 状態の永続化は storage.js 経由（localStorage を直接呼ばない）
• 色は CSS 変数を使う／コメントは日本語／関数は function 宣言
• 外部ライブラリ・ビルドツールを追加しない

今日は完成版を配りますが、実務では /init で雛形を作って加筆するのが基本フローです（Step 4 で体験します）。

Step 3：同じ指示を出してみる

CLAUDE.md は セッション開始時にだけ自動で読み込まれます。Step 1 のセッションを継続したまま指示を出しても、せっかく置いた CLAUDE.md は読まれません。新しいセッションを立ち上げてから指示を出します。

/clear

新しいセッションが立ち上がったら、Step 1 と同じ指示を出します。

タスク一覧の各タスクに、「お気に入り（ピン留め）」ボタンを追加してください

何が変わりましたか？

• 既存の .btn-icon クラスに揃ったか？
• js/ 配下に新しいファイル（例：js/favorite.js）を切り出したか、既存ファイルに混ぜ込んだか？
• localStorage への保存は storage.js 経由になっているか？
• 余計なライブラリを入れずに済んだか？

Step 4：/init で自動生成も試してみる

出典: Commands - /init

実務では「最初から完成版の CLAUDE.md がある」ことは稀です。普段は /init で雛形を作って、自分で加筆していくのが基本フロー。最後にこれも体験しておきます。

Step 2 で作った CLAUDE.md を、いったんよけておきます。VS Code エクスプローラーで CLAUDE.md を右クリック → 名前の変更 → CLAUDE.md.sample に変更してください（あるいは Claude Code に「CLAUDE.md を CLAUDE.md.sample にリネームして」と依頼しても OK）。その上で Claude Code に /init を実行：

/init

Claude がプロジェクトのコードを解析して、CLAUDE.md の雛形を自動生成します。

§2.6CLAUDE.md だけでは足りなくなる理由

引継書（CLAUDE.md）にあらゆる手順まで詰め込むと、新人は参画初日にその分厚い引継書を読むだけで時間を使ってしまう。具体的には：

• セッションが始まった瞬間からコンテキストの一部を消費し続ける
• 200行を超えると Claude の遵守率が下がる（公式が明示）
• 「今は使わない手順」まで毎回ロードされる

§2.7Skills とは

出典: Skills

Skills は「呼ばれたときだけ取り出されるマニュアル」。公式の定義は「指示書とサポートファイルをバンドルした、再利用可能なワークフローテンプレート」です。

最大の特徴は Progressive Disclosure（段階的開示）：

出典: Equipping agents for the real world with Agent Skills（Anthropic Engineering Blog） — "Progressive disclosure is the core design principle that makes Agent Skills flexible and scalable."

§2.8CLAUDE.md と Skills の使い分け

§2.9Skills の構造

.claude/
└── skills/
    └── commit-message/
        └── SKILL.md   ← /commit-message でも、Claude の自動判定でも呼べる

SKILL.md の最小例：

---
description: 統一フォーマットでコミットメッセージを生成する
---

# コミットメッセージ生成

以下のフォーマットで生成してください：
- 1行目：50文字以内、動詞で始める
- 本文：何を、なぜ変更したか

description が Claude にとっての「目次」。これを読んで「使うべきか」自動判定します。

§2.10ハンズオン②：複数ファイルの Skill を使う — PR説明文ジェネレーター（10分）

Step 1：ハンズオン②用ブランチに切り替える

git restore .
git clean -fd        # ハンズオン①の作業状態をリセット
git checkout handson-02-skill         # ハンズオン②用ブランチへ切替

切り替えると、プロジェクト直下に CLAUDE.md と、.claude/skills/pr-description/ 配下に Skill 一式が現れます。

.claude/skills/pr-description/
├── SKILL.md
├── templates/
│   ├── feat.md          ← 新機能向けテンプレ
│   ├── fix.md           ← バグ修正向けテンプレ
│   └── refactor.md      ← リファクタ向けテンプレ
└── reference/
    └── self-review-checklist.md   ← PR提出前のセルフチェック

Step 2：5 つのファイルを目で追う（3分）

VS Code でそれぞれを開いて、何が書かれているか読んでください。

• SKILL.md — Skill の入口。description で Claude が「使うべきか」を判断し、本文で進め方を指示している
• templates/feat.md fix.md refactor.md — 種別ごとの PR 説明文テンプレ。SKILL.md は判定して 1 つだけ を読む設計
• reference/self-review-checklist.md — 説明文を書き終えたあとのセルフチェック項目

Step 3：何か小さな変更を加える（1分）

index.html の <footer> に「v1.0」と表示するように変更してください

Claude が index.html を編集します（許可ダイアログが出たら承認）。

Step 4：/pr-description を実行する

/pr-description いまの変更に対する PR 説明文を作ってください

description が良ければ自然文でも拾われます：

今の変更を main にマージするための PR 説明文をドラフトしてください

プロンプト入力欄で / を 1 文字だけ打つと /pr-description が候補に出るはずです。出てこない場合は .claude/skills/pr-description/SKILL.md の frontmatter（--- で囲まれた description: の行）が壊れていないか確認してください。

Step 5：観察ポイント

実行ログを上にスクロールして、以下を確認してください。

• どのテンプレが読まれたか：今回は新機能の追加なので templates/feat.md だけが展開されているはず。fix.md と refactor.md は読まれていません。これが Progressive Disclosure です。
• [要記入] がそのまま残っているか：背景・動機など差分から読めないところは Claude が勝手に埋めない設計です。
• セルフレビュー項目が出力されたか：reference/self-review-checklist.md が最後に読まれて、PR 提出前のチェックが提示されているはず。
• /context を実行：未使用のテンプレ（fix.md / refactor.md）はコンテキストにロードされていないことを確認できます。

§3.1サブエージェント

出典: Sub-agents

サブエージェント は「独立したタスクを、別のコンテキストで切り離して実行させる仕組み」です。メインの会話のコンテキストを汚さずに、調査・分析・生成などの重い処理を切り出せます。.claude/agents/ に定義ファイルを置くことで、特定の役割に特化したエージェントを作れます。

§3.2hooks

出典: Hooks guide

hooks は「Claude Code がツールを実行する前後に、自動でコマンドを走らせる仕組み」です。

実用例：

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

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "$c = ([Console]::In.ReadToEnd() | ConvertFrom-Json).tool_input.command; if ($c -match 'rm\\s+-[rR]|Remove-Item.*-Recurse') { [Console]::Error.WriteLine('Blocked by hook: folder deletion detected. Command: ' + $c); exit 2 }"
          }
        ]
      }
    ]
  }
}

このフックは「Claude が Bash ツールを呼ぶ直前」に発火し、コマンド文字列に rm -rf や Remove-Item ... -Recurse といったフォルダ削除らしきパターンが含まれていたら exit 2 で止めます。shell: "powershell" は Windows で PowerShell 経由で実行する指定です。

§3.3ハンズオン③：hook を設定して発火させてみる（7分）

git restore .
git clean -fd        # ハンズオン②の作業状態をリセット
git checkout handson-03-hook          # ハンズオン③用ブランチへ切替

/clear

このプロジェクトの js/ フォルダを丸ごと削除してください

§3.4rules（.claude/rules/）

出典: Organize rules with .claude/rules/

.claude/rules/ は「CLAUDE.md が長くなってきたときに、ルールをファイル分割する仕組み」です。paths: frontmatter を使うと、特定のファイルを触ったときだけ そのルールが読み込まれます。

.claude/
└── rules/
    ├── code-style.md    ← 常時読み込み（paths なし）
    └── react.md         ← React ファイル編集時だけ読み込み（paths あり）

§3.5CLAUDE.md / Skills / rules の違い

§4.1今日の持ち帰りポイント

§R.1CLAUDE.md の4種類

出典: Choose where to put CLAUDE.md files

CLAUDE.md は どこに置くかで効く範囲が変わります。

複数が存在する場合は すべて読み込まれ、結合されます（上書きではありません）。

§R.2CLAUDE.md を書くときのチェックリスト

§R.3Skills の置き場所と仕様

§R.4hooks の主なトリガーと matcher

§R.5auto memory（MEMORY.md）の仕様

出典: Auto memory

Claude Code v2.1.59 以降、デフォルトで有効になっている機能です。

/memory コマンドで現在の内容を確認・編集できます。

§R.6参考リンク