このレッスンのゴール — 「迷ったら戻る1枚の地図」
第6章ではここまで、スラッシュコマンド・Hooks・Skills・MCP・Subagents・settings.json・Worktrees・デバッグループと、Claude Code を操縦(ステアリング、＝振る舞いを目的に合わせて誘導すること)する手法を1つずつ深掘りしてきました。さらに直前の ch6-l9 で Rules・Output Styles・システムプロンプト追記の3つを足しました。
このレッスンはそれらの総まとめです。新しい機能は出てきません。代わりに「どの手法を、いつ使うか」を1枚の地図にします。これは原典ブログ「Steering Claude Code」の核心そのものです。深い使い方は各レッスンに譲るので、本文からどんどんリンクへ飛んでください。迷ったらこの地図に戻ってくる、という使い方を想定しています。
まず「判断軸」 — なぜ全部 CLAUDE.md に書くのが悪手か
手法を選ぶには、まず4つの違いを見ます。どの手法も同じではなく、次の4点でクセが違います。
- いつ読み込まれるか: セッション開始時にずっと持つのか、ファイルに触れた時だけか、呼び出した時だけか。
- コンパクション(文脈圧縮)で消えるか: 会話が長くなると過去が要約・圧縮されます。その時に残るのか、回避(bypass)されるのか、消えてしまうのか。
- コスト: 常に文脈に居座る指示はトークン(AIが読む文字の単位)を食い続けます。必要な時だけ読まれる指示は安いです。
- 指示の強制力: 「お願い」レベルなのか、モデルの気分に関係なく決定論的(必ず同じ条件で発火する)に効くのか。
ここで大事な結論。何でも CLAUDE.md に書くのは悪手です。理由は2つあります。
- CLAUDE.md はセッション中ずっと文脈に居座るので、書けば書くほどトークンを食い、肝心の作業の余地を圧迫します。だからルート CLAUDE.md は200行未満に保つのが推奨です(さらに、オーナー＝管理者を決めて、コードと同じようにレビューするのが良いとされています)。
- CLAUDE.md はお願いであって強制ではない。「毎回必ずYせよ」「絶対するな」と書いても、モデルがその通り動く保証はありません。本当に止めたいなら別の仕組み(Hooks など)が要ります。
つまり「常に効かせたい/必要な時だけ効かせたい」「お願いでいい/絶対守らせたい」を切り分けて、目的に合う手法を選ぶのがこのレッスンの全てです。
1枚の比較表 — 8つの置き場所
ここが地図の本体です。原典ブログの比較表(列＝Method / When it's loaded / Compaction behavior / Context cost / When to use)を、CLAUDE.md のルート版・サブディレクトリ版を分けて8行で示します。
| 手法 | 読み込まれるタイミング | コンパクション時の挙動 | コスト | 主な用途 |
|---|---|---|---|---|
| ルート CLAUDE.md | セッション開始時 | メモ化されて再読込される | 高 | プロジェクト概要・規約 |
| サブディレクトリ CLAUDE.md | 該当ファイルに触れた時(オンデマンド) | 触れるまで失われている | 低 | そのディレクトリ固有のルール |
| Rules | セッション常時 or paths でスコープ | 再注入される | 中(paths スコープでコスト減) | ファイル単位の制約(constraints) |
| Skills | 名前は開始時・本体は呼び出し時 | バジェット内で再注入(多いと古いものから落ちる) | 低 | 手続き的ワークフロー(手順) |
| Subagents | 名前は開始時・本体は隔離コンテキスト | 最終メッセージのみメインに戻る | 低 | 並列・隔離タスク |
| Hooks | ライフサイクルイベントで発火 | コンパクションを回避(bypass) | 低 | 決定論的な自動化 |
| Output Styles | セッション開始時 | 決してコンパクションされない | 高 | 役割そのものの変更 |
| システムプロンプト追記 | 起動時(--append-system-prompt) | 初回以降はキャッシュ | 中 | フォーマット・標準の追加 |
各行の深掘りは既存レッスンにあります。関連リンクをまとめておきます。
- スラッシュコマンド: /lesson/ch6-l1
- Hooks: /lesson/ch6-l2
- Skills: /lesson/ch6-l3
- MCP: /lesson/ch6-l4
- Subagents: /lesson/ch6-l5
- settings.json と Permissions: /lesson/ch6-l6
- Worktrees(並列開発): /lesson/ch6-l7
- デバッグループ実践: /lesson/ch6-l8
- Rules / Output Styles / システムプロンプト追記: /lesson/ch6-l9
表の読み方のコツ。「高コスト」の2つ(ルート CLAUDE.md と Output Styles)は常に文脈に居座るので、ここに何でも詰めるとすぐ重くなります。逆に Skills・Subagents・Hooks は「必要な時だけ」なので安く、強い武器です。
各手法の置き場所(ファイルパス)早見
地図と一緒に、各手法が「どこに書くファイルか」を確認しておきます。原典ブログ準拠の正確なパスです。
| 手法 | 置き場所 |
|---|---|
| CLAUDE.md | ルート / 各サブディレクトリ(例: app/api/CLAUDE.md) |
| Rules | .claude/rules/ の Markdown |
| Skills | .claude/skills/ 配下のフォルダ(SKILL.md に手順を書く) |
| Subagents | .claude/agents/ の Markdown(YAML frontmatter + 本文) |
| Hooks | settings.json / 管理ポリシー設定 / スキル・エージェントの frontmatter |
| Output Styles | .claude/output-styles/(組み込みは Proactive / Explanatory / Learning) |
| システムプロンプト追記 | 起動フラグ --append-system-prompt |
やってはいけないパターンと、正しい置き換え
原典ブログがはっきり警告している「CLAUDE.md の誤用」と、その直し方です。ここが一番実戦的です。
NG1: 「Xしたら毎回必ずYせよ」を CLAUDE.md に書く
CLAUDE.md はお願いなので、毎回確実には実行されません。「毎回必ず」は決定論的な仕組みの仕事です。
- 正しい置き換え → Hooks。編集後に linter を走らせる、といった自動化は Hooks が決定論的に発火します。詳しくは Hooks の回。
# 例: 編集のたびに必ず prettier を走らせたい → PostToolUse フック(settings.json)
# CLAUDE.md に「毎回 prettier をかけて」と書くのではなく、ここで強制する
NG2: 「絶対にこれをするな」を CLAUDE.md に書く
「絶対するな」は CLAUDE.md では本当のガードレールになりません。守られない時があります。
- 正しい置き換え → ブロック機能付きの Hooks(PreToolUse フックは exit code 2 で拒否=deny できる)か、managed settings(管理ポリシー設定)。組織として禁止したいなら後者。
# PreToolUse フックの考え方: 危険なコマンドを検査し、ダメなら exit 2 で拒否
# 例) rm -rf を含むコマンドをブロックする、など
exit 2 # ← この終了コードで、そのツール呼び出しが拒否される
NG3: 30行の手順を CLAUDE.md に書く
長い手順を CLAUDE.md に置くと、毎セッション常に読み込まれてトークンを浪費します。
- 正しい置き換え → Skills。本体(SKILL.md の全文)は呼び出した時だけ読み込まれます。開始時は「名前と説明」だけ。デプロイ手順やリリースチェックリストはこれが最適。詳しくは Skills の回。
NG4: paths の無い「API 専用ルール」
Rules に paths を付けないと、API と無関係なファイルを触っている時も常にトークンを食います。
- 正しい置き換え → paths フィールドでスコープする。対象パスを書けば、そのファイルに触れた時だけ効きます。
---
paths:
- "src/api/**"
- "**/*.handler.ts"
---
すべての API ハンドラは、処理の前に Zod で入力を検証すること。
決定の早見 — どれを選ぶか(フローチャート風)
迷ったら上から順に当てはめてください。これがこの地図の「結論」です。
- プロジェクト全体の規約・概要(ビルドコマンド、ディレクトリ構成、チームの慣習)→ ルート CLAUDE.md(ただし200行未満に保つ)
- 特定ディレクトリだけのルール(例:
app/api/配下の決まり)→ サブディレクトリ CLAUDE.md(そこに触れた時だけ読まれる) - 特定ファイル群への制約(例: API ハンドラは入力検証、マイグレーションは追記のみ)→ Rules(必ず paths でスコープ)
- 手順・チェックリスト(デプロイ、リリース、レビューの段取り)→ Skills
- 隔離したい大きな脇道タスク(深い検索、ログ解析、依存関係監査)→ Subagents(専用の新しいコンテキストで動き、最終メッセージだけ戻る。最大5階層までネスト可)
- 「毎回必ず」「絶対するな」＝決定論的に強制したい→ Hooks(ブロックは PreToolUse + exit 2、または managed settings)
- 役割そのものを大きく変えたい→ Output Styles(ただし既定の指示が置き換えられて外れるので慎重に。残したいなら frontmatter に
keep-coding-instructions: true) - 起動時に標準・フォーマットを足したいだけ(役割は変えない)→ --append-system-prompt(元のシステムプロンプトに足すだけ。キャッシュで初回以降は安い)
補足: チームでこれらの設定を共有したい時は plugins(プラグイン) でまとめて配布できる、と原典ブログは触れています。
操縦法を診断してもらう: あなたは Claude Code の操縦法アドバイザーです。私がこれから「やりたい制御」を1つ貼ります。次の8択から最適なものを1つ選び、理由を3行で述べてください。選択肢=(1)ルートCLAUDE.md (2)サブディレクトリCLAUDE.md (3)Rules(pathsでスコープ) (4)Skills (5)Subagents (6)Hooks (7)Output Styles (8)--append-system-prompt。判断軸は「いつ読み込まれるか/コンパクションで消えるか/コスト/強制力(お願いか決定論的か)」です。やりたい制御=「src/api 配下のハンドラは必ず入力検証させたい」まとめ — この地図に戻ってくる
新しい手法を覚える必要はもうありません。覚えるべきは選び方です。
- 4つの軸(読み込みタイミング / コンパクション / コスト / 強制力)で見れば、どの手法も役割が決まる。
- 「全部 CLAUDE.md」は重くて弱い。お願いでいいなら CLAUDE.md、絶対守らせたいなら Hooks、長い手順は Skills、ファイル単位の制約は Rules(paths)。
- 実際の構築の細部は各レッスン(ch6-l1〜ch6-l9)へ。
次に自分のリポジトリで「これ、どこに書こう?」と迷ったら、上の決定の早見をもう一度なぞってください。それがこのレッスンの使い方です。
自分の規約を仕分ける: あなたは Claude Code の設定設計の相談相手です。私のプロジェクトには次の3つの決まりがあります。それぞれ「ルートCLAUDE.md / サブCLAUDE.md / Rules / Skills / Subagents / Hooks / Output Styles / append-system-prompt」のどれに置くのが最適か、理由つきで表にしてください。(1)『API ハンドラは必ず入力検証する』(2)『ファイルを編集したら毎回 prettier をかける』(3)『本番デプロイは10ステップの決まった手順がある』