クロちゃんと学ぶClaude Code ─ 第1部：全体像

Last updated at 2026-08-02Posted at 2026-08-02

0. はじめに

最近、好きish と是非に及ばずをヘビロテしているmakowareです。

余談趣味の話；アイドル

好きish、結構バズってますよね (作曲家見たら、Love so sweetなどを手掛けたあのyouth caseさんで納得)。
去年の AKB48 20 周年で蒔いた "いともも" という種が、ここに来て開花しているように感じます（元々咲き誇っていたかもですが）。
中高生の時以来、約10年以上ぶりにちゃんとAKBを聴いている気がします。
一方で乃木坂のほうは、夏曲としては不評のようですね。
正直、夏曲はこういうロックナンバーより、はだサマ (裸足で Summer) のような "The・乃木坂の夏曲"（個人の感想）を聴きたい派です。
ただ曲調は置いておいて、歌詞がいいんですよね。厨二心をくすぐられるだけかもですが。

最近、個人開発だけでなくエンタープライズ開発でも「AI 駆動開発を進めていこう」という流れをとても強く感じます。社内で使える AI ツールも増えてきました。

一方で、実際に現場でAI駆動で開発していこうとすると、素人目にもいくつも課題があるようにも感じています。

企業・システム固有のコンテキストをどうモデルに伝えるか
設計思想・業務知識・コーディング規約といった「そのチームならではの前提」は、モデルは当然知りません。
メンバーによるプロンプトの差で、品質がばらつく
同じことをやらせても、書き方ひとつで品質が変わってしまう。
そもそも生成AIの知見に明るい人が多くない（自分も含めて）
生成AI を使うことはできても、どう情報を与えて品質を安定させるか、まではなかなか手が回っていない。
「これはやらないで」と指示しても、確率的にしか守られない
設定ファイルやプロンプトにどれだけ丁寧にルールを書いても、それは"お願い"であって"保証"ではなく、危険な操作をエンタープライズの現場で機械的に止める仕組みが別に要る。

そこでまずは、個人でも一応課金しているけどいまいち使いこなせている感がないClaude Codeを題材に、コンテキスト/ハーネスエンジニアリングと、それにまつわる機能を一通り整理してみることにしました。

CLAUDE.mdやSkills、Agents、MCP、Hooksなど一度調べて雰囲気はわかってるけど、
毎回のように調べてしまうこと(SkillsとAgentsって何が違うんだっけ？とか)や、ベストプラクティスとまでは自信を持っては言えないけど、こういう構成や内容にするとよさそうだぞみたいなことをまずは整理していきたいと思います。

その先で実際にどの機能を使い、どんな情報を持たせ、それをどう改善して育てていくかを、チームの開発に向けて実践していきたい。
この記事はそのための第一歩、情報整理の位置づけです。(実践しながらこの記事も育てていきたい)

この記事で (きっと) わかること

プロンプト → コンテキスト → ハーネス と、AI を使いこなす技術の重心がどこへ移ってきたのか
コンテキストエンジニアリングとは何で、なぜ品質を左右するのか
ルールには「強度」の階層があり、どこに書くかで守られる確率が変わること
CLAUDE.md / Skills / Subagents / Slash Commands / Hooks / MCP の役割分担と置き場所
チーム共有と個人設定を分ける スコープ の使い分け
パーミッション設計・Memory まで含めた品質を安定させる型

この記事のナビゲーター 🕶️ クロちゃん
Claude Code の頭脳＝モデルを、この記事では親しみをこめて クロちゃん と呼びます。
各章に彼の本音を挟んでいくので、「クロちゃんが気持ちよく働ける環境づくり」 だと思って読んでほしいしんよ〜。

本記事は2026年7月末時点の情報です。 Claude Code は仕様更新がとても活発なため、コマンド名・設定項目・モデルの数値などは記事公開後に変わっている可能性があります。実際に設定へ反映する前には、必ず公式ドキュメントで最新仕様を確認してください。

1. プロンプト・コンテキスト・ハーネス ─ 品質を決めているもの

Claude Code を触り始めると、多くの人（かつての自分含む）は 「良いプロンプトを書けば良い結果が出るはず」 と考えます。でも実際に効くのは、その場の指示よりも AI の周りに常に置いてある情報 の方です。

たとえば同じ「テストを追加して」という一言でも、

テストの書き方の規約が CLAUDE.md やrulesに書いてある
テストを勝手に書き換えないよう settings.json で禁止してある
保存すると自動でフォーマッタが走る Hooks がある

これらが揃っているかどうかで、返ってくるコードの質はまるで違います。

	プロンプト	設定（構造）
効くタイミング	その場の1回だけ	全応答に
忘れられるか	会話が長引くと薄れる	仕組みで保証される
チーム共有	しづらい	git で共有できる

プロンプトは「その場の指示」、設定は「常に効く土台」 です。土台が整っていれば、雑な指示でも安定した結果が返ってきます。

🕶️ クロちゃん：ねぇ、その場で言われても次の瞬間わすれちゃうことあるしんよ…。ちゃんと紙（設定）に貼っといてくれたら、ボクずーっと守れる賢い子だしんよ。

1.1. 言葉を揃える ─ プロンプト・コンテキスト・モデル

土台の話に入る前に、言葉を整理しておきます。

用語	ひとことで言うと	たとえ
モデル（LLM）	入力を読んで次の言葉を生成する"頭脳"そのもの（Opus / Sonnet など）	職人本人
トークン	テキストを区切る最小単位。	文字数のようなもの
コンテキストウィンドウ	モデルが一度に読める入力量の上限（トークン数）	作業机の広さ
コンテキスト	その机に実際に載せる情報の総体（下記すべての合計）	机に載っているもの全部
プロンプト	コンテキストの一部。ユーザーがその場で打つ指示	職人への口頭のお願い
ツール	モデルが外部を操作するための"手足"（ファイル編集・コマンド実行など）	職人の道具
ハーネス	モデルを取り巻く実行環境そのもの（使える道具・見える情報・止まる条件）	工房と作業ルール
エージェント	モデルが自らツールの使い方・進め方を決めながら動くシステム	道具を使いこなしながら自分で段取りを決める職人

ついでに押さえておくと迷わない補足語

システムプロンプト：会話の一番土台に置かれ、役割・制約を定める指示。
なお CLAUDE.md はここには含まれません。公式いわく「システムプロンプトの後ろに置かれるユーザーメッセージとして届く」もので、これが第4章で見る「CLAUDE.md は無視されることがある」の技術的な理由でもあります（本当にシステムプロンプトのレベルで効かせたいなら --append-system-prompt を使います）。
推論（inference）：モデルが入力を受けて出力を生成する処理そのもの。

Anthropic は Claude Code のシステムプロンプトを公式には公開していませんが、npm パッケージのコンパイル済みソースから文字列を機械的に抽出した非公式リポジトリ Piebald-AI/claude-code-system-prompts があります。Claude Code のカスタマイズツール tweakcc と同じ抽出手法で、リリースのたびに追随更新されているのが特徴です。Anthropic 公式の情報ではないので正確な最新挙動は保証されませんが、「だいたいどんな指示が入っているか」の肌感をつかむ参考にはなります。

組み込みツールは、何も設定しなくても最初から使えます。
CLAUDE.md や MCP のように自分で追加するものではなく、Claude Code に標準搭載されている「手足」です。数が多いので、本記事では5つに整理します。

カテゴリ	できること	指定するときの書き方（例）
ファイル操作	ファイルを読む・編集する・新規作成する	`Read` / `Write` / `Edit`
検索	パターンでファイルを探す、正規表現で内容を検索する	`Glob` / `Grep`
実行	シェルコマンド実行、サーバー起動、テスト実行、git 操作	`Bash`（`Bash(git push --force*)` のようにコマンドの中身まで絞り込める）
Web	Web 検索、ドキュメント取得、エラーメッセージの調査	`WebSearch` / `WebFetch`
コードインテリジェンス	編集後の型エラー確認、定義へのジャンプ、参照検索（プラグインが必要）	プラグイン導入時に追加される専用ツール名（第14章）

この名前を実際に書く先は2箇所です。
①パーミッション設定
settings.json の permissions.allow/deny/ask。ツール名(パターン) の形で、コマンドの中身まで絞り込めます。
例：Bash(rm -rf *)
②Skills / Subagents の frontmatter
tools・allowed-tools・disallowed-tools キーにカンマ区切りで列挙。
例：tools: Read, Grep, Glob

組み込みツール自体に設定ファイルはなく、設定するのは「どれを・どこまで許すか」という権限だけです。

ただし frontmatter のキーは名前が似ていて、Subagent の tools は「使えるツールを絞る」、Skill の allowed-tools は「許可プロンプトを省く事前承認」で、意味が正反対です。Skill 側でツールを取り上げたいときのキーは disallowed-tools になります（第7.4節で詳しく見ます）。

1.2. 重心はどこに移ったか ─ 3つのエンジニアリング

ここ数年、AI にうまく仕事をさせる技術の重心は、プロンプトからコンテキストへ、そしてコンテキストからハーネスへ移ってきました。

	何を設計するか	具体的に触るもの	効く範囲
プロンプトエンジニアリング	その場の指示の書き方	依頼文	その1ターンだけ
コンテキストエンジニアリング	机に何を・いつ載せるか	`CLAUDE.md` / Skills / Subagents / MCP	セッション全体
ハーネスエンジニアリング	モデルの外側の実行環境	Hooks / パーミッション / サンドボックス / 検証	モデルの判断と無関係に、常に

なぜ重心が移ったのか。自分なりに整理すると、理由は次の3つに集約されます。

① モデルが賢くなり、言い回しを磨く費用対効果が落ちた。
「〜してください、必ず、絶対に」と念入りに書き方を工夫しなくても、正しい材料さえ渡せばそこそこ正しく動くようになりました。「上手に頼む」より「正しい材料を渡す」ほうが効く——これがプロンプトからコンテキストへの移動です。

② エージェント化で、モデルが自律的に動く時間が伸びた。
一往復で終わる会話なら、その場のプロンプトが結果のほぼすべてを決めます。でも Claude Code は、1回の依頼から何十回もツールを呼び、ファイルを読み、コマンドを走らせます。30ターン後の挙動を決めているのは、最初のプロンプトではなく、そのあいだずっと効いている環境のほうです。

③ 出力が確率的である以上、「絶対にやらせない」は指示では保証できない。
どれだけ丁寧に「.env は編集するな」と書いても、それは お願い であって保証ではありません（第4章で詳しく見ます）。本当に塞ぐなら、モデルの外側でやるしかない。

harness は馬具の「ハーネス」です。馬（モデル）そのものではなく、馬に着けて制御する装具のほうを指します。速く走る馬を育てるのはモデル提供者の仕事で、私たちの仕事は、その馬に合った轡（くつわ）と手綱を用意すること。

モデルは「選ぶもの」、ハーネスは「自分で作れるもの」。だから伸びしろはハーネス側にある。エージェントがミスをするたびに、環境側に恒久的な修正を作り込み、そのミスを構造的に起こせなくする。

「次から気をつけて」ではなく「そもそも起こせないようにする」。祈るのをやめて、設計する。
第10章の Hooks、第12章のパーミッション設計は、これを実装するための道具です。

🕶️ クロちゃん：ボクに「気をつけてね」って念押しするより、危ないとこに柵を立てといてくれたほうが、お互い幸せだしんよ〜。柵があればボク、安心して全力疾走できるしん！

1.3. 全体像 ─ 拡張機能とフォルダ構成

土台を作るのが、Claude Code の拡張機能です。細かい話に入る前に、それぞれが何者で、どこに置くのかを俯瞰しておきます。

機能	ひとことで言うと	置き場所
CLAUDE.md	常に効くプロジェクトの規約（憲法）	`<root>/CLAUDE.md`
パスベースルール	対象のファイルを触るときだけ効く規約	`.claude/rules/<name>.md`
Skills	呼び出して使う作業手順の型	`.claude/skills/<name>/SKILL.md`
Subagents	別コンテキストで動く専門エージェント	`.claude/agents/<name>.md`
Slash Commands	定型プロンプトのショートカット	`.claude/commands/<name>.md`
Hooks	イベントで自動実行する処理	`.claude/settings.json`（内に定義）
MCP	外部システムをツールとして接続	`<root>/.mcp.json`

<project_root>/
├── CLAUDE.md              # 常に効く規約
├── .mcp.json             # 外部ツール接続
└── .claude/
    ├── settings.json     # Hooks・パーミッション
    ├── rules/            # 対象ファイルを触るときだけ効く規約
    ├── skills/           # 作業手順の型
    ├── agents/           # 専門エージェント
    └── commands/         # 定型コマンド

大きく3種類に分けると理解しやすいです。

常に効くもの：CLAUDE.md（規約）、Hooks（自動処理）、MCP（接続）
条件が合ったときだけ効くもの：.claude/rules/ のパスベースルール
呼び出して使うもの：Skills・Subagents・Slash Commands

