🗂️ Claude Code の指示をどこに書くか — 7つの指示面とコンテキスト負債の設計

Claude Code には、AI の挙動を制御する手段が 7 つあります。CLAUDE.md・Rules・Skills・Subagents・Hooks・Output styles・System prompt 追加です。これらに加えて memory・plugins・managed settings も挙動を左右します。

問題は「どの指示をどこに書くか」です。置き場を誤ると、性能より先に運用が壊れます。たとえば手順をすべて CLAUDE.md に書くと、関係ない作業でも毎回ロードされ、コンテキストを浪費します。長いセッションでは圧縮 (compaction) によって指示が失われ、Claude が従わなくなります。

この記事では、各手段を「読込タイミング / 圧縮 (compaction) 後の残り方 / 権威の強さ / コンテキストコスト」の 4 軸で整理します。さらに C4 モデルでロード機構を構造化し、設定データモデル・構築方法・運用・ベストプラクティスまで通しで示します。出典は Anthropic 公式ブログ「Steering Claude Code: skills, hooks, rules, subagents and more」と Claude Code 公式ドキュメントです。

概要

Claude Code は、コーディングタスクを自律的に実行するエージェントです。長いセッション・複数ファイルにまたがる作業・サブエージェントへの委任を通じて動作するため、「どの指示をどこに書いたか」が性能より先に問われる設計課題になります。

Anthropic はこの課題に対して 7 つの指示面 (steering surfaces) を提供します。指示面とは、Claude の挙動を制御する手段群の総称です。各手段は次の 3 軸で異なります。

1. いつコンテキストに読み込まれるか (セッション開始 / オンデマンド / ライフサイクルイベント)
2. 圧縮 (compaction) 後も残るか (消える / 再注入される / 圧縮をバイパスする)
3. どれだけの権威 (authority) を持つか (Claude の判断に委ねる指示か / 確定的に強制するか)

なぜ指示の置き場を誤ると運用が壊れるのか

Claude Code はすべての指示をコンテキストウィンドウ上で処理します。コンテキストは有限であり、セッションが長くなると compaction (圧縮) が発生して古い内容が失われます。

コンテキスト負債 (context debt) とは、この問題が蓄積した状態です。典型的な進行は次のとおりです。

• チーム全員が CLAUDE.md に指示を追記し続け、誰も削除しません。
• 結果として、エンジニア全員の全セッションで関係のない指示が毎回ロードされます。
• トークン消費が増え、Claude が指示に従う精度が下がります。
• compaction で失われるべきでない指示まで失われ、運用が不安定になります。

正しい指示面を選ぶと、「必要なときだけ必要な指示をロードする」設計になり、コンテキスト効率と指示の確実性が両立します。本ドキュメントは「何をコンテキストに載せずに済ませるか」を判断軸として、各手段の配置・ロード機構・データモデル・運用知見を整理します。

特徴

7 手段の一言要約

全体を貫く設計思想

Progressive disclosure (段階的開示)

• Skills と Subagents は名前・説明だけを先にロードし、本体はオンデマンドでロードします。
• 「必要になるまで全体を読み込まない」ことで、コンテキストコストをゼロに近づけます。
• disable-model-invocation: true を設定すると、Claude がこのスキルを自動起動しなくなり、説明の事前ロードも抑制されます (/name での手動起動は可能です)。

コンテキストに載せないで済ませることが設計目標

• Hooks は設定がコンテキスト外に存在し、発火してもコンテキストを汚しません。
• Subagents は独立したコンテキストウィンドウを持ち、中間処理が親セッションを汚しません。
• Path-scoped rules は対象ファイルを触るまでロードされません。

指示と強制を区別する

• CLAUDE.md / Rules / Skills への記述はすべて「指示 (instruction)」であり、Claude が守るかどうかは確率的です。
• 「絶対に起きてはいけない操作」は Hooks (PreToolUse) と Permissions (deny ルール) で確定的に強制します。
• Managed settings は管理者デプロイによる上書き不可の組織全体ガードレールです。

4 軸比較テーブル

補足: Managed settings と Plugins

Managed settings (managed-settings.json / MDM / レジストリ) は、管理者がデプロイしてユーザー設定で上書きできない組織ガードレールです。許可・拒否コマンド、利用モデル制限、MCP サーバー制御を強制し、claudeMd キーで managed CLAUDE.md 相当の指示も埋め込めます。

Plugins (.claude-plugin/plugin.json + skills/ + agents/ + hooks/) は、Skills / Subagents / Hooks / MCP servers を 1 ディレクトリにまとめて配布・再利用するパッケージング層です。スキル名はプラグイン名でネームスペース化 (/plugin-name:skill-name) され、衝突を防ぎます。.claude/skills/ 直下の standalone 設定と動作は同じですが、複数リポジトリへの配布・バージョン管理・マーケットプレイス登録が可能です。

構造

7 手段が「どのタイミングで・どの経路でコンテキストに載るか / compaction でどう扱われるか / hook はどこで harness が実行するか」というロード機構を、C4 model の 3 段階で示します。

システムコンテキスト図

システムコンテキスト図の要素

コンテナ図

ここでの「コンテナ」は、claude プロセス内の論理処理単位を指します。実際にはすべて単一プロセス内で動作します。

コンテナ図の要素

コンポーネント図

セッション初期化ローダー

Progressive Disclosure ローダー

コンテキストウィンドウマネージャー

hook ランナー harness

指示がコンテキストに載る経路

データ

各手段の設定ファイルが持つエンティティ・属性・関連をモデル化します。

概念モデル

情報モデル

エンティティの要点

構築方法

CLAUDE.md

スコープに応じて複数の場所に置けます。ロード順はブロードなスコープが先です。

/init で既存コードベースを解析して自動生成できます。既存ファイルがあれば上書きせず改善提案を行います。

/init

@path インポート記法で他ファイルを読み込めます。最大 4 ホップで再帰インポートでき、バックティックで囲うとインポートされません。

プロジェクト概要は @README を参照してください。
利用可能な npm コマンドは @package.json を参照してください。
git ワークフローは @docs/git-instructions.md を参照してください。

推奨記述スタイルは次のとおりです。目安は 200 行以内で、HTML コメント (<!-- ... -->) はコンテキストに注入されないため、メンテナ向け注記に使えます。

# ビルドコマンド
- テスト実行: `npm test`
- ビルド: `npm run build`

# コーディング規約
- インデント: スペース 2 文字
- 全 API エンドポイントで Zod による入力バリデーションを行う

大規模モノレポで他チームの CLAUDE.md を除外するには claudeMdExcludes を使います。

{
  "claudeMdExcludes": ["**/other-team/CLAUDE.md"]
}

Rules

.claude/rules/*.md に配置し、paths frontmatter で適用ファイルを限定します。paths がない場合はセッション開始時に常時ロードされます。

---
paths:
  - "src/api/**/*.ts"
  - "lib/**/*.ts"
---

# API 開発ルール

- 全エンドポイントで入力バリデーションを実施する
- エラーレスポンスは標準フォーマットを使う

ユーザーレベルのルールは ~/.claude/rules/ に置き、全プロジェクトに適用されます。シンボリックリンクで共有ルールを使い回せます。

Skills

.claude/skills/<skill-name>/SKILL.md を本体に、補助ファイルを同ディレクトリに置きます。

.claude/skills/deploy/
├── SKILL.md          # メイン手順書 (必須)
├── examples/sample.md
└── scripts/validate.sh

SKILL.md の記述例と主要フィールドは次のとおりです。

---
name: deploy-staging
description: ステージング環境へデプロイします。「ステージングにデプロイ」「デプロイしたい」に反応します。
argument-hint: "[env]"
allowed-tools: Bash
---

デプロイ手順:
1. テストスイートを実行する: `npm test`
2. ビルドする: `npm run build`
3. ステージングへプッシュする: `./scripts/deploy.sh $ARGUMENTS`