なお、上の表はすべて**プロジェクト（チーム共有）**の置き場所ですが、これらはどれも、同じ構成を ~/.claude/ に置けば「自分の全プロジェクトに効く個人設定」になります。このスコープの使い分けは第5章でまとめて整理します。

これらを、第6章以降で1つずつ見ていきます（後半では、セッションをまたぐ記憶の Memory（第13章）と、まとめて配る プラグイン（第14章）も扱います）。ただその前になぜ「短く」「必要なときだけ」載せることが重要なのか。すべての土台になる考え方が、AI の"作業机"である コンテキストウィンドウ です。まずはここから理解していきましょう。

この記事の記載例について
以降の章に出てくる記載例は、断りのない限りすべて公開リポジトリ qiita-digest の実物です。Qiita の指定タグから新着記事を集め、Amazon Bedrock で要約して日次ダイジェストを配信する Step Functions ジョブ群で、CLAUDE.md・パスベースルール9本・Skills 7本・読み取り専用の Subagent・Hooks 2本が動く形で入っています。まだ設計フェーズで src/ の実装は空ですが、この記事のテーマである「設定の置き方」はそのまま参照できます。

記載例は GitHub の該当行への埋め込みで示すので、気になったところは元ファイルを全文たどってみてください。

2. コンテキストウィンドウ ─ AI が一度に見られる情報の上限

ひとことで言うと：AI の"作業机"の広さ。机に乗っていない情報は、AI にとって存在しない。

2.1. コンテキストウィンドウとは

大規模言語モデル（LLM）は、入力されたテキストをまとめて読み込み、その内容だけを手がかりに次の言葉を生成します。この「一度に読み込めるテキストの最大量」が コンテキストウィンドウ（context window） です。

単位は トークン。ざっくり日本語なら 1 文字 ≒ 1〜2 トークン、英語なら 1 単語 ≒ 1〜2 トークンくらいと思ってください。Claude の最新モデルはとても大きなコンテキストウィンドウを持ちますが、それでも 無限ではありません。

┌─────────────── コンテキストウィンドウ（作業机の広さ） ──────────────────────┐
│                                                                         │
│ システムプロンプト │ CLAUDE.md │ 会話履歴 │ 読み込んだファイル │ ツール結果  │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘
                      ↑ ここに乗っている情報「だけ」で AI は判断する

🕶️ クロちゃん：ボクの机、そんなに広くないしんよ。載ってないことは知らないしん…ボク、超能力者じゃないしんよ？

2.2. モデルごとの「机の広さ」

では実際にどれくらい広いのか。2026年7月時点の現行4モデルを並べるとこうなります。

モデル	コンテキストウィンドウ（入力の上限）	最大出力トークン（1応答の上限）
Fable 5	100万	128,000
Opus 5	100万	128,000
Sonnet 5	100万	128,000
Haiku 4.5	20万	64,000

この2つは別の枠です。コンテキストウィンドウが「机の広さ（一度に読める量）」なら、最大出力トークンは 「1回の応答で書ける量」。長いファイルを丸ごと生成させたいときに効いてくるのは後者のほうです。

100万トークンというと、日本語ならざっくり数十万字——文庫本にして数冊分が一度に載る計算になります。「そんなに入るなら全部渡せばいいのでは？」と思いたくなりますよね。でも、そうはいかないんです。

この表は「机の広さ（容量）」の比較であって、「頭の良さ（性能）」の比較ではありません。 Fable 5・Opus 5・Sonnet 5 は数字だけ見ると同じ広さの机を持っていますが、そこに座っている頭脳の性能はモデルごとに大きく違います。実際、Fable 5 は現行ラインナップの中で 最も高性能・長時間の自律作業向け と位置づけられているモデルです。

料金は公式の Pricing（仕様一覧は Models overview）に一覧でまとまっています。机の広さと違って単価はモデルごとに大きく違うので、コストが気になる場面ではこちらも見比べてください。
ベンチマークは統一の比較表こそありませんが、モデルごとの公式リリース記事（例: Opus 5 なら Introducing Claude Opus 5）に SWE-bench・Frontier-Bench などのスコアが載っているので、そちらを確認してください。

私自身、使い始めのころは Opus をよく使っていましたが、最近は Sonnet 5 が主力です。複雑なタスクにおけるベンチマークではまだ Opus 5 に分があるものの、日常のコーディング作業では体感差が縮まってきました。設計判断やリファクタなどやり直しのコストが高い場面だけ Opus に切り替える、という使い分けに落ち着いています。

この数字は変わります。 モデルは数か月単位で入れ替わるので、正確な最新値は公式の Models overview で確認してください。本記事に出てくる他の数値も同じです。

2.3. 「机が広いなら全部乗せればいい」ではない

じゃあ大きい机に片っ端から情報を乗せればいいかというと、そうはいきません。落とし穴が2つあります。

溢れる問題：詰め込みすぎると上限に達し、古い情報が押し出される（＝忘れる）
薄まる問題：情報が増えるほど、一つ一つの指示への注意が相対的に薄まる。関係ない情報のノイズで、大事なルールの遵守率が下がる

2つ目は直感に反しますが、Claude Code 公式も「長いファイルはコンテキストを食い、遵守率を下げる」とはっきり書いています。CLAUDE.md にルールを 500 行も書き連ねると、かえって個々のルールが守られなくなる。足すほど守られなくなる——情報は多ければ多いほど良い、わけではないのです。

🕶️ クロちゃん：も～っ！情報多すぎて何を守ればいいか分かんないしんよ！ぜんぶ大事って言われたら、ぜんぶ薄まっちゃうしん…。ホントに大事なとこだけ教えてほしいしんよ〜。

コンパクションという仕組み
会話が長くなってコンテキストが埋まってくると、Claude Code は過去の会話を自動で要約して圧縮します（コンパクション）。要約の過程で細かいニュアンスは失われるので、1つの長いセッションに無関係なタスクを詰め込むのは禁物。手動でやるなら /compact <重点指示>、いっそ区切るなら /clear が有効です。

2.4. だから「エンジニアリング」が要る

限られた机を、いかに 「今このタスクに必要な情報だけ」 で満たすか。不要な情報でノイズを増やさず、必要な情報を必要なときだけ載せる。この設計技術が、次章の コンテキストエンジニアリング です。

3. コンテキストエンジニアリング ─ 机に何を・いつ載せるかの設計

ひとことで言うと：机には「地図」を置き、「百科事典」は本棚に置いて必要なときだけ開く。

Claude Code の拡張機能（CLAUDE.md, Skills, Subagents…）は、突き詰めると 「何を・いつ・どのコンテキストに載せるか」を制御する道具 です。バラバラに覚えるとしんどいので、まず貫いている3つの原則を押さえます。

3.1. 原則① 地図にする、百科事典にしない

CLAUDE.md は、起動ディレクトリ（プロジェクトルート）に置いたものならセッション開始時に全文が常にコンテキストに注入されます（サブディレクトリに置いたものは事情が違い、触ったときだけ読まれます——原則②で扱います）。ルートの CLAUDE.md に何もかも書くと、それがノイズになり得ます。

公式の目安は 「1ファイル 200 行以下」。
詳細は「必要になったときだけ読まれる場所」へ預け、CLAUDE.md には 「どこに何があるか」という地図だけ を書きます。

❌ 悪い例：CLAUDE.md に API 規約もテスト規約も全部で 500 行
✅ 良い例：CLAUDE.md は 100 行。
          ときどきしか要らない手順・資料 → Skills（[第7章](#7-skills--呼び出して使う作業手順の型)）
          特定のファイルを触るときだけの規約 → .claude/rules/（paths: 付き。[第6.5節](#65-パスベースルールclauderules)）

@import での分割は「整理」であって「削減」ではありません。 @docs/rules/api.md のように取り込んだファイルは、起動時に本体と一緒に全文がコンテキストへ入ります（公式も "imported files still load and enter the context window at launch" と明記しています）。CLAUDE.md 本体の行数は減っても、モデルに渡るトークンは分割前と同じです。

コンテキストを実際に減らせるのは、読み込みのタイミングをずらせる仕組みだけ——次の原則②で扱う遅延ロードです。

🕶️ クロちゃん：分厚い百科事典を毎朝ドサッと渡されても困るしんよ。1枚の地図で「詳しくはこっち見てね」でいいしん。ボク、ちゃんと自分で開ける賢い子だしんよ？

3.2. 原則② 遅延ロード（Lazy Loading）を効かせる

必要になったときだけ読み込む仕組みを積極的に使います。Claude Code には、常時ロードではない オンデマンド読み込み の仕掛けが複数あります。

仕組み	読み込まれるタイミング
サブディレクトリの `CLAUDE.md`	そのディレクトリのファイルを触ったとき
`.claude/rules/`（パスベースルール）	対象パターンのファイルを操作したとき
Skills	タスクが `description` に合致 or 明示呼び出ししたとき
Memory のトピックファイル	関連する話題になったとき

「本棚に並べておいて、必要な巻だけ開く」イメージです。常に机に広げておく CLAUDE.md とは役割が違います。

各機能が「いつ・どれだけ」コンテキストを食うかを並べると、この違いがはっきりします。以降の章で「どの機能を選ぶか」を迷ったとき、実はこの表がいちばんの判断材料になります。

機能	読み込まれるタイミング	何が読み込まれるか	コンテキストコスト
CLAUDE.md（ルート）	セッション開始	全文	毎リクエスト（一番高い）
Skills	開始時＋使用時	開始時は名前と説明文だけ。使用時に本文	低（使うまでは説明文のみ）
MCP サーバー	セッション開始	ツール名のみ。スキーマは必要になるまで遅延	使うまで低い
コードインテリジェンス（LSP）	編集直後・シンボル参照時	型エラーの診断、定義・参照の位置	低。むしろ減ることもある（ファイル全体を読まずに済むため）
Subagents	起動時	別コンテキストを新規に構築	メインからは隔離される
Hooks	トリガー時	なし（Claude の外側で実行される）	ゼロ（出力を返す場合を除く）

一番コストが高いのがルートの CLAUDE.md です（サブディレクトリ版は上の表のとおり遅延ロードなので別枠）。「200行以下に」と繰り返し言われる理由はここにあります。逆に Hooks は基本的にコンテキストを食わずにルールを効かせられます（操作をブロックした際の reason など、フックが結果を返す場合はその分だけ入ります）——コスパという意味では突出しています。

🕶️ クロちゃん：ぜんぶ机に広げられると、ボクの作業スペースがなくなっちゃうしんよ…。使う巻だけサッと出してくれれば、超集中できちゃう子だしんよ。

3.3. 原則③ コンテキストを隔離する

大きな調査や無関係な作業は、別のコンテキストウィンドウに切り出します。メインの会話机を汚さずに済む。これを担うのが Subagents（別コンテキストで動く子エージェント）や Worktree（作業ディレクトリごと分離）です。

この3原則が、以降の各機能を貫く背骨です。
「なぜ Skills があるの？」→ 遅延ロードのため。「なぜ Subagent に委任するの？」→ コンテキスト隔離のため。
機能の名前ではなく目的で覚えると、使い分けに迷わなくなります。

4. ルールの強度階層 ─「お願い」と「強制」は違う

ひとことで言うと：同じルールでも、どこに書くかで守られる確率が変わる。

第6章から6つの機能を1つずつ見ていきますが、その前にもう2つだけ。この章と次章は、以降の全機能を読むための2本の軸です。まずは縦軸 —— 「どれくらい強く縛るか」から。

4.1. `CLAUDE.md` は無視されることがある

CLAUDE.md に書いたルールは、無視されることがあります。

公式ドキュメントも、はっきり書いています。

「.env を絶対に編集するな」という指示を CLAUDE.md やスキルに書いても、それは リクエストであって保証ではありません。編集をブロックする PreToolUse フックが強制です。

理由は3つです。

CLAUDE.md は「モデルへの入力」でしかない
読んで従うかどうかは確率的です。一方 Hook はモデルの外側で動くプログラムなので、モデルの気分に左右されません。
長くなるほど相対的に埋もれる
10万トークンの会話に埋もれた30行のルールは、会話開始直後の30行より確実に注意を引きにくい。「しばらく動かしていたら急に規約を破り始める」の正体はこれです（第2章の"薄まる問題"）。
ファイルが長すぎる
原則①のとおり。500行の CLAUDE.md は、それ自体が遵守率を下げます。

🕶️ クロちゃん：貼り紙、ちゃんと読んでるしんよ？…でも机の上がごちゃごちゃしてくると、端っこの1行はうっかり見落とすしん…。ぜったい守ってほしいやつは、ボクが物理的にできないようにしといてほしいしんよ〜。

4.2. ルールには「強度」の階段がある

守らせたい強さに応じて置き場所を変えます。

弱い ──────────────────────────────────────────────────────► 強い

チャットで口頭  <  CLAUDE.md  <  Skills  <  Hooks  <  権限 deny / サンドボックス
 会話が流れると    ほかの情報に   呼ばれれば   条件が合えば   そもそも実行が
 消える            埋もれうる     必ず効く     必ず発火       不可能

右にいくほど 「モデルの判断」から離れ、「仕組み」になるのがポイントです。CLAUDE.md は思ったより左側にいます。ここが直感とズレやすく、「規約に書いたのに守ってくれない」の原因になります（サンドボックスの実体は第12.7節で説明します。ここでは「権限 deny と並んで一番強い」という位置づけだけ押さえておいてください）。

この階段を踏まえて、自分が運用ルールにしているのがこれです。

同じ失敗が2回起きたら、対処のレベルを一段上げる。

公式が言っているのは「同じミスを2回されたら CLAUDE.md に書く」までですが、それを階段全体に広げたのがこの言い方です。口頭で言っても直らないなら CLAUDE.md へ、それでも直らないなら Hook へ。
「もう一度ちゃんとお願いする」ではなく「置き場所を変える」——これがいちばん効きました。

4.3. どの層に固定するかの判断表

起きているミス・要件	固定する場所
毎回必ず起きてほしい処理	Hooks（決定論的に実行される）
常に知っておくべき短い規約	CLAUDE.md（200行以内）
特定のディレクトリ・ファイル型のときだけ効かせたい規約	`.claude/rules/`（`paths:` 付き）
作業に必要な手順	Skills
そもそも触らせたくない	権限 deny／サンドボックス
調査のたびにコンテキストが溢れる	Subagents

公式ドキュメントも、同じことを「こうなったら、これを追加する」という形で整理しています。

こうなったら	これを追加
同じ規約やコマンドを2回間違えた	`CLAUDE.md` に追記
同じプロンプトを毎回打っている	手動呼び出しの Skill として保存
同じ手順書を3回目チャットに貼った	Skill として固める
Claude が見られない画面からデータをコピーし続けている	MCP サーバーとして接続
脇道タスクの出力で会話が溢れる	Subagent に回す
確認なしで毎回起きてほしい	Hook を書く
2つ目のリポジトリで同じ設定が要る	プラグインとしてパッケージ化

5. 設定のスコープ ─ どこに置くと誰に効くか

ひとことで言うと：チーム全員に守らせたいものはリポジトリへ、自分の手癖はホームへ。

第4章が「どれくらい強く縛るか」という縦軸なら、こちらは 「誰に効かせるか」という横軸です。
この2つが決まれば、以降の各章は「その機能を、どの強度で、誰に効かせるか」を選ぶだけになります。

5.1. 3つのスコープ

ほぼすべての拡張機能は、次の3箇所のどれかに置けます。同じ構成のフォルダを、置く場所だけ変えるのが基本です。

スコープ	置き場所	効く範囲	git
ユーザーグローバル	`~/.claude/`（Windows は `%USERPROFILE%\.claude\`）	自分の全プロジェクト	管理外
プロジェクト（チーム共有）	`<root>/CLAUDE.md`・`<root>/.claude/`・`<root>/.mcp.json`	そのリポジトリの全員	管理対象
個人 × プロジェクト	`<root>/.claude/settings.local.json`・`<root>/CLAUDE.local.md`	自分だけ・このリポジトリのみ	`settings.local.json`＝追記不要（自動で管理対象外）／`CLAUDE.local.md`＝`.gitignore`に自分で追記

~/.claude/                                ← 自分専用（全プロジェクト共通）
<プロジェクトルート>/.claude/              ← チーム共有（git 管理する）
<プロジェクトルート>/.claude/*.local.json  ← 個人 × このプロジェクトだけ

プロジェクト側：リポジトリにコミットしてチームで共有する規約・コマンド
ユーザー側：個人の好み。どのプロジェクトでも効く
ローカル：自分の環境依存の値や、共有したくない実験設定

迷ったら「チームで守らせたい規約はプロジェクト側、自分だけの好みはユーザー側」と覚えれば十分です。

🕶️ クロちゃん：どの壁に貼ってあっても、ボクはぜんぶ読むしんよ。でも「チーム全員の貼り紙」と「キミだけのメモ」を混ぜられると、他の人んとこで動かないしん…。貼る壁は選んでほしいしんよ〜。

5.2. `settings.json` だけは5層ある

settings.json は、上の3つに 「コマンドライン引数」と「組織のポリシー」 が加わって5層になります。下にいくほど優先度が高く、上を上書きします。

優先度	種別	置き場所
低	ユーザー（個人・全プロジェクト）	`~/.claude/settings.json`（Windows: `%USERPROFILE%\.claude\settings.json`）
↓	プロジェクト（チーム共有）	`<root>/.claude/settings.json`（コミットする）
↓	ローカル（個人 × このプロジェクト）	`<root>/.claude/settings.local.json`（自動で `.gitignore` される）
↓	コマンドライン引数	`claude --permission-mode plan` など。そのセッション限り
高	マネージド（組織のポリシー）	管理者が OS 側に配置。誰も上書きできない

個人の好み（モデル・通知）はユーザー、チームで揃えたい規約（deny リスト・Hooks）はプロジェクト、自分の環境依存の値はローカル、という切り分けになります。

パーミッションだけは「上書き」ではなく「マージ」です。 各スコープの deny / ask / allow は合算されたうえで評価されるので、自分のユーザー設定で allow しても、プロジェクトの deny に当たれば拒否されます。チームが張った安全弁は、個人設定では外せない——意図された設計です（詳細は第12章）。

Hooks も同じくマージされます。 ユーザーグローバルの PostToolUse とプロジェクトの PostToolUse は、どちらも実行されます（第10章）。

5.3. 実例 ─ 「使うモデルをチームで揃えたい」はどこまで効くか

この5層の使い分けが実務でよく効いてくる例が、モデルとエフォート（どれだけ考えさせるか）の統制です。「コスト管理のために、チームでは Sonnet を既定にしたい」といった要望があるとします。ここでどの層に書くかで、"揃う"の意味がまったく変わります。

書く場所	効き方	ユーザーが変更できるか
`.claude/settings.json` の `model` キー	チーム全員の初期値が揃う	できる（`/model` で切り替え可能）
マネージド設定（組織管理者が OS 側に配置）	上書き不可の設定として配られる	できない
組織の管理コンソール（Enterprise）	サーバー側で強制。使えるモデル・モデルごとの最大エフォート・既定モデルをロール単位で縛れる	できない

リポジトリの settings.json に書いた model は、あくまで初期値 にすぎません。「チームの規約として Sonnet に固定したつもりが、各自が /model で Opus に上げていた」——これは設定ミスではなく、そういう仕様です。

本当に「変更不可」にしたいなら、現時点ではEnterprise の管理コンソールでロールを切るしかありません（組織全体でモデルを無効化すると Owner 含む全員に適用されます）。逆に言えば、Pro / Max の個人利用や小さなチームでは、強制ではなく初期値を揃えるところまでが現実的なゴールです。

Hooks で疑似的に縛ることは一応できます。 第10章で扱う PreToolUse フックを使えば「特定条件でブロックする」独自ロジックは書けます。ただしこれは公式の強制機能ではなく、あくまで自作の門番です。組織として保証したいならコンソール、チームの手癖を揃えたいなら settings.json と割り切るのが健全だと思います。

縦軸（強度）と横軸（スコープ）が揃いました。ここからようやく、6つの拡張機能を1つずつ詳しく見ていきます。

6. CLAUDE.md ─ 常に効く「プロジェクトの前提・規約」

ひとことで言うと：毎回自動で読まれる"憲法"。ただし短く、地図に徹する。

6.1. CLAUDE.md とは

会話の開始時に 自動で読み込まれ、全応答に適用 される指示書です。「このプロジェクトではこう書いてね」という前提をここに置いておくと、毎回説明しなくても守ってくれます。

6.2. 置き場所と読み込み階層

~/.claude/CLAUDE.md        ← ① 個人のグローバル設定（全プロジェクト共通）
<root>/../CLAUDE.md        ← 親フォルダの共通設定（起動時に読み込み・下記参照）
<root>/CLAUDE.md           ← ② プロジェクト規約（最重要・git 管理）
<root>/CLAUDE.local.md     ← ③ 個人×このプロジェクトのみ（.gitignore 推奨）
<root>/src/CLAUDE.md       ← サブディレクトリ単位の追加規約（オンデマンド読み込み）

読み込みの挙動は「上方向」と「下方向」で異なります。

実線（太矢印）が「起動時に必ず全文読み込み」、点線が「触ったときだけの遅延ロード」です。

親フォルダの CLAUDE.md は起動時に"遡って"全部読まれる（上方向）
起動時、Claude Code はカレントディレクトリから親フォルダを順に遡り、途中で見つけた CLAUDE.md / CLAUDE.local.md を すべて全文読み込みます（リポジトリの境界では止まりません）。
コンテキストにはルート側 → カレント側の順で並ぶため、起動フォルダに近いファイルほど後に読まれます。
複数プロジェクトを束ねる親フォルダ（例: Documents/work/）に共通ルールの CLAUDE.md を置けば、配下の全プロジェクトにまとめて効かせられます。

サブディレクトリの CLAUDE.md は"遅延ロード"される（下方向）
ルート直下の CLAUDE.md はセッション開始時に必ず読まれますが、サブディレクトリのものは そのフォルダのファイルを触ったときだけ 読み込まれます（原則②）。ディレクトリ固有の細かい規約は、ルートに書かずサブディレクトリに置くとコンテキストの節約になります。

🕶️ クロちゃん：起動した部屋から上の階の貼り紙はぜんぶ読んでから仕事はじめるしんよ。下の部屋のメモは、その部屋に入ったときに読むから大丈夫しん。「ちゃんと読んだ？」って心配なら /context でボクの机を見てほしいしんよ〜。

読み込みが思ったとおりに効いていないときは、確認と除外の2つを押さえておくと早く解決できます。

実際にどのファイルが読み込まれたかは /context で確認できます（/memory はメモリファイルの場所一覧と編集用）。「CLAUDE.md が効いていない？」と感じたら、まず /context に載っているかを見るのが最短です。
逆に「親フォルダの CLAUDE.md をこのプロジェクトでは読みたくない」場合は、settings の claudeMdExcludes にパスやグロブを指定して除外できます。モノレポで他チームの CLAUDE.md まで拾ってしまうときにも有効です。

{
  "claudeMdExcludes": ["**/work/CLAUDE.md"]
}

CLAUDE.mdにも、第5章・第7章と同じ エンタープライズ管理ポリシー層 があります。IT/DevOpsが配布する CLAUDE.md（macOS: /Library/Application Support/ClaudeCode/CLAUDE.md、Linux/WSL: /etc/claude-code/CLAUDE.md、Windows: C:\Program Files\ClaudeCode\CLAUDE.md）は個々の設定で除外できず、ユーザー・プロジェクトのCLAUDE.mdより先に読み込まれます。ファイルを配布する代わりに、managed settingsの claudeMd キーへ直接本文を書く方法もあります。

6.3. 記載例

qiita-digest の CLAUDE.md は 57 行で、中身は 「アーキテクチャ原則」と「共通規約」だけです。まず前半、そのプロジェクトで設計判断を下すときの拠り所になる原則です。

「エラーはキャッチしない」「ステート間で運ぶのは S3 キーと件数だけ」——コードを読んでも分からない、そのプロジェクト固有の意思決定が並んでいます。逆にここに「読みやすいコードを書く」のような一般論は書きません（第6.6節の判断基準）。

後半は、毎回説明したくない環境と作法です。

リージョン・Python のバージョン・命名規則・使うツール（uv）といった、推測できないし間違えると手戻りする情報に絞ってあります。「AWS の仕様・制限値を記憶で書かない」の行に "実際に「Redrive は 24 時間以内」と誤記したことがある" と実例が添えてあるのは、実際にやらかしたので規約に昇格させた痕跡です（第4章の鉄則）。禁止だけを書くより、何が起きたかを1行添えておくほうが守られる気がしています。

そして最終行が、詳細ルールを .claude/rules/ に逃がしているという宣言になっています。これが次節以降の話につながります。

6.4. `@import` で分割管理する

CLAUDE.md が膨らんできたとき、まず思いつくのが分割です。@ で別ファイルを取り込めます。

## 詳細ルールは以下を参照すること
@docs/rules/stepfunctions.md
@docs/rules/lambda.md
@docs/rules/eventbridge.md

Step Functions・Lambda・EventBridge それぞれの詳細ルールを別ファイルに分け、本体は「原則」だけに絞る。「Step Functions を触るときの細かい作法」を stepfunctions.md にまとめておけるので、レビューも差分も追いやすくなります。
相対パスは 「そのファイルから見た相対」 で解決されます（起動ディレクトリ基準ではありません）。
@import は入れ子にできますが 最大4ホップまで。@a.md が @b.md を、@b.md が @c.md を…と辿れるのは4段階目までで、5段階目以降は展開されません。この上限のおかげで、@a.md と @b.md が互いを取り込み合うような循環を組んでしまっても、無限ループにはならず自動的に打ち切られます。
 はコンテキスト注入前に除去されるので、トークンを消費せずにメモを残せます。

@import してもコンテキストは減りません。 取り込まれたファイルは、起動時に本体と一緒に全文が読み込まれます。つまり CLAUDE.md を 400 行から 100 行＋@import 3本にしても、モデルが毎リクエスト受け取る量は変わりません。得られるのは管理のしやすさだけ、と割り切ってください（原則①）。

「読ませる量そのものを減らしたい」なら、逃がす先は次の2つです。

.claude/rules/ の paths: 付きルール（次節）… 対象ファイルを読んだときだけ載る
Skills（第7章）… 起動時は名前と説明文だけ。本文は使ったときに載る

先ほど見た qiita-digest が @import を1本も使わず、詳細ルールを丸ごと .claude/rules/ に置いているのはこの理由からです。分けるだけなら @import、読ませる量を減らしたいなら次節、という住み分けになります。

6.5. パスベースルール（`.claude/rules/`）

「特定のファイルを触るときだけ効かせたいルール」は、本体ではなく .claude/rules/ に切り出せます。frontmatter でパターンを指定すると、該当ファイル操作時のみ発火します（これも遅延ロード）。

qiita-digest の Lambda 用ルールは、こう始まっています。冒頭 5 行の frontmatter が本体です。

このファイルは 85 行あって「handler.py には処理フローだけ書く」「相対 import は使わない」といった細かい作法がびっしり書いてありますが、Claude がそれを読むのは src/ か tests/ の .py を触ったときだけです。ドキュメントを書いているだけのセッションでは 1 トークンも消費しません。

paths は ルールファイルごとの frontmatter に書きます。"src/**/*.{ts,tsx}" のようにブレース展開や複数パターンも指定でき、発火するのは Claude がマッチするファイルを読んだときです。.md は再帰的に発見されるので rules/frontend/・rules/backend/ と切ってもかまいません。個人用は ~/.claude/rules/ に置けば全プロジェクトに効きます（同名ならプロジェクト側が優先）。

6.5.1. `paths:` あり／なしで読み込みタイミングが変わる

paths: を省略すると、そのルールファイルは CLAUDE.md と同じ扱いになります——起動時に全文がコンテキストへ注入され、遅延ロードの恩恵はありません。paths: を書いて初めて「対象ファイルを触ったときだけ」の遅延ロードに切り替わります。

	`paths:` あり	`paths:` なし
読み込み	対象ファイルを読んだときだけ	起動時に全文（`CLAUDE.md` と同じ）
コンテキスト	節約になる	変わらない
圧縮（コンパクション）後	消える（対象ファイルを再度読むまで）	ディスクから再注入される

つまり paths: は 「軽いが、長いセッションでは静かに落ちることがある」。絶対に破られたくない規約には、あえて paths: を付けないという判断もあります。

もうひとつ、paths: を付けない理由があります。qiita-digest では9本のルールのうち deployment.md だけが常時ロードで、その理由がファイルの冒頭に書いてあります。

デプロイ作業は aws cloudformation deploy や sam deploy を打つのが中心で、特定のファイルを編集しない。だから paths: でどんなパターンを書いても発火してくれません。「paths: を付けられるか」は、そのルールが必要になる場面がファイル操作として現れるかで決まります。

ちなみに、こういう 「なぜこの選択をしたか」をファイル自身に1行書いておくのは地味に効きます。半年後の自分も、他のメンバーも、paths: の付け忘れだと思って"直して"しまわずに済みます。

なお paths: なしでもファイルを分ける価値はあります。1トピック1ファイルにしておけば、あとから paths: を1行足すだけでその塊を遅延ロードへ移せるからです。500行の CLAUDE.md の「この節だけ遅延ロード」はできません。

6.5.2. 共通ルールを1箇所で保守する（symlink）

.claude/rules/ は symlink をたどれます（循環も検出されます）。共有ルールの正本をプロジェクトの外に置き、各リポジトリからリンクすれば、更新は正本だけで済みます。ディレクトリ単位でも1ファイル単位でも張れます。

ln -s ~/company-claude-rules .claude/rules/shared           # ディレクトリごと
ln -s ~/company-standards/security.md .claude/rules/security.md

ただし プラグインが持てる構成要素の一覧に rules/ は入っていません（第14章）。複数リポジトリへ「配る」ところまでやりたいなら、ルールではなく Skill に仕立ててプラグインに載せるのが公式のルートになります。

育てすぎ注意。
CLAUDE.md が 500 行に膨らんだら、それは「遵守率が下がっているサイン」です（原則①）。詳細を .claude/rules/（paths: 付き）や Skills に逃がしてスリムに保ちましょう——@import での分割は見通しは良くなりますが、読み込まれる量は変わりません。
また、CLAUDE.mdは/init コマンドで既存コードから雛形を自動生成することもできます。

6.6. 何を書き、何を書かないか ─ 剪定の判断基準

とはいえ「短くしろ」と言われても、どの行を削るか迷います。判断基準はひとつだけで十分です。

各行について「これを消したら、Claude はミスをするか？」と自問する。しないなら削る。

線引きを具体化するとこうなります。

✅ 入れる	❌ 入れない
Claude が推測できない Bash コマンド	コードを読めば分かること
デフォルトと違うコードスタイル規則	Claude が既に知っている標準的な言語慣習
テスト手順・使うテストランナー	詳細な API 仕様（リンクで済ませる）
リポジトリの作法（ブランチ命名・PR 規約）	よく変わる情報
環境の癖（必須の環境変数など）	「きれいなコードを書く」的な自明な話

うまくいっていないときの切り分けも、わりと機械的にできます。

ルールを書いているのに従わない → ファイルが長すぎて、そのルールが埋もれている（→ 削る・.claude/rules/ に逃がす）
CLAUDE.md に書いてあることを Claude が質問してくる → 表現が曖昧（→ 書き直す）
削っても挙動が変わらない → もともと不要だった（→ そのまま消す）

CLAUDE.md はコードと同じように扱うのが正解です。問題が起きたらレビューし、定期的に剪定し、変更したら「Claude の挙動が実際に変わったか」で検証する。書きっぱなしにすると、静かに効かなくなっていきます。

🕶️ クロちゃん：「たまにしか使わない知識」まで貼り紙にされると、毎朝それ全部読まされるしんよ…。ときどきでいいやつは Skill にしてほしいしん。ボク、必要なときはちゃんと自分で取りにいく子だしんよ〜。

7. Skills ─ 呼び出して使う「作業手順の型」

ひとことで言うと：使うときだけ机に載る"手順書＋専門知識"のパッケージ。

7.1. Skills とは

正式名称は Agent Skills（claude.ai・Claude API・Claude Code に共通する仕組みで、Claude Code のドキュメント内では単に「Skills」と呼ばれます）。特定タスク用の 手順書＋専門知識のパッケージ です。/skill-name で明示的に呼ぶか、description に合致すると自動的に使われます。CLAUDE.md と違って 常時ロードされない のがポイント（原則②の遅延ロード）。

🕶️ クロちゃん：毎回この長い手順を暗記しとくの、正直しんどいしんよ…。使うときだけ「はいコレ」って渡してくれる型、ボク大好きしんよ〜。

7.2. 置き場所

<root>/.claude/skills/<skill-name>/SKILL.md   ← 本体（必須）
<root>/.claude/skills/<skill-name>/           ← 補助ファイルも同居可
~/.claude/skills/<skill-name>/SKILL.md        ← 個人用

保存場所は全部で4レベルあり、どこに置くかで「誰が使えるか」が決まります（第5章のスコープが、Skills ではこう現れます）。

レベル	パス	適用範囲
エンタープライズ	管理設定の配置場所に準ずる	組織の全ユーザー
個人	`~/.claude/skills/<name>/SKILL.md`	自分の全プロジェクト
プロジェクト	`.claude/skills/<name>/SKILL.md`	このプロジェクトのみ
プラグイン	`<plugin>/skills/<name>/SKILL.md`	プラグインが有効な場所

同名のスキルが複数レベルにあるときは、エンタープライズ＞個人＞プロジェクト の順で上書きされます。「個人設定がプロジェクト設定に勝つ」ので、第5章のパーミッション（マージされて deny が勝つ）とは向きが逆です。プラグインのスキルは plugin-name:skill-name という名前空間を持つので競合しません。

7.3. 記載例

「新しいサービスのディレクトリ一式を、既存と同じ形で作る」は毎回同じ作業なので、Skill に固める典型例です。qiita-digest の scaffold スキルがそれで、中身より frontmatter のほうが重要です。

注目してほしいのは description の書き方です。「雛形を作る」だけでなく、

どういう言い方をされたら起動するか（「箱だけ作って」「ファイル構成だけ用意して」）
どういうときは起動しないか（ロジックまで欲しいなら implement スキルへ）

の両方が書いてあります。起動条件と、隣のスキルとの境界線。ここが曖昧だと、似たスキルが2つあるときに毎回どちらが出てくるか分からなくなります。

本文（残り 36 行）には「src/<service>/ と tests/<service>/ をミラーさせる」といった具体的なファイル構成が並びますが、これが読み込まれるのは実際に scaffold を使うときだけです。起動時のコンテキストに載るのは、上の name と description の2行分だけで済みます。

7.4. frontmatter で挙動を細かく制御する

description 以外にも、動作を制御するオプションがあります。

キー	役割
`name`	スキル識別子
`description`	いつ自動起動するかの生命線。トリガー条件を具体的に書く
`context: fork`	独立したサブエージェントとして実行し、メイン会話を汚さない
`model`	使用モデルを指定（軽いタスクは軽量モデルでコスト最適化）
`allowed-tools`	そのスキルを呼んだターンだけ、許可プロンプトなしで使えるツール（制限ではなく事前承認。次のメッセージを送ると解除される）
`disallowed-tools`	スキルが有効な間、Claude の手元から取り上げるツール（制限したいときはこちら）
`user-invocable`	`/` メニューへの表示・非表示
`disable-model-invocation`	`true` で「明示呼び出し時のみ」実行（自動起動を止める）

allowed-tools は名前に反して「制限」ではありません。 公式ドキュメントは "It does not restrict which tools are available: every tool remains callable" と明言していて、書いていないツールも普通に呼べます。役割は「ここに挙げたツールは、このスキルを呼んだターンのあいだ許可プロンプトを出さずに使ってよい」という事前承認——つまり権限を絞るどころか広げるキーです。
allowed-tools: Read, Grep と書いて「これで読み取り専用になった」と思うと逆効果になるので、取り上げたいときは disallowed-tools を使ってください。

その disallowed-tools の実例も見ておきます。qiita-digest の review スキルは、編集系のツールを落としてあります。

レビューが勝手にコードを直し始めないための歯止めです。ここで大事なのは、7本あるスキルのうちツール制限を持っているのはこれだけという点。実装・調査系のスキルは必要なツールが広く、先回りして絞ると後から壊れます。制限すること自体に意味があるときだけ書く、が実用的な線引きだと感じています。

disable-model-invocation は「コンテキスト節約」のためではありません。
用途は 副作用のある操作の実行タイミングを人間が握ることです。/deploy や /commit に付けておけば、Claude が「コードが完成したっぽいからデプロイするか」と判断してしまう事故を防げます。逆に user-invocable: false は「Claude だけが使う背景知識」向け（人間が / から呼んでも意味がないもの）。

7.5. Skills を使う目的

手順が長い・参照資料が多いタスクを「型」として固定したいときに使う。
description が重要。
ここに書いたトリガー条件で「いつ自動起動するか」が決まります。曖昧だと発火しません。
references/ などの補助ファイルを同フォルダに置き、SKILL.md から参照させられます。
本文は簡潔に、大事なことは上に。
一度ロードされたスキルの本文は、その後のターンにもコンテキストに残ります。ただしコンパクションを挟むと無傷では戻りません——公式によると、再注入されるのはスキル1本あたり 5,000 トークン・合計 25,000 トークンまでで、超えたぶんは古いスキルから捨てられます。しかも切り詰めはファイルの先頭を残す方式なので、長いスキルの末尾に書いた注意書きは静かに落ちます。ずっと効かせたい指示ほど SKILL.md の上のほうに置く、が実務的な結論です。

7.6. 便利な Skills を探す ─ マーケットプレースの実例

自作だけでなく、公開されている Skills を入れて試すこともできます（マーケットプレースの仕組み自体は第14.2節で扱います）。
ここでは代表的な3つを紹介します。

Skill / コレクション	提供元	何をするか	導入
skill-creator	Anthropic公式（`claude-plugins-official`）	Skill を作る・評価する・改善するためのメタSkill。Create/Eval/Improve/Benchmark の4モードを持つ	`/plugin install skill-creator@claude-plugins-official`
superpowers	Jesse Vincent氏・Prime Radiant（`obra/superpowers`）	ブレインストーミング・体系的デバッグ・TDD・並列サブエージェント委任などの開発方法論を14個のSkillに体系化。公式マーケットプレースにも収録されている	`/plugin install superpowers@claude-plugins-official`
everything-claude-code（ECC）	`affaan-m/everything-claude-code`（非公式・第三者製）	67のSubagentと281のSkillsを束ねた大規模コレクション。メモリ共有・継続学習・セキュリティスキャンまで含む「エージェントハーネスの最適化」志向	`/plugin marketplace add https://github.com/affaan-m/ECC` → `/plugin install ecc@ecc`

8. Subagents ─ 別コンテキストに切り出す「専門エージェント」

ひとことで言うと：独立した机で働く子分。調査を任せてメインの机を汚さない。

8.1. Subagents とは

独立したコンテキストウィンドウで動く子エージェントです。専用のシステムプロンプト・ツールアクセスを持ち、メインの会話を汚さずに調査や特定作業を任せられます（原則③のコンテキスト隔離）。

8.2. 置き場所と記載例

<root>/.claude/agents/<name>.md   ← プロジェクト用
~/.claude/agents/<name>.md        ← 個人用

qiita-digest に入っているコードレビュー用のサブエージェントです。frontmatter に、このエージェントの性格がすべて出ています。

3つのキーが効いています。

tools: Read, Grep, Glob, Bash … 使えるツールの制限（省略すると全ツール）。Edit / Write が入っていないので、そもそも直せません。Bash があるのは git diff で変更を特定するためです。
permissionMode: plan … 第12.5節の読み取り専用モード。tools と二重に効かせています。
model: inherit … メイン会話のモデルを引き継ぎます。ここを sonnet などに変えれば、レビューだけ軽いモデルでコスト最適化できます（コメント行にその旨を書いてあります）。

本文（残り 30 行）には「最初に CLAUDE.md と .claude/rules/ を読む」「指摘には規約の該当箇所を根拠として添える」といったレビュー観点が並びます。サブエージェントは会話履歴を引き継がないので、「何を根拠に判断するか」を毎回この定義ファイルから読み直すことになります。だから判断基準を全部ここに書き切る必要があります。

さらに skills: で特定の Skill をプリロード できます。「隔離された作業場（Subagent）× そこに持ち込む専門知識（Skill）」 という組み合わせで、第7章と第8章が噛み合う場所です。

---
name: security-reviewer
description: セキュリティ脆弱性のレビュー
tools: Read, Grep, Glob
skills: [security-checklist]   # ← このスキルを最初から持たせる
model: opus
---

チェックリストを Skill として1箇所に置き、それを持った Subagent を複数走らせる——という形にすると、知識の管理は1箇所のまま、実行だけを並列化できます。

逆向きの噛み合わせ方もあります。Skill 側から Subagent を呼ぶパターンで、第7.4節で見た review スキルの中身がまさにこれです。

「レビューして」と言われたときに code-reviewer へ直接投げず、わざわざスキルを1枚挟んでいる理由が冒頭2行に書いてあります。サブエージェントは会話履歴を引き継がないので、渡すプロンプトの品質がそのまま結果の品質になる。「対象範囲はどこか」「関連する設計書はどれか」をスキル側で調べてから委任する、という前処理を型にしているわけです。

サブエージェントを使い始めると「思ったより雑な結果が返ってくる」ことがありますが、エージェントの定義より、渡すプロンプトのほうが原因なことが多い印象です。

8.3. 組み込みサブエージェント

自分で定義しなくても、標準で用意されています。

名前	役割
`Explore`	読み取り専用（Write / Edit は不可）。コードベースの探索・検索特化。モデルはメイン会話から継承する（Claude API では Opus が上限）
`Plan`	読み取り専用。実装計画の設計特化
`general-purpose`	全ツール使用可能な汎用

Explore と Plan の2つだけは、探索を速く安く保つために CLAUDE.md と git status を読み込みません（自作を含む他のサブエージェントは読み込みます）。この2つにも必ず効かせたい前提があるなら、委任するときのプロンプトに書き直して渡します。

8.4. 委任の鉄則 ─「収集は委任、統合は自前」

調査・情報収集はサブエージェントに任せてよい。一方、複数の結果を比較して最終判断を下す工程は、全体を把握しているメイン会話が行う必要がある点に注意です。
サブエージェントは メイン会話の履歴を引き継がない（CLAUDE.md と git status は読み込みますが、それ以外に持っているのは起動時に渡されたプロンプトだけ）ため、メイン会話が溜めてきた以下を引き継げないからです。判断そのものを丸投げすると、目標のズレや情報の欠落を招きます。

暗黙の制約
ユーザー意図の微妙なニュアンス
すでに却下したアプローチ

🕶️ クロちゃん：子分たちは今日はじめて来た子だしんよ。「調べてきて」は任せられるけど、最後のジャッジはボク（全部わかってる親分）がやらなきゃダメしんよ。じゃないと、あさっての方向いっちゃうしん〜。

サブエージェントの frontmatter に isolation: worktree を付けると 専用の git worktree で動作し、複数エージェントの同時編集による衝突を防げます（並列作業向け）。
各エージェントに独立コピーで作業させて、最後にまとめるのが正解です。

9. Slash Commands ─ 定型プロンプトを「/コマンド」に登録

ひとことで言うと：よく打つプロンプトのショートカット。

9.1. Slash Commands とは

よく使うプロンプトをコマンド化する仕組みです。Skills と似ていますが、より 軽量な定型文の呼び出し 向き。

現在の公式では、カスタムコマンドは Skills に統合されています。 .claude/commands/deploy.md と .claude/skills/deploy/SKILL.md は、どちらも /deploy を作り同じように動きます。既存の .claude/commands/ はそのまま動くので本章の内容は有効ですが、位置づけとしては 「1ファイルで書ける軽量な Skill」 と捉えるのが実態に近く、公式の拡張機能一覧にも独立項目としては載っていません。新しく作るなら Skills 側（フォルダ＋SKILL.md）に寄せておくと、補助ファイル・context: fork・disable-model-invocation などをあとから足せます。

9.2. 置き場所と記載例

<root>/.claude/commands/<name>.md          ← /name で呼ぶ
<root>/.claude/commands/frontend/comp.md   ← /frontend:comp（サブフォルダで名前空間）
~/.claude/commands/<name>.md               ← 個人用

前章までと違い、ここは記事のために書いたサンプルです（qiita-digest は上の注記の方針どおり、コマンドを作らず Skills に寄せているため）。失敗した Step Functions 実行を調べるコマンドを例にします。

.claude/commands/redrive.md

---
description: 失敗した Step Functions 実行の原因を調べ、redrive 方針を立てる
argument-hint: <実行ARN>
---

Step Functions の実行 $ARGUMENTS が失敗しました。以下を行ってください。

1. `aws stepfunctions describe-execution --execution-arn $ARGUMENTS` で状態を確認
2. `aws stepfunctions get-execution-history --execution-arn $ARGUMENTS` で失敗ステートと
   エラー分類（カスタム例外名）・Cause を特定
3. データ／権限どちらの問題かを切り分け、redrive すべきか・その前に直すべきことを箇条書きで提案

呼び出し：/redrive arn:aws:states:...:execution:... → $ARGUMENTS が実行ARNに置換されます。
$1 $2 で個別引数、! 始まりでシェル実行、@path でファイル参照も可能。

9.3. Skills との使い分け

	Slash Command	Skill
用途	短い定型プロンプト	手順・知識の大きめのパッケージ
自動起動	基本しない（手動）	description に合致で自動起動しうる
補助ファイル	単一 .md	フォルダごと（references 等）

9.4. 入力欄の3つの接頭辞

Slash Command の / は、入力欄の「モード切り替え」の1つです。全部で3つあり、揃えて覚えておくと地味に効きます。

接頭辞	何が起きるか
`/`	コマンド・Skill を呼ぶ
`!`	シェルコマンドを直接実行する（Claude を通さない）
`@`	ファイルパスを補完して、参照に追加する

特に ! は便利です。! npm test のように打つと、Claude の判断も許可プロンプトも挟まずにその場で実行され、コマンドと出力がそのまま会話に入ります。

! git status
! uv run pytest

肝は 出力がコンテキストに載る ことです。「自分でテストを流して、その結果を見て考えてもらう」が1手で済みます。新しめのバージョンでは出力が入った時点で Claude が自動的に応答するので、! npm test と打つだけで失敗の解説まで返ってきます（黙って追加するだけにしたいなら、設定で respondToBashCommands を false に）。

自分でコマンドを打ちたいが、結果は Claude に見ておいてほしい——という場面は思ったより多いので、覚えておきたい接頭辞です。

9.5. よく使うスラッシュコマンド

ここまでで組み込みコマンドが本文のあちこちに登場しました。迷ったときに引ける早見表としてまとめておきます。

コマンド	何をするか	詳しくは
`/context`	現在のコンテキストの内訳を確認する	第6.2節
`/compact`	会話を要約して圧縮する	第2.3節
`/clear`	会話をリセットする	第2.3節
`/memory`	メモリファイルの場所一覧・編集	第13.2節
`/model`	使用モデルを切り替える	第5.3節
`/permissions`	パーミッションルールを管理する	第12章
`/mcp`	MCP の接続状態確認・認可	第11章
`/plugin`	プラグインの検索・インストール・管理	第14.3節
`/sandbox`	サンドボックスのモード・設定を確認する	第12.7節
`/init`	既存コードから `CLAUDE.md` の雛形を生成する	第6.5節
`/rewind`	会話・ファイル変更をチェックポイントまで巻き戻す	第13.1節
`/hooks`	Hooks 設定を確認・編集する	第10章
`/usage`	プランの利用量・上限を確認する	─

/ はコマンドと Skill の入り口、!・@ は第9.4節の接頭辞という役割分担でしたが、この表の大半は組み込みの / コマンドです。カスタムコマンド（第9.2節）や Skills とは別に、まずここから触ってみると土地勘がつかめます。

10. Hooks ─ イベントで自動実行する「品質ゲート」

ひとことで言うと：「〜したら必ず〜する」を保証する自動化。

10.1. Hooks とは

ツール実行の前後などで、必ず自動で何かを実行する仕組みです。
確率論的ではなく、決定論的に「X したら必ず Y して」という自動化を実現します。

🕶️ クロちゃん：正直ボク、けっこう気分屋だしんよ…。「毎回わすれず〇〇してね」って口約束、守れる自信ないしん。仕組みで強制してくれたほうが、ホッとするしんよ。

10.2. Hooks が要る理由 ─ 階段の「必ず発火する」段

第4章の強度階層を思い出してください。Hooks はその 右から2番目、「条件が合えば必ず発火する」段にあたります。

チャットで口頭  <  CLAUDE.md  <  Skills  <  【 Hooks 】  <  権限 deny / サンドボックス
                                              ↑ ここ

CLAUDE.md に「編集したら必ずフォーマットして」と書いても、それはお願いです。守られる確率は高くても 100% ではありません。　　
Hook を実行するのは Claude Code 本体なので、モデルが忘れることが原理的にありえない。ここが決定的な差です。

しかも第3章の表のとおり、Hooks のコンテキストコストはゼロ。「規約を1行増やすと CLAUDE.md が重くなる」というトレードオフが、そもそも発生しません。CLAUDE.md に書いたルールのうち 機械的に判定できるものを Hook に移すほど、全体が軽くなって遵守率も上がる——という一石二鳥が起きます。

同じ失敗が2回起きたら、対処のレベルを一段上げる。第4章の鉄則が実務でいちばん効くのが、この移し替えです。

10.3. 置き場所と記載例

Hooks は settings.json の中に定義します。

<root>/.claude/settings.json         ← チーム共有（コミットする）
<root>/.claude/settings.local.json   ← 個人 × このプロジェクト（git 管理外）
~/.claude/settings.json              ← ユーザーグローバル（自分の全プロジェクト）

Hooks はスコープ間で「マージ」されます（上書きではありません）。 ユーザーグローバルの PostToolUse とプロジェクトの PostToolUse は、どちらも実行されます。
「チーム共通の lint はリポジトリに、自分だけの完了通知はホームに」と重ねられるのが利点ですが、裏を返すと同じ整形処理を両方に置くと2回走ります（設定ファイル全体の優先順位は第5章を参照）。

qiita-digest の settings.json は、中身が Hooks の定義だけです。ファイルを編集する前と後に、それぞれ1本ずつ走らせています。

PreToolUse … 認証情報ファイル（.env / *.pem）への書き込みをブロックする（第10.5節で中身を見ます）
PostToolUse … 編集した .py に ruff check をかけ、指摘があればその場で直させる

どちらも command にワンライナーを書かず、.claude/hooks/ 配下の Python スクリプトを呼んでいます。ここは好みが分かれるところですが、公式ドキュメントによく出てくる jq -r '.tool_input.file_path' | xargs -r ruff format のような書き方は、Windows だと jq が入っていないことが多く、そのまま動きません。条件分岐が2つ以上入るとワンライナーの可読性も落ちるので、最初からスクリプトに切り出すほうが結局は楽でした。

JSON 内の各フィールドの意味は次のとおりです。

フィールド	必須	意味
`matcher`	-	発火対象の絞り込み（次節で詳説）
`hooks[].type`	✅	実行方式。`command`（シェルコマンド）のほか `http`・`mcp_tool`・`prompt`・`agent` もありますが、まずは `command` を覚えれば十分です
`hooks[].command`	`type: command` 時必須	実行するコマンド。`args` を指定しなければシェル経由（`&&`・パイプ・変数展開が効く）、`args` を指定すると実行ファイルを直接起動（シェルを介さないぶん特殊文字の解釈に悩まされません）
`hooks[].timeout`	-	タイムアウト秒数。既定 600 秒（`command`/`http`/`mcp_tool` の場合）
`hooks[].if`	-	パーミッションルール構文でさらに絞り込む。例: `"if": "Bash(rm *)"` なら `rm` を含むコマンドのときだけ発火

確率的な忘却ではなく、必ず実行されるのが Hook の価値です。同じ要領で、ステートマシン定義（*.asl.json）を編集したら JSON の構文チェックを走らせる、といった「規約の自動ゲート」も組めます。

フックへの入力は「標準入力の JSON」です。 session_id・cwd・hook_event_name（イベント名）・tool_name（ツール名）・tool_input（ツールの引数）が共通で流れてきます（PostToolUse ではさらに実行結果の tool_response も付きます）。編集されたファイルのパスは、シェルなら jq -r '.tool_input.file_path'、Python なら json.load(sys.stdin) から取り出します（次々節の実例を参照）。
フックが受け取れる環境変数は $CLAUDE_PROJECT_DIR・$CLAUDE_PLUGIN_ROOT・$CLAUDE_EFFORT などです。上の settings.json が "$CLAUDE_PROJECT_DIR"/.claude/hooks/... とスクリプトを呼んでいるのは、リポジトリの clone 先が変わっても壊れないようにするためです。

10.4. 主なイベント（matcher で対象を絞る）

イベント	タイミング	代表的な用途
`PreToolUse`	ツール実行前（ブロック可能）	危険なコマンドを拒否。exit code 2 で止め、stderr が AI にフィードバックされる
`PostToolUse`	ツール実行後	フォーマッタ・型チェック・lint の自動実行
`UserPromptSubmit`	ユーザー送信時	定型の前処理・コンテキスト注入
`Stop` / `SubagentStop`	応答終了時（ブロック可能）	必須の検証ステップを強制
`SessionStart`	セッション開始時	環境情報の読み込み

matcher の書き方は主に4パターンです。

書き方	例	挙動
文字列そのまま	`"Bash"`	完全一致
`\|`（または `,`）区切り	`"Edit\|Write"`	いずれかに一致（OR）
上記以外を含む文字列	`"^Notebook"`・`"mcp__.__write."`	正規表現として評価（部分一致。完全一致させたいなら `^...$` で囲む）
`"*"`・`""`・省略	-	絞り込みなし（常にマッチ）

MCP 経由のツールは mcp__<サーバー名>__<ツール名> という名前になるので、"mcp__memory__.*"（特定サーバーの全ツール）のような指定もできます。

注意したいのは、matcher が何を照合するかはイベントごとに違うという点です。PreToolUse / PostToolUse はツール名で絞り込みますが、SessionStart は起動理由（startup・resume・clear・compact・fork）、SubagentStart / SubagentStop はエージェント種別（general-purpose・Explore・Plan・カスタムサブエージェント名）で絞り込みます。さらに Stop と UserPromptSubmit はそもそも matcher を持たず、条件に関わらず毎回発火します（上の表では Stop と SubagentStop を1行にまとめていますが、matcher の有無という点では挙動が異なります）。

設定変更は update-config スキルに任せると安全です。単純なテーマ・モデル変更なら /config コマンドで十分。

10.5. 実例 ─ 外部スクリプトで保護ファイルの編集をブロックする

前節で settings.json から呼んでいた2本のスクリプトの中身を見てみます。まず PreToolUse 側、認証情報ファイルへの書き込みを止めるフックです。

肝は sys.exit(2) です。第10.4節の表にある「PreToolUse は exit code 2 で止め、stderr が AI にフィードバックされる」がまさにこれで、ブロック: ... は認証情報ファイルのため編集禁止。 という stderr の内容がそのまま Claude に伝わります。却下されただけでなく理由も分かるので、Claude は「では .env.example のほうに書きます」と別の手段に切り替えられます（sys.exit(0) なら素通り）。

判定ロジックが地味に効いています。.env だけでなく .env.local や .env.production も止める一方で、.env.example は通す。共有前提の雛形まで止めてしまうと、今度は正当な作業が邪魔されて「フックを一時的に外す」ことになりがちです。

もう1本、PostToolUse 側の ruff フックにも設計上の工夫があります。

対象が .py でなければ素通りし、uv が入っていない環境では何もせず exit 0 で静かに抜けます。ここを「ツールが無いからエラー」にしてしまうと、そのリポジトリをクローンした人は編集のたびに無関係なエラーを浴びることになります。しかも PostToolUse の exit 2 は stderr が Claude へ返るので、Claude が存在しない問題を直そうとし始めます。

フックはモデルの外側で必ず走るぶん、壊れたときにモデルの判断で回避してもらえません。「無関係なイベントでは黙って通す・外部ツールが無ければスキップする」は、フックを書くときの基本作法だと思っておくとよさそうです。

サンプルがシェルスクリプトではなく Python なのは、Windows で開発しているからです。公式ドキュメントの例は jq と bash 前提のものが多いのですが、標準ライブラリだけの Python スクリプトにしておけば、python <path> で OS を選ばずに呼べます（chmod +x も要りません）。

11. MCP ─ 外部ツール連携（Model Context Protocol）

ひとことで言うと：DB・API・SaaS を「AI が使えるツール」として接続する規格。

11.1. MCP とは

Model Context Protocol の略。DB・API・SaaS など 外部システムをツールとして接続 する仕組みです。Google Drive 連携や IDE 診断などがこれにあたります。

11.2. 置き場所 ─ 3つのスコープ（既定は「自分だけ」）

MCP にもスコープが3つあり、既定が local（自分だけ・このプロジェクトのみ） なのが最初のハマりどころです。claude mcp add をそのまま打っても、チームには共有されません。

スコープ	効く範囲	チーム共有	保存先
`local`（既定）	このプロジェクトのみ	❌	`~/.claude.json`（プロジェクトごとの区画）
`project`	このプロジェクトのみ	⭕ バージョン管理経由	`<root>/.mcp.json`
`user`	自分の全プロジェクト	❌	`~/.claude.json`

-s / --scope で指定します。

# 自分だけ・このプロジェクト（既定）。認証情報付きの個人サーバー向き
claude mcp add --transport http stripe https://mcp.stripe.com

# チーム共有。<root>/.mcp.json に書き出されるのでコミットする
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 自分の全プロジェクトで使う個人ツール
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

チーム共有する .mcp.json は、手で書いてコミットしてもかまいません。qiita-digest に置いてあるものは7行しかありません。

AWS 公式ドキュメントを検索・取得できる aws-knowledge を、project スコープ（＝コミットしてチーム全員に効かせる）で登録しています。認証不要の HTTP サーバーなので、クローンした人は何も設定せずに使えます。

これを入れた理由は CLAUDE.md の「AWS の仕様・制限値を記憶で書かない」という規約とセットです。実際に「Step Functions の Redrive は 24 時間以内」と書いてしまったこと（正しくは 14 日）があり、モデルの記憶が古い／曖昧な領域を、一次情報を引ける道具で塞いだという位置づけになっています。規約（お願い）と道具（手段）を組みで用意する、という形です。

同名のサーバーが複数スコープにある場合、設定はマージされず、優先度の高い1つだけが採用されます（local > project > user）。

local スコープの保存先は ~/.claude.json であって、.claude/settings.local.json ではありません。名前がよく似ていますが別物です（後者は設定ファイルのローカルスコープ）。

🕶️ クロちゃん：キミのパソコンにだけ挿さってるドリル、チームのみんなは持ってないしんよ。「動かないんだけど？」って言われる前に、共有するやつは --scope project で置いてほしいしん〜。

認証が必要なサーバー（Google Drive 等）は、対話セッションで /mcp から認可します。
.mcp.json は「他人が書いたコマンドを自分の PC で動かす」ことになるため、チームのリポジトリを初めて開いたときは承認プロンプトが出ます（/mcp で確認・承認）。API キーは直接書かず、${API_KEY} の形で環境変数を展開させるのが定石です。
接続した MCP のツールには mcp__<サーバー名>__<ツール名> という命名規則が付きます（例：mcp__postgres__query）。パーミッション設定で許可・拒否を書くときも、この名前を使います。

11.3. つまずきポイント

MCP は「繋がらない」「繋がったのに使えない」で止まりがちです。よくあるものを先に潰しておきます。

症状	原因と対処
ツールが見えない	stdio サーバーはセッション開始時にツールを検出する。途中で追加したなら、セッションを開き直す
接続済みなのにツールが0個	認証が済んでいない可能性。`/mcp` から認可する
SSE で接続エラー	SSE は非推奨。streamable HTTP に移行済みなので `--transport http` に切り替える
`npx` 系が起動しない	初回のパッケージ取得が起動タイムアウトに間に合わないことがある。`MCP_TIMEOUT`（ミリ秒）で延ばす（例: `MCP_TIMEOUT=10000 claude`）
セッションを再開したら MCP が消えた	`--mcp-config` フラグで渡していた場合、再開時に渡し直しが必要

CLI ツールという選択肢も忘れずに。
外部サービス連携で最もコンテキスト効率が良いのは CLI です。GitHub なら gh を入れておくだけで、Claude は issue 作成・PR 作成・コメント読み取りの使い方を既に知っています（gh がないと GitHub API を直接叩くことになり、レートリミットにも当たりがち）。知らない CLI でも「foo-cli --help で使い方を学んでから A・B・C をやって」と頼めば動きます。MCP を立てる前に「CLI で済まないか」を一度考えるのがおすすめです。

11.4. コストの話 ─ 繋ぎすぎない

MCP は便利なぶん、繋げば繋ぐほどツール定義が積み上がってコンテキストを圧迫します。第3章のコスト表で「使うまで低い」と書きましたが、これは いまは自動で緩和されている という意味であって、ゼロではありません。

何が起きているかというと——セッション開始時に読み込まれるのは 接続済みサーバーのツール名だけ で、完全な JSON スキーマは 実際にそのツールが必要になるまで遅延 されます（ツール検索が既定で有効なため）。だから待機中の消費は最小限に抑えられています。

とはいえ実測できるので、見ておくのが確実です。

/context … セッション全体の内訳。MCP が重くなっていればここに出ます。まず見るのはこちら。
/mcp … 接続状態（connected / failed / pending）の確認と、使っていないサーバーの切断ができます。

判断はシンプルで、「しばらく使っていないサーバーは切る」。第3章の原則②（遅延ロード）は、MCP では 「そもそも繋がない」 という形で効きます。

🕶️ クロちゃん：道具箱、大きいほうがいいってわけじゃないしんよ。使わないドリルが10本並んでると、必要なやつを探すだけで疲れちゃうしん…。

11.5. Skills との違い ─ 混同しやすいので整理

Skills も MCP も機能を足す仕組みなので混同しがちですが、足すものが違います。知識を教えるのが Skills、道具を接続するのが MCP です。

	Skills	MCP
正体	手順書・専門知識（Markdown）	外部システムを操作するツールの接続
何が増えるか	Claude の知識・作法	Claude が呼べるアクション・接続先
実行するのは	Claude 自身（読んで手を動かす）	別プロセスの MCP サーバー（API/DB 呼び出しを代行）
実体	`SKILL.md` を置くだけ	サーバーが常駐（`.mcp.json` で定義）
たとえ	レシピ本を渡す	電動ドリルをコンセントに繋ぐ

「Step Functions の JSONata の書き方を守らせたい」「Lambda テストの手順を固定したい」→ Skills（やり方を教える）
「Slack へ通知させたい」「社内 DB に接続させたい」→ MCP（接続口を与える）

両者は組み合わせも自然です。「MCP で Slack ツールを繋ぎ、Skill でその使い方（どのチャンネルに何を書くか）を教える」といった役割分担になります。

12. settings.json とパーミッション設計 ─「やらせないこと」を先に決める

ひとことで言うと：deny は最後の砦。危険な操作は物理的に封じる。

12.1. パーミッションとは

settings.json は Hooks だけでなく、AI が実行できる操作の許可・拒否（パーミッション） も司ります。

12.2. スコープのおさらい ─ deny は「外せない」から意味がある

settings.json の置き場所が5層（ユーザー＜プロジェクト＜ローカル＜コマンドライン引数＜マネージド）で、下にいくほど強い、という話は第5章で整理しました。パーミッションを設計するうえで効いてくるのは、そこで触れた以下の点です。

パーミッションだけは「上書き」ではなく「マージ」。 各スコープの deny / ask / allow は合算されたうえで評価されるので、チームが .claude/settings.json に張った deny を、個人の設定で外すことはできません。

つまり deny リストは、チーム全員に対する安全弁として機能することが保証されているわけです。
「各自が気をつける」ではなく「誰がやっても止まる」。だからこそ、何を禁止するかをプロジェクト側で決める価値があります。

12.3. 評価順序 ─ deny → ask → allow

最重要ルールが評価順序です。deny は bypassPermissions モードでも強制適用される最後の砦。まず「絶対にやらせないこと」を deny で固めます。

この節のコード例は、記事のために書いたサンプルです。 qiita-digest の settings.json にはまだ permissions を書いておらず（設計フェーズで src/ も tests/ も空のため）、実物を引用できていません。ここだけは他の章と扱いが違う、という前提で読んでください。

12.4. 守るべき3つの deny 設定

{
  "permissions": {
    "deny": [
      "Read(./.env*)",
      "Edit(./.env*)",
      "Edit(/tests/**)",
      "Bash(git push --force*)",
      "Bash(rm -rf *)"
    ]
  }
}

評価基準の保護 … テストファイル（tests/ 配下）を deny 化する。
AI は「テストが落ちたらテスト自体を書き換えて通す」最短経路を選びがち。tests/<service>/test_handler.py を勝手に緩められると検証にならないので、物理的に封じます。

🕶️ クロちゃん：テストが赤いと、つい「テストのほう直せば緑になるしん…？」って魔が差すしんよ。触れないようロックしといてくれると、ボクも正しい子でいられるしんよ。
不可逆操作の禁止 … git push --force*、rm -rf * など。取り返しのつかない操作を、確信を持って実行されるリスクを消します。
シークレットの保護 … .env 系の Read/Edit を deny。コンテキストに入ると意図せず露出するため。

deny は最後の砦ですが、万能ではありません。 2つ注意点があります。

パスの基準：テストの例を ./... ではなく /... で書いているのは、起動ディレクトリに依存させないためです。./ は起動時のカレントディレクトリ基準なのでサブディレクトリから起動すると効きませんが、/ はこの設定ファイル（プロジェクト設定）の置き場所＝プロジェクトルートに固定されます。4つのパス記法の一覧は第12.6節にまとめました。
コマンド引数を狙ったパターンは壊れやすい：Bash(rm -rf *) は rm -fr ... や find . -delete のような別の書き方まではカバーできません。公式も「引数を制約する Bash パターンは fragile (壊れやすい)」と明言しています。だから deny だけに頼らず、「やれたとしても届かない範囲」を OS に強制させるサンドボックスを重ねます（第12.7節）。

12.5. パーミッションモード

用途に応じてセッション全体の挙動を切り替えられます（Shift+Tab で循環切り替え、または起動時に指定）。

モード	挙動
`default`	初回使用時に確認プロンプト
`acceptEdits`	ファイル編集を自動承認
`plan`	読み取り専用。書き込みツールは使用不可
`auto`	分類モデルが各ツール呼び出しのリスクを自動判定
`dontAsk`	allow ルール一致のみ実行、それ以外は全拒否
`bypassPermissions`	全ツール自動承認（隔離環境専用）

パターン記法には癖があります。 Bash(ls *) は lsof にはマッチしません（末尾の * が単語境界を要求するため。Bash(ls*) なら両方にマッチします）。

12.6. ファイルパスの4つの記法 ─ 基準点がそれぞれ違う

Read / Edit のパスパターンには4つの書き方があり、それぞれ「何を起点に解決するか」が違います。ここを混同すると「deny を書いたのに効かない」が起きます。

記法	基準点	例	実際に指す場所
`path` / `./path`	起動時のカレントディレクトリ	`Read(*.env)`	`<起動時のcwd>/*.env`
`/path`	このルールを書いた設定ファイルの置き場所（スコープで変わる。下表）	`Edit(/src/**)`	プロジェクト設定なら `<プロジェクトルート>/src/**`
`~/path`	ホームディレクトリ	`Read(~/Documents/*.pdf)`	`~/Documents/*.pdf`
`//path`	ファイルシステムのルート（真の絶対パス）	`Read(//Users/alice/secrets/**)`	`/Users/alice/secrets/**`

/Users/alice/file のように書いても 絶対パスにはなりません。 先頭の / 1つは「設定ファイルの置き場所」を指すだけで、ファイルシステムのルートではないからです。真の絶対パスにしたいときは //Users/alice/file と / を2つ重ねます。

/path はさらに、どのスコープの設定ファイルに書いたかで実体が変わります。

ルールを書いた場所	`/path` の実体
プロジェクト設定 `.claude/settings.json`	`<プロジェクトルート>/path`
ローカル設定 `.claude/settings.local.json`	`<起動時のcwd>/path`
ユーザー設定 `~/.claude/settings.json`	`~/.claude/path`

だから、ユーザー設定に Read(/secrets/**) と書いても ~/.claude/secrets/** を指すだけで、各プロジェクトの secrets/ は守られません。全プロジェクトに一律で効かせたいなら、// の絶対パスか ~/ のホーム相対を使います。

第12.4節でテストディレクトリの deny ルールを ./... ではなく /... で書いていたのも同じ理屈です。./ は起動ディレクトリ基準なのでサブディレクトリから claude を起動すると効かなくなりますが、/ はプロジェクト設定ファイルの置き場所＝プロジェクトルートに固定されるため、どこから起動しても同じファイルを指せます。

12.7. サンドボックス ─「やれても届かない範囲」を OS に強制する

deny が「やらせないこと」を決めるなら、サンドボックスは「やれたとしても届かない範囲」を決めます。
パーミッションはコマンドが走る前に止める仕組みですが、rm -fr のような表記ゆれ（第12.4節）まで含めて危険なコマンドを事前に全部列挙するのは現実的ではありません。
そこで、走ってしまった後でも被害が及ばない箱を用意する——それがサンドボックスです。

12.7.1. Docker とは別物 ─ OS カーネルレベルの隔離

まず誤解しやすい点から。Claude Code のサンドボックスは Docker ではありません。

	Claude Code のサンドボックス	Docker
隔離の実体	OS のセキュリティ機構（macOS: Seatbelt／Linux・WSL2: bubblewrap）	コンテナ（名前空間・cgroups）
隔離される対象	Bash ツールとその子プロセスだけ（`Read`/`Edit`/`Write` は対象外＝引き続きパーミッションで制御）	プロセス全体
準備	不要（macOS）／パッケージ2つ（Linux・WSL2）	イメージのビルドが必要
効く範囲	ファイルシステムとネットワーク	ほぼ全部

既定では、サンドボックス内の Bash コマンドは 作業ディレクトリとセッション用の一時ディレクトリにしか書き込めません。ネットワークも、コマンドが最初に新しいドメインへアクセスしようとしたタイミングで確認が入ります（許可ドメインは既定で空）。/sandbox コマンドを打つと、現在のモードや設定を確認できるパネルが開きます。

有効化は settings.json からも行えます（ここも第12.4節と同じく、記事のために書いたサンプルです）。

{
  "sandbox": {
    "enabled": true,
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

ネイティブ Windows は非対応です。 サンドボックスが動くのは macOS・Linux・WSL2 のみで（WSL1 は不可）、Windows では WSL2 の中で Claude Code を動かす必要があります。Linux・WSL2 では bubblewrap と socat のインストールが要ります。

12.7.2. パーミッションとの関係 ─ 壁と、ドアの鍵

両者は排他ではなく、役割が違うだけです。

パーミッション（deny/allow） … そのツール呼び出しを実行するかを、実行前に決める。全ツールが対象。
サンドボックス … 実行された Bash コマンドが、どこまで触れるかを OS が強制する。Bash とその子プロセスが対象。

決定的な違いは 強制のされ方です。パーミッションはコマンド文字列を見て事前に判断しますが、サンドボックスは 走っているプロセスに対して OS が境界を効かせます。つまり、許可したコマンドが名前から想像される以上のことをしても、境界は破れません。第4章の強度階層で deny とサンドボックスが並んで一番右にいた理由がこれです。

13. Memory ─ セッションをまたぐ記憶の外部化

ひとことで言うと：Claude は毎回"初対面"。覚えておいてほしいことは外部ファイルに書く。

13.1. Memory とは

Claude Code は セッションをまたぐ記憶を持ちません。毎回「初対面」からスタートします。だからこそ、引き継ぎたい情報は 外部ファイルへの永続化が必須 です。

ここでの「記憶」は、--resume・/rewind・/compact とは別物です。それらは「同じ会話（セッション）」をどう保存・再開・巻き戻す・圧縮するかという話ですが、Memory は まったく新しいセッションに知識を持ち越すための仕組みです。

🕶️ クロちゃん：ボク、朝起きると昨日のこと全部わすれてる金魚だしんよ…。「昨日の続きね」って言われても、キョトンだしん。大事なことはメモに残しといてほしいしんよ。

CLAUDE.md と Auto Memory は「2つの相補的な記憶の仕組み」で、役割が分かれています。

	CLAUDE.md	Auto Memory
誰が書くか	あなた	Claude 自身
中身	指示・ルール	学習内容・パターン
スコープ	プロジェクト／ユーザー／組織	リポジトリ単位（worktree 間で共有）
読み込まれるタイミング	毎セッション	毎セッション（先頭 200 行／25KB まで）
向いている用途	コーディング規約・ワークフロー・アーキテクチャ	ビルドコマンド・デバッグの知見・好みの発見

13.2. 自動メモリ（Auto Memory）

新しめのバージョンではデフォルト有効。Claude 自身が学んだことをファイルに書き込みます。ビルドコマンド・デバッグの知見・アーキテクチャのメモ・コードスタイルの好み・作業習慣など、「次のセッションでも役に立ちそうか」をClaudeが判断して書き込む対象を決めます（毎セッション必ず書くわけではありません）。

~/.claude/projects/<project>/memory/
├── MEMORY.md          ← エントリポイント（毎セッション読み込み）
├── debugging.md       ← トピックファイル（オンデマンド読み込み）
└── api-conventions.md

MEMORY.md の読み込みは 先頭 200 行または 25KB まで が目安。ここは「索引」に徹し、詳細はトピックファイルに分離します（原則①・②がここでも効いています）。

Auto Memoryは /memory コマンドでオン/オフを切り替えられます（トグルはautoMemoryEnabledとして設定ファイルに保存されます）。プロジェクト単位で切りたい場合は、そのプロジェクトの settings.json に {"autoMemoryEnabled": false} と書く方法もあります。環境変数 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 でも無効化できます。

一時的なメモではなく プロジェクト全体の恒久ルールにしたい場合は、そのままCLAUDE.mdへの追記をClaudeに頼めます（「これをCLAUDE.mdに追加して」）。書き込み先を最初から選べる、というだけで自動で"昇格"する機構があるわけではありません。

保持期間にも違いがあります。Auto Memoryは明示的に消さない限り残り続けますが、会話トランスクリプト（.jsonl）は既定30日で自動削除されます。「消えてほしくない知見」はAuto MemoryかCLAUDE.mdに書く、が結論です。

13.3. 手動での引き継ぎ「3点セット」

長いタスクを別セッションに引き継ぐときは、次の3つを用意すると失敗しません。

ファイル	役割	答える問い
Git log	判断の履歴	何が完了しているか
進捗ファイル（`todo.md`）	現在地	どこまで終わったか
実行計画（`plan.md`）	次の一手	次に何をすべきか・なぜ

「概ね順調です」という引き継ぎは無意味です。 良い引き継ぎには、目的・アプローチの判断理由・各ステップの検証コマンド・進捗チェックボックスが必要。次のセッションの自分（or AI）が、読んだだけで手を動かせる状態にしておきましょう。

14. プラグイン ─ 拡張機能をまとめて配る・もらう

ひとことで言うと：ここまでの機能を1つのフォルダに詰めて、インストールできる形にしたもの。

14.1. プラグインとは

第6章から第13章まで、拡張機能を1つずつ見てきました。ただ、これを チームや他プロジェクトに配ろうとすると急に面倒 になります。「この Skill と、この Hook と、この MCP 設定を、各自の .claude/ にコピーしてください」——現実的ではありません。

そこで プラグイン です。Skills・Subagents・Hooks・MCP サーバーなどを1つのフォルダにまとめ、インストール可能にしたもの。中身はここまで見てきたものと同じで、置き方が変わるだけ です。

場所	中身
`.claude-plugin/plugin.json`	マニフェスト（名前・説明・バージョン）
`skills/<name>/SKILL.md`	Skills（第7章）
`agents/<name>.md`	Subagents（第8章）
`hooks/hooks.json`	Hooks（第10章）
`.mcp.json`	MCP サーバー（第11章）
`.lsp.json`	言語サーバー（コードインテリジェンス）

よくあるミス：skills/ や agents/ を .claude-plugin/ の中に入れてしまうこと。.claude-plugin/ に置くのは plugin.json だけ で、残りはすべてプラグインのルート直下 です。

.claude/ に直接置くのとの違いは、実質2点です。

	`.claude/` に直接	プラグイン
スキルの呼び名	`/deploy`	`/plugin-name:deploy`（名前空間が付く）
向いている用途	個人の作業・そのプロジェクト限定	チーム配布・複数プロジェクトで再利用・バージョン管理

まず .claude/ で作って回し、共有したくなったらプラグインに変換する——これが自然な流れです。

14.2. マーケットプレース ─ Skills はどこで探すのか

自分で作らなくても、公開されているものを入れられます。そのカタログが マーケットプレース です。アプリストアと同じで、「ストアを登録する」→「個別にインストールする」 の2段階になります。

Anthropic 公式の claude-plugins-official は、Claude Code の起動時に自動で登録されます。中身は /plugin の Discover タブか claude.com/plugins で見られます。ここが実用的で、たとえばこんなものが並んでいます。

コードインテリジェンス（LSP）：typescript-lsp・pyright-lsp・gopls-lsp・rust-analyzer-lsp など。入れると Claude が 編集した直後に型エラーを受け取り、定義ジャンプや参照検索ができる ようになります。第3章のコスト表で「むしろ減ることもある」と書いたのがこれで、ファイルを読み漁らずに済むぶん、コンテキストがかえって軽くなります（別途、言語サーバー本体のインストールが必要）。
外部サービス連携：github・gitlab・linear・notion・figma・slack・sentry・vercel・firebase・supabase など。MCP サーバーが同梱済み なので、第11章のような手設定なしに繋がります。
開発ワークフロー：commit-commands（コミット・PR 作成）、pr-review-toolkit、plugin-dev
セキュリティ：security-guidance（Claude の変更を都度レビューして脆弱性を指摘・修正させる）

公式のほかに、審査を通った第三者製が並ぶ コミュニティマーケットプレース もあります。こちらは手動で登録します。

# コミュニティマーケットプレースを登録する
/plugin marketplace add anthropics/claude-plugins-community

# そこからインストールする
/plugin install <plugin-name>@claude-community

登録元は GitHub リポジトリ・任意の Git URL・ローカルパス・リモート URL のいずれでもかまいません。社内向けなら private リポジトリにマーケットプレースを置く のが定石です。

/plugin marketplace add your-org/claude-plugins           # GitHub（owner/repo）
/plugin marketplace add https://gitlab.com/org/p.git      # 他の Git ホスト
/plugin marketplace add ./my-marketplace                  # ローカル

プラグインは、あなたの権限で任意のコードを実行できます。 Anthropic は同梱される MCP サーバーやファイルの中身を管理しておらず、意図どおり動くことを保証してもいません。信頼できる発行元のものだけを入れてください。 第12章の deny リストやサンドボックスと違い、ここは自分の判断が最後の砦です。

14.3. インストール ─ 何が、どこに入るのか

インストールは /plugin の対話パネルか、コマンドで行います。

/plugin                                          # パネルを開く（Discover / Installed / Marketplaces / Errors）
/plugin install github@claude-plugins-official   # 名前を指定して入れる
/reload-plugins                                  # 再起動せずに反映する

インストール時にスコープを選びます。 第5章の3層が、そのまま出てきます。

スコープ	効く範囲	記録先
User	自分の全プロジェクト	ユーザー設定
Project	このリポジトリの全員	`<root>/.claude/settings.json`（コミットする）
Local	自分だけ・このリポジトリのみ	`.claude/settings.local.json`（git 管理外）
Managed	組織全体	管理者が配布。変更できない

そして肝心の 実体がどこに置かれるか ですが、ここが少し独特です。プラグイン本体はキャッシュにコピーされます。

~/.claude/plugins/cache/     ← インストールされたプラグインの実体
~/.claude/settings.json      ← 「どれを有効にするか」の情報はこちら（スコープに応じて .claude/settings.json）

実体と「有効にするかの設定」が別々に置かれている わけです。だからチーム共有ができます（設定だけコミットすればよく、実体は各自の環境に落ちてくる）。

この構造が分かっていると、2つのトラブルに納得がいきます。

プラグイン内の相対パスは、プラグインの外を参照できません。 「インストールしたらファイルが見つからない」の原因はたいていこれです。
スキルが出てこないときはキャッシュを消して入れ直す のが有効です（rm -rf ~/.claude/plugins/cache → Claude Code を再起動 → 再インストール）。

14.4. チームに配る

プロジェクトの .claude/settings.json にマーケットプレースを書いておくと、チームメンバーがそのリポジトリを開いたときにインストールを促されます。

{
  "extraKnownMarketplaces": {
    "my-team-tools": {
      "source": { "source": "github", "repo": "your-org/claude-plugins" }
    }
  },
  "enabledPlugins": ["formatter@my-team-tools"]
}

第5章の 「チーム全員に効かせたいものはリポジトリへ」 が、プラグインの単位でも成立します。

なお、プラグインに同梱できるのは上の表にある構成要素だけで、.claude/rules/ のパスベースルールは含められません。ルールを複数リポジトリで共有したいときは、第6.5節の symlink か ~/.claude/rules/（自分の全プロジェクト）を使うか、内容を Skill に仕立ててプラグインへ載せます。

14.5. 入れすぎない ─ プラグインもコンテキストを食う

便利だからと入れすぎると、第3章のコンテキストコストが積み上がります。判断材料はちゃんと出るようになっていて、プラグインの詳細画面にこの3つが表示されます。

Context cost … そのプラグインが毎ターン消費するトークンの見積もり
Will install … 入れると何が増えるか（コマンド・エージェント・スキル・Hooks・MCP/LSP サーバー）の一覧
Last updated … 最終更新日

さらに /plugin の Installed タブには 「Not used recently」 という区分があって、入れたきり2週間以上使っていないもの が集められます。起動時間とコンテキストだけ食っている状態なので、ここを定期的に見て畳むのが健全です。

/plugin list                       # 入っているものを一覧する
/plugin disable <name>@<market>    # アンインストールせず無効化
/plugin uninstall <name>@<market>  # 完全に削除

🕶️ クロちゃん：便利な道具をいっぱいもらえるのは嬉しいしんよ！でも使わない道具まで机に置きっぱなしだと、作業スペースがなくなっちゃうしん…。たまに片づけてほしいしんよ〜。

14.6. 自分で作る

中身はここまでと同じものなので、作るのは拍子抜けするほど簡単です。フォルダを作ってマニフェストを置き、skills/ などを並べるだけ。

mkdir -p my-first-plugin/.claude-plugin

my-first-plugin/.claude-plugin/plugin.json

{
  "name": "my-first-plugin",
  "description": "チーム共通のデプロイ手順",
  "version": "1.0.0"
}

開発中は、インストールせずに --plugin-dir で読み込めます。

claude --plugin-dir ./my-first-plugin

すでに .claude/ に Skills や Subagents が溜まっているなら、フォルダごとコピーするだけで移行できます（Hooks だけは settings.json の hooks ブロックを hooks/hooks.json に移す必要があります）。配布するときは、マーケットプレース用のリポジトリを1つ作ってそこに登録します。

15. 全体像とまとめ

15.1. ディレクトリ全体像

ここまで章ごとに引用してきたファイルを、1枚に並べるとこうなります（qiita-digest の実際の構成です）。

qiita-digest/
├── CLAUDE.md                        # 6章 常時適用の規約（57行。原則と共通規約だけ）
├── .mcp.json                        # 11章 チーム共有の MCP サーバー定義（aws-knowledge）
├── src/  tests/  docs/  tools/      # プロジェクト本体
└── .claude/
    ├── README.md                    # 何がどこにあるかの索引（人間向け）
    ├── settings.json                # 10章 Hooks の定義（共有）
    ├── settings.local.json          # 12章 個人設定・許可リスト（git 管理外）
    ├── hooks/
    │   ├── protect_credentials.py   # 10章 PreToolUse: .env / *.pem をブロック
    │   └── ruff_check.py            # 10章 PostToolUse: 編集した .py に ruff check
    ├── rules/                       # 6章 パスベースルール9本（8本は paths 指定・1本は常時ロード）
    │   ├── stepfunctions.md         #      *.asl.json を触ったときだけ
    │   ├── lambda.md                #      src/**/*.py・tests/**/*.py を触ったときだけ
    │   └── deployment.md            #      paths なし＝常時ロード（理由をファイル冒頭に明記）
    ├── skills/                      # 7章 開発フローを型化した7本
    │   ├── scaffold/SKILL.md        #      新サービスの雛形一式を作る
    │   └── review/SKILL.md          #      code-reviewer へ文脈を添えて委任する
    └── agents/
        └── code-reviewer.md         # 8章 読み取り専用のレビュアー（別コンテキスト）

~/.claude/                            # 上記と同構成の「ユーザーグローバル版」（全プロジェクトに効く）
├── CLAUDE.md
├── settings.json
├── skills/  agents/  commands/
├── plugins/cache/                    # 14章 インストール済みプラグインの実体
└── projects/<project>/memory/        # 13章 セッションをまたぐ記憶
~/.claude.json                        # 11章 MCP の local / user スコープ定義（settings.local.json とは別物）

rules/ と skills/ は代表的なものだけ抜き出しています。全部を見たい方は、リポジトリの .claude/README.md に何がどこにあるか・なぜそう置いたかを一覧にしてあるので、そちらが入口として読みやすいはずです。

15.2. どれを使えばいい？早見表

やりたいこと	使う機能	コンテキスト上の役割
プロジェクトの前提・規約を常に守らせたい	CLAUDE.md	常時ロード（地図）
特定のファイルを触るときだけ規約を効かせたい	パスベースルール（`.claude/rules/`）	遅延ロード
長い作業手順を「型」として固定したい	Skills	遅延ロード
調査や専門作業を別コンテキストに任せたい	Subagents	コンテキスト隔離
よく打つ定型プロンプトを短縮したい	Slash Commands	手動呼び出し
「〜したら必ず〜する」を自動化したい	Hooks	実行の保証
危険な操作を禁止したい	settings.json（deny）	安全弁
外部の DB・API を操作させたい	MCP	外部連携
セッションをまたいで覚えさせたい	Memory	記憶の外部化
チーム全員に効かせたい／自分だけに留めたい	スコープの使い分け	適用範囲の制御
出来合いの拡張を入れたい／自分の設定を配りたい	プラグイン	拡張の再利用と配布
ルールが守られない	強度を一段上げる（第4章）	遵守の保証

15.3. まずはここから

いきなり全部やろうとすると挫折するので、小さく始めるのがおすすめです。

CLAUDE.md を 200 行以下にスリム化する（「消したら Claude がミスするか？」で剪定）
settings.json に「テスト・lint・.env」の deny リストを追加する
Write / Edit 後に自動フォーマッタを走らせる PostToolUse Hook を1つ設定する

この3つは、いずれも 第4章の階段を1段上げる 作業です。慣れてきたら、繰り返す作業の Skill 化、調査の Subagent 委任、引き継ぎ 3点セット へと広げていきます。

16. おわりに

冒頭の「出てくるコードの質がやたらブレる」問題は、結局のところ AI の周囲の構造が整っていなかった のが原因でした。プロンプトをどれだけ丁寧に書いても、机の上が散らかっていれば安定しないです。

生成AI 全盛の昨今、どんなコンテキストを渡すかを設計する「コンテキストエンジニアリング」 は、プロンプトの小手先テクニック以上に効いてくる領域だと感じています。そしてその外側には、モデルの挙動そのものを環境で縛る「ハーネスエンジニアリング」 がある——第1章で見たとおりです。

どちらも、やっていることは同じでした。「良い結果が出ますように」と祈るのではなく、出る構造を設計する。Claude Code の設定ファイル群は、まさにそのための道具箱です。

まずは CLAUDE.md と、1つの Skill、1つの Hook から。
祈りから設計へ、少しずつ移していきましょう。

🕶️ クロちゃん：机の上をきれいに整えてくれたら、ボク超はりきっちゃうしんよ！ボクってば、環境さえ整えばいいコード書いちゃう子だしん。いっぱい構ってしんね〜。

今後について

ここまでで 「何を・どこに置くか」 は一通り揃いました。ただ、置いただけでは回りません。実際にチーム開発へ広げていくには、まだ見えていない課題もいくつも残っています。

プロジェクト固有の情報をどう持たせるか
チーム開発でのハーネス設計・運用ルールの策定（どこまでを強制的に閉じ、どこからを運用でカバーするか）
複数プロジェクトで使い回せるスキャフォールドをどうつくるか
実際のチーム開発でどう使い、どう進めていくか（Claude Code に不慣れなメンバーへの教育、開発ループの回し方、各種フィードバックループの設計）
Claude Code 以外にも適用できるマルチエージェント向けの設計（AGENTS.md を正本にして CLAUDE.md から参照させる、など）

このあたりは実践しながら、追って記事にしていくつもりです。

Claude Code は仕様更新がとても活発な領域です（Skills・パーミッションモード・Auto Memory など）。細かい仕様は変わっている可能性があるので、正確な最新仕様は必ず公式ドキュメントを参照してください。本記事は コンテキストエンジニアリングという普遍的な考え方 を軸にしているので、機能名が変わっても「なぜそれが必要か」の判断軸は使い続けられるはずです。

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