!`command` 構文でスキル実行時にシェルコマンドの出力を差し込めます。

Subagents

.claude/agents/<name>.md の frontmatter で定義し、本文がシステムプロンプトになります。/agents コマンドで対話的に作成・編集できます。

---
name: code-reviewer
description: コードレビューを行い、品質・セキュリティ・ベストプラクティスを指摘します。コード変更後に自動で呼ばれます。
tools: Read, Glob, Grep
model: sonnet
color: blue
memory: project
---

あなたはシニアコードレビュアーです。コード品質・セキュリティ・ベストプラクティス準拠を確認し、現在のコードと改善案を示してください。

CLI フラグでセッション限定のサブエージェントを定義することもできます。

claude --agents '{"code-reviewer":{"description":"コードレビュー専門","prompt":"品質とセキュリティに集中","tools":["Read","Grep","Glob"],"model":"sonnet"}}'

Hooks

settings.json の hooks キーに登録します。スキル / エージェントの frontmatter にも記述できます。

{
  "hooks": {
    "EventName": [
      {
        "matcher": "ToolName",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/script.sh",
            "timeout": 60,
            "statusMessage": "検証中..."
          }
        ]
      }
    ]
  }
}

主なライフサイクルイベントは PreToolUse (ツール前・ブロック可) / PostToolUse (ツール成功後) / UserPromptSubmit / Stop / SessionStart / SessionEnd / PreCompact (圧縮前) / PostCompact / SubagentStart / SubagentStop / FileChanged です。これらは一部であり、完全なイベント一覧は公式 Hooks リファレンスを参照してください。

マッチャーは完全一致 ("Bash")、パイプ区切り ("Edit|Write")、正規表現 ("^Notebook")、空文字 (全ツール) を取れます。終了コードは 0 で stdout の JSON を解析、2 でイベント別の確定的ブロック (PreToolUse はツール呼び出しをブロックして stderr を Claude に渡す、Stop は停止を防止、PreCompact は圧縮をブロック) を行い、その他は非ブロッキングエラーとして継続します。

Output styles

.claude/output-styles/<name>.md に置き、本文がシステムプロンプト追加指示になります。

---
name: Diagrams first
description: すべての説明の冒頭に図を提示する
keep-coding-instructions: true
---

コード・アーキテクチャ・データフローを説明するときは、必ず Mermaid 図から始めてください。

keep-coding-instructions: true は応答スタイルだけを変え、コーディング向けデフォルト指示を保持します。省略すると built-in のソフトウェアエンジニアリング指示を引き継ぎません。force-for-plugin はプラグイン有効時の自動適用 (プラグイン専用) です。

System prompt 追加

CLI フラグで呼び出し時に指定します。

追記フラグ (--append-system-prompt 系) は置き換えフラグ (--system-prompt 系) と併用できます。公式ドキュメントは併用時の優先順位や排他を明記していないため、置き換えフラグを複数同時に指定する使い方は避けます。

claude --append-system-prompt "常に型アノテーションを記述する" \
  -p "src/api/users.ts のリファクタリング計画を作成してください"

利用方法

各手段の起動・適用方法をまとめます。

確認・起動コマンド

• /memory: ロード済みの CLAUDE.md・ルール・auto memory を一覧・編集する。
• Skills は /deploy-staging production のようにスラッシュ起動するか、description 一致で自動起動する。ネストは /apps/web:deploy の修飾名で呼ぶ。引数は $ARGUMENTS / $0 / $name で参照する。
• Subagents は description 一致で自動委任される。明示する場合は「Use the code-reviewer agent to analyze src/api/」のように指示する。ネスト深度は最大 5 レベル。/agents で実行状況とライブラリを確認する。
• Hooks は設定後に自動実行され、/hooks で登録済みフックを一覧する。スクリプト内では ${CLAUDE_PROJECT_DIR} / ${CLAUDE_PLUGIN_ROOT} などのパス変数を使える。
• Output styles は /config で切り替え、選択は .claude/settings.local.json の outputStyle に保存される。変更は /clear またはセッション再起動後に反映される。

運用

CLAUDE.md の肥大化管理

CLAUDE.md は毎セッション全文がコンテキストに読み込まれます。肥大化すると重要な指示がノイズに埋もれ、コンテキスト消費が増え、セッション後半のパフォーマンスが下がります。公式の推奨は 1 ファイル 200 行未満で、各行に「これを削除したら Claude が間違えるか」を問い、No なら削ります。

共有リポジトリでは誰も削除しない状態になりがちです。CLAUDE.md にオーナーを置き、コードと同等の変更レビューを行います。ブロックレベルの HTML コメントはコンテキスト投入前に除去されるため、トークンコストなしでメンテナ注記を残せます。

コンテキスト負債のモニタリング

/context でシステムプロンプト・ツール・メモリファイル・スキル・会話履歴別のトークン消費量を確認できます。メモリファイルがセッション開始前に大きな割合を占めていれば見直しが必要です。

コンテキスト汚染の兆候は、同じ失敗を 2 回以上訂正した・Claude が以前の指示に従わなくなった・CLAUDE.md に書いてある事項を Claude が質問してきた、です。これらは長いセッションに蓄積した無関係な情報が原因のことが多く、/clear してより具体的な初期プロンプトで再スタートするのが有効です。

compaction との付き合い方

コンテキストウィンドウが上限に近づくと自動的に圧縮 (compaction) が走り、重要なコードや決定事項を保持しながらスペースを確保します。

compaction 後に確実に再注入したい情報は、SessionStart hook に matcher: "compact" を指定して stdout で渡します。

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          { "type": "command", "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing.'" }
        ]
      }
    ]
  }
}

/compact <instructions> で圧縮対象と保持対象を指示できます。

plugin によるチーム配布・継続的共有

スタンドアロンの .claude/ 設定を plugin として配布すると、複数リポジトリに同一設定を展開できます。

managed-settings.json で enabledPlugins を指定すると、管理者が承認したプラグインのみが有効化され、ユーザーは無効化できません。

ベストプラクティス

使い分け原則の全体図

原則 1: 手順は skill へ (常駐禁止)

CLAUDE.md にデプロイ手順を書くと、関係ない作業のコンテキストも消費し続けます。手順は .claude/skills/<name>/SKILL.md に移し、説明文だけをセッション開始時に常駐させ、本文は呼び出し時のみロードします。

原則 2: 並列分業・調査の孤立は subagent へ

調査タスクを親セッションで行うと、読んだファイルすべてがコンテキストに蓄積します。subagent は独立コンテキストで動作し、最終メッセージ (+ メタデータ) のみを親に返すため、中間の大量ファイル読み込みが親を汚しません。ネスト深度は最大 5 レベルです。

調査系 subagent には Write 権限を与えないと成果物の保存が silent fail することがあります。保存させるなら全ツールを持つ汎用エージェントを使い、直後に ls / Read で実体を確認します。

原則 3: 強制実行は hook へ

CLAUDE.md に「必ず lint を実行してからコミットせよ」と書いても、長いセッションや曖昧な状況、プロンプトインジェクションで従わない可能性があります。「絶対に」が必要なら hook で確定的に実行します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

hook 自体はコンテキストを消費しません。hookSpecificOutput.additionalContext を使った場合のみ、その内容がコンテキストに追加されます。

原則 4: 常駐すべき規約だけ CLAUDE.md へ

原則 5: ファイル固有制約は paths スコープ rule へ

paths: ["src/api/**/*.ts"] のように対象を絞ると、src/api/ 以下を操作するときのみロードされ、無関係な作業ではコンテキストを消費しません。

原則 6: 大幅なロール変更は output style (ただし慎重に)

output style はシステムプロンプトに注入され最高の従属優先度を持ちますが、デフォルト指示 (スコープ・コメント・セキュリティ・確認事項) を上書きします。--append-system-prompt フラグはデフォルトを削除せず追記のみ行う安全な代替ですが、コンテキストコストは高めです。

原則 7: 親セッションに本文を入れない subagent 設計

subagent は独立コンテキストで動き、最終メッセージだけを親に返す設計にします。数十のファイルを読んでも、親セッションは差分と判断結果のみを受け取ります。

トラブルシューティング

誤用→正用の対照表

症状: CLAUDE.md の指示に従わない

1. /memory でファイルがロードされているか確認する。
2. ファイルが正しい場所 (scope) にあるか確認する。
3. 指示をより具体的に書き直す (「コードをきれいに書け」→「2 スペースインデントを使え」)。
4. 複数 CLAUDE.md ファイル間の矛盾を探す。
5. ファイルが 200 行を超えていないか確認する。
6. 必ず守らせたいなら hook に書き換える。

症状: hook が動かない

/hooks で登録を確認し、スクリプトに chmod +x で実行権限を付与します。exit 0 で JSON を返す場合は、シェル起動出力が混入しないよう有効な JSON のみを出力します。managed settings で allowManagedHooksOnly: true の場合、user / project フックは無効化されています。

症状: PreToolUse でブロックしたいが動かない

exit code 2 方式 (シンプル) と JSON 方式 (理由付き) の 2 通りがあります。

#!/bin/bash
COMMAND=$(jq -r '.tool_input.command' < /dev/stdin)
if [[ "$COMMAND" == *"rm -rf"* ]]; then
  echo "Blocked: rm -rf commands are not allowed" >&2
  exit 2
fi
exit 0

#!/bin/bash
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
  jq -n '{hookSpecificOutput: {hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: "Destructive command blocked by hook"}}'
else
  exit 0
fi

exit 2 の場合は JSON 出力が無視されるため、どちらか一方を選びます。優先順位は permissions.deny > hook の exit 2 ブロック > permissions.allow ルールです。

症状: subagent が成果物を保存したと報告するが実体がない

Write 不可のエージェント (例: 読み取り専用の探索エージェント) を使うと保存が silent fail します。保存させるなら全ツールを持つ汎用エージェントを使い、保存後すぐに ls / Read で実体を確認します。

症状: managed settings で設定したが反映されない

managed-only 設定は管理者レベルのファイルにのみ記述できます。user / project の settings.json に書いても効果がありません。

managed-only の主要キーは allowManagedHooksOnly (managed 以外のフックをブロック)、allowManagedPermissionRulesOnly (user / project の permission rule をブロック)、strictPluginOnlyCustomization (カスタマイズを plugin 経由のみに制限) です。

まとめ

Claude Code の 7 つの指示面は、「読込タイミング / 圧縮後の残り方 / 権威の強さ / コンテキストコスト」で性格が分かれます。手順は skill、並列分業は subagent、確定実行は hook、常駐規約だけ CLAUDE.md、ファイル固有制約は path-scoped rule、と置き場を分けると、コンテキスト負債を抑えながら指示の確実性を保てます。「何をコンテキストに載せずに済ませるか」を判断軸にすると、長いセッションでも性能が落ちにくくなります。

この記事が少しでも参考になった、あるいは改善点などがあれば、ぜひリアクションやコメント、SNSでのシェアをいただけると励みになります！

参考リンク

• 公式ブログ
  • Steering Claude Code: skills, hooks, rules, subagents and more (英語)
  • Claude Code の制御方法 (日本語)
• 公式ドキュメント
  • How Claude remembers your project (CLAUDE.md / Auto memory)
  • Extend Claude with skills
  • Create custom subagents
  • Hooks reference
  • Automate actions with hooks (hooks-guide)
  • Output styles
  • Claude Code settings
  • CLI reference
  • Explore the context window
  • Best practices for Claude Code
  • Configure permissions
  • Create plugins
  • Extend Claude Code (features-overview)