claude_code プリセットから始めます。異なるサーフェス、アイデンティティ、またはパーミッションモデルを持つエージェント向けに独自のプロンプトを作成します。
システムプロンプトの仕組み
システムプロンプトは、会話全体を通じて Claude の動作方法を形作る初期命令セットです。Agent SDK には、これに対する 3 つの開始点があります:- 最小限のデフォルト:TypeScript で
systemPromptを設定しない、または Python でsystem_promptを設定しない場合、SDK はツール呼び出しをカバーする最小限のプロンプトを使用しますが、claude_codeプリセットの残りのコンテンツ(セキュリティと安全性の命令を含む)は省略されています。これは、デフォルトで Claude Code システムプロンプトを使用するclaude -pとは異なります。CLI から移行していて、一致する動作を望む場合は、claude_codeプリセットを設定してください。 claude_codeプリセット:Claude Code CLI が使用するシステムプロンプト。ツール使用命令、セキュリティと安全性の命令が含まれています。TypeScript でsystemPrompt: { type: "preset", preset: "claude_code" }を設定するか、Python でsystem_prompt={"type": "preset", "preset": "claude_code"}を設定してください。オプションでappendを使用して、最後に独自の命令を追加できます。- カスタム文字列:自分で作成したプロンプト。SDK は提供したものだけを送信します。
開始点を決定する
決定要因は、エージェントが Claude Code にどの程度似ているかです:リポジトリで動作するコーディングエージェント。人間がストリーミング出力を監視して作業を指導します。製品がそれから遠いほど、独自のプロンプトを作成する必要があります。
「Claude Code と異なる」は通常、以下のいずれかを意味します:
- 異なるサーフェス:出力は、それをトリガーした人によってターミナルで読まれません。チャット UI、構造化出力コンシューマー、およびコーディング以外の自動化は、それぞれ、出力がどのようにレンダリングおよびレビューされるかに一致するプロンプトが必要です。CI ジョブがリントエラーを修正したり、diff をレビューしたりするような無人コーディング自動化は、作業自体がプリセットが書かれているものであるため、プリセットに適合します。
- 異なるアイデンティティ:エージェントは Claude Code として自分自身を提示すべきではありません。サポートボット、データ分析アシスタント、またはドメイン固有のエージェントは、独自の名前、スコープ、およびペルソナが必要です。
- 異なる権限モデル:エージェントは人間が各ステップを承認することなく自律的に実行されるか、リソースの限定されたセットで動作します。Claude Code のプロンプトは、人間がループ内にいて、完全なツールセットにアクセスできることを前提としています。
- コーディング以外のタスク:Claude Code のプロンプトのほとんどはコーディングガイダンスです。研究、コンテンツ、または運用エージェントの場合、そのガイダンスは実際に必要な命令と競合します。
エージェントの動作をカスタマイズする
append とカスタムプロンプト文字列はそれぞれシステムプロンプトを直接変更し、出力スタイルは Claude Code がすべてのレスポンスに対して Claude に与える指示を変更します。CLAUDE.md は異なるパスを取ります。SDK がそれを読み込み、その内容をプロジェクトコンテキストとして会話に注入するため、選択したシステムプロンプトと一緒に動作を形作ります。Skills、hooks、および permissions もシステムプロンプト外で動作を形作り、独自のページで説明されています。
プロジェクトレベルの指示のための CLAUDE.md ファイル
CLAUDE.md ファイルは Claude に永続的なプロジェクトコンテキストと指示を提供します。SDK はその内容を会話に注入し、システムプロンプトはそのままにするため、どのシステムプロンプト設定でも機能します。CLAUDE.md に何を入れるか、どこに配置するか、効果的な指示を書く方法については、When to add to CLAUDE.md および How Claude remembers your project の残りの部分を参照してください。このセクションでは SDK に固有のもの、つまり CLAUDE.md がどのように読み込まれるかについて説明します。 SDK は、一致する設定ソースが有効な場合に CLAUDE.md を読み込みます。'project' はワーキングディレクトリから CLAUDE.md または .claude/CLAUDE.md を読み込み、'user' は ~/.claude/CLAUDE.md を読み込みます。デフォルトの query() オプションは両方のソースを有効にするため、CLAUDE.md は自動的に読み込まれます。TypeScript で settingSources または Python で setting_sources を明示的に設定する場合は、必要なソースを含めてください。CLAUDE.md の読み込みは設定ソースによって制御され、claude_code プリセットによっては制御されません。
SDK で CLAUDE.md を読み込む
CLAUDE.md を読み込むには、settingSources を CLAUDE.md を保持するレベルを含むように設定します。以下の例は、claude_code プリセットと一緒にプロジェクトレベルの CLAUDE.md を読み込むため、Claude はコーディングエージェントプロンプトとプロジェクトの規約の両方を持ちます。
settingSources 配列を渡す場合は読み込まれません。
永続的な設定のための出力スタイル
出力スタイルは、Claude のロール、トーン、および出力形式を変更する保存された指示セットです。マークダウンファイルとして保存され、セッションとプロジェクト全体で再利用できます。出力スタイルを作成する
出力スタイルは、メタデータの frontmatter の後にプロンプトコンテンツが続くマークダウンファイルです。すべてのプロジェクトで利用可能なユーザーレベルのスタイルの場合は~/.claude/output-styles/ に保存し、リポジトリ内のプロジェクトレベルのスタイルの場合は .claude/output-styles/ に保存してチームと共有できます。
カスタム出力スタイルは claude_code プリセットのソフトウェアエンジニアリング指示を除外し、独自のものを使用します。それらを保持し、指示を上に重ねるには、フロントマターで keep-coding-instructions: true を設定します。これらの指示は Claude Code の完全なシステムプロンプトにのみ含まれるため、短いシステムプロンプトのセッションではこの設定は効果がありません。どのモデルでも完全なプロンプトを選択するには、CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT を 0 に設定します。エージェントがまだソフトウェアエンジニアリング作業を行っている場合は保持します。ロール全体を置き換える場合は除外します。
以下の例は、コーディング指示を保持するコードレビュー担当者のペルソナを定義します。コードレビューは Claude Code のセキュリティとコード品質ガイダンスから引き続き利益を得るためです。~/.claude/output-styles/code-reviewer.md として保存して、プロジェクト全体で利用可能にします。
~/.claude/output-styles/code-reviewer.md
出力スタイルを有効化する
作成後、出力スタイルは以下を通じて有効化します。-
CLI:
/output-style <style>を実行します。例えば/output-style conciseを実行するか、/configを実行してスタイルを選択します。/output-styleコマンドには Claude Code v2.1.269 以降が必要です。 -
Settings:
.claude/settings.local.jsonでoutputStyleを設定します。 -
TypeScript SDK:
query()に渡されるインラインsettingsオブジェクト内でoutputStyleを設定するか、settingsをoutputStyleを設定する設定ファイルにポイントします。outputStyleはトップレベルのOptionsフィールドではありません。
'{"outputStyle": "Explanatory"}')または outputStyle を設定する設定ファイルへのパスを取る settings オプションを通じて outputStyle を設定します。
SDK ユーザーへの注意: 出力スタイルは、オプションに settingSources: ['user'] または settingSources: ['project'](TypeScript)/ setting_sources=["user"] または setting_sources=["project"](Python)を含める場合に読み込まれます。
claude_code プリセットに追加する
Claude Code プリセットを append プロパティと共に使用して、すべての組み込み機能を保持しながらカスタム指示を追加できます。
ユーザーとマシン全体でプロンプトキャッシングを改善する
デフォルトでは、同じclaude_code プリセットと append テキストを使用する 2 つのセッションは、自動メモリの場所が異なる場合、プロンプトキャッシュエントリを共有できません。プリセットは append テキストの前にシステムプロンプトにその場所を埋め込みます。場所はデフォルトで ~/.claude/projects/ の下の絶対パスであり、ディスク上のリポジトリのパスに基づいて名前が付けられるため、ユーザー、マシン、チェックアウト全体で異なります。
CLAUDE.md コンテンツおよびワーキングディレクトリ、プラットフォーム、シェル、OS バージョンなどの環境詳細は、Claude Code がそれらをシステムプロンプトではなく会話で配信するため、システムプロンプトキャッシュに影響を与えません。
セッション全体でシステムプロンプトを同一にするには、TypeScript で excludeDynamicSections: true を設定するか、Python で "exclude_dynamic_sections": True を設定します。ユーザーごとのコンテキストは最初のユーザーメッセージに移動し、静的プリセットと append テキストのみがシステムプロンプトに残るため、同一の設定はユーザーとマシン全体でキャッシュエントリを共有できます。
excludeDynamicSections には @anthropic-ai/claude-agent-sdk v0.2.98 以降、または Python の場合は claude-agent-sdk v0.1.58 以降が必要です。プリセットオブジェクト形式でのみ設定します。SDK はカスタムプロンプトの代わりにプリセットを渡す場合、それを無視します。カスタムプロンプトの指示を TypeScript SDK でキャッシュに保つには、Cache the static part of a custom prompt を参照してください。append ブロックを excludeDynamicSections と組み合わせるため、エージェントのフリートが同じキャッシュされたシステムプロンプトを再利用できます。
--exclude-dynamic-system-prompt-sections を参照してください。
カスタムシステムプロンプト
カスタム文字列をsystemPrompt として提供して、デフォルトを独自の指示で完全に置き換えることができます。
system_prompt={"type": "file", "path": "..."} を使用してファイルから大きなカスタムプロンプトを読み込みます。Python SDK は文字列プロンプトを CLI サブプロセスへの 1 つのコマンドライン引数として渡すため、OS 引数長制限を超えるプロンプトはプロセス生成時に失敗し、API リクエストが送信される前に失敗します。Linux ではエラーは Argument list too long です。プラットフォームのしきい値と Windows の動作については、SystemPromptFile を参照してください。
カスタムプロンプトの静的部分をキャッシュする
TypeScript SDK では、カスタムプロンプトを 1 つの文字列ではなく文字列の配列として渡すことができます。静的部分と残りの部分の間にSYSTEM_PROMPT_DYNAMIC_BOUNDARY マーカーを付けます。プロンプトが、すべてのリクエストで同じ指示とリクエストごとに変わるコンテキスト(エージェントが処理しているカスタマーまたはチケットなど)を組み合わせる場合に使用します。両方の部分を 1 つの文字列として渡す場合、リクエストごとの部分への変更は全体のシステムプロンプトを変更するため、静的指示もキャッシュを逃します。配列形式は Python SDK では利用できません。ClaudeAgentOptions は system_prompt が受け入れる形式をリストします。
SDK は Claude API を直接呼び出すか、Claude Platform on AWS で実行する場合にのみプロンプトを分割します。Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、または LLM gateway など、その他のすべての設定では、
CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1 を設定するたびに、SDK は全体のプロンプトを 1 つのブロックとして送信します。これは 1 つの文字列を渡すのと同じです。@anthropic-ai/claude-agent-sdk から SYSTEM_PROMPT_DYNAMIC_BOUNDARY をインポートし、2 つの部分の間の配列要素として渡します。SDK はマーカーの前の文字列を 1 つのテキストブロックとして送信し、その後の文字列を 2 番目のブロックとして送信します。各ブロックは独自のキャッシュブレークポイントを持ちます。以下の例では、サポートエージェントがトリアージ指示をファイルから読み込み、各リクエストで 1 つのチケットの詳細を受け取るため、指示はキャッシュされたままでチケットの詳細が変わります。
TypeScript
cache_creation_input_tokens および cache_read_input_tokens フィールドについて説明します。
SDK は配列から次のようにブロックを組み立てます。
- SDK はマーカーの各側の文字列をそれらの間に空行を入れて結合し、マーカー自体を削除するため、マーカーテキストは Claude に到達しません。
- マーカーを複数回含める場合、最初のものが分割であり、SDK は他のものを削除します。
- マーカーを除外する場合、SDK はすべての文字列を 1 つのブロックに結合します。これは 1 つの文字列を渡すのと同じです。
--system-prompt または --system-prompt-file フラグ では、プロンプトは 1 つの文字列であるため、マーカーを含む配列はありません。静的部分とリクエストごとの部分の間に __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ のみを含む行を含めます。Claude Code はプロンプトを最初のそのような行で同じ 2 つのブロックに分割し、その行を削除します。Claude Code v2.1.275 以降が必要です。
SDK では、配列形式を推奨します。これはマーカー行なしで境界を含みます。
既存のセッションのプロンプトを変更する
デフォルトでは、resume または continue でセッションに戻るときに異なる append またはカスタムプロンプトを渡す場合、Claude は次のターンでそれを見ません。Claude Code はセッションの最初のリクエストでシステムプロンプトを記録し、セッションがコンパクト化されるまでそのレコードを再利用します。新しいテキストはその後のコンパクト化後、または新しいセッションで有効になります。
セッション中に Claude の指示を更新する
システムプロンプトに入れた指示がセッション実行中に変わる必要がある場合(例えば、ユーザーがエージェントを読み取り専用モードに切り替えたり、アプリで設定を編集したりした場合)、systemPrompt を変更する代わりに会話で新しい指示を送信します。
- 次のメッセージで: 送信する次のユーザーメッセージに新しい指示を含めます。
- フックから:
UserPromptSubmitまたはPostToolUsehook callback からadditionalContextを返します。「ワークスペースは読み取り専用になりました」などの事実上の声明として書かれています。SDK はフックが発火した時点で会話にテキストを挿入するため、記録されたプロンプトは変わりません。
単語遣いを反復処理する際に記録をオフにする
プロンプト単語遣いを反復処理し、各編集が再開するセッションに到達するようにしたい場合、システムプロンプトのオブジェクト形式でsnapshot を false に設定します。Claude Code はすべてのリクエストでプロンプトを再構築します。このフィールドは TypeScript の systemPrompt のプリセットおよびカスタム形式、および Python の system_prompt で利用可能であり、@anthropic-ai/claude-agent-sdk v0.3.257 以降、または claude-agent-sdk v0.2.153 以降が必要です。
本番環境では記録をオンのままにしてください。記録がオフの場合、再開されたセッションの異なる append またはカスタムプロンプトは次のターンで Claude に到達し、そのリクエストはセッションの prompt cache を再利用できません。API が preserved thinking を強制する場合、Claude は以前のターンからの思考も失います。
cloud sessions の外で、extraArgs を通じて --bare を渡すか、CLAUDE_CODE_SIMPLE=1 を設定することで Claude Code を bare mode で開始する場合、snapshot: true を設定しない限り、記録はオフのままです。
append またはカスタムプロンプトを記録するには、デフォルトで Claude Code v2.1.265 以降が必要です。TypeScript Agent SDK は v0.3.265 から、Python Agent SDK は v0.2.153 からバンドルされています。Claude Code v2.1.268 より前では、feature flags をフェッチしないセッション(Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry のセッションを含む)はすべてのリクエストでプロンプトを再構築し、snapshot は効果がありませんでした。
Claude Code がシステムプロンプト外に追加するコンテキスト
システムリマインダーは、Claude Code がセッション中に会話に追加するメッセージで、CLAUDE.md ファイルの内容やファイルがディスク上で変更されたというメモなど、Claude にコンテキストを提供します。Claude Code はシステムプロンプトではなく会話内でそれらを送信するため、claude_code プリセットを使用するか、systemPrompt として独自の文字列を渡すかに関わらず、そのほとんどは Claude に到達します。
このセクションでは、エージェントの動作を変更する可能性が最も高いリマインダー、エージェントが置き換えるコンテキストをオフにする方法、および特定のリクエストで Claude が受け取ったものを確認する方法について説明します。
Claude Code が会話に追加するリマインダー
システムリマインダーは、Claude Code がコードが送信するプロンプトと一緒に会話に追加するテキストです。以下のリマインダーは、エージェントの動作を変更する可能性が最も高いものです。- プロジェクト指示:
settingSourcesオプションが読み込む CLAUDE.md ファイル - 出力スタイル指示: メイン会話内のアクティブな出力スタイルの指示
- コミットおよびプルリクエスト属性:
attribution設定からのCo-Authored-Byトレーラーおよびプルリクエストフッター - フック出力: フックが
additionalContextとして返すテキスト - 利用可能なスキル: Claude が呼び出せるスキルの名前と説明
- 利用可能なサブエージェント: Claude が開始できるサブエージェントの名前と説明
- タスクリストナッジ: タスク追跡ツールを持つセッションでは、Claude が数ターン間タスクリストに触れていない場合、タスクリストを更新するようプロンプトします
- ファイル変更メモ: Claude が以前読み込んだファイルがディスク上で変更されたというメモ
systemPrompt として独自の文字列を渡す場合は、システムリマインダーが何であるかを説明する文を追加してください。claude_code プリセットには 1 つあり、独自の文字列がプリセット全体を置き換えます。これがないと、CLAUDE.md コンテンツやフック出力などのリマインダーがアプリケーションからのものであり、ユーザーからのものではないことを、プロンプト内の何も Claude に伝えません。例えば:
エージェントが置き換えるコンテキストをオフにする
エージェントが同じガイダンスの独自バージョンを提供する場合、組み込みコンテキストの一部をオフにします。例えば、プロンプトが Claude にPROJ-142: fix login redirect としてコミットメッセージを書くよう指示し、トレーラーがない場合、Claude Code は依然として Claude に各コミットメッセージを Co-Authored-By トレーラーで終わるよう指示するため、Claude は同じコミットに対して 2 つの矛盾した指示を受け取ります。
TypeScript では settings オプションを通じて設定キーを渡し、Python では settings を通じて渡し、env オプションを通じて環境変数を渡します。TypeScript では、env は継承された環境を置き換えるため、process.env をそこに展開します。
組み込みのコミットおよびプルリクエスト指示を除外するには、
includeGitInstructions を false に設定します。これらの指示は Bash ツールの説明の一部であり、カスタム systemPrompt を使用する場合でも Claude に到達します。ただし、最小限のデフォルト、カスタム systemPrompt、または独自のプロンプトを持つカスタムメインスレッドエージェントを使用する場合、セッションは git ステータススナップショットなしで開始されます。
CLAUDE_CODE_DISABLE_ATTACHMENTS を設定する場合、Claude Code は @ ファイルメンションをプレーンテキストとして送信し、ファイルコンテンツに展開しません。利用可能なサブエージェントのリストとバックグラウンドタスク通知は依然として到達します。@ ファイルメンションの展開のみを停止するには、Claude Code v2.1.299 以降で代わりに CLAUDE_CODE_DISABLE_FILE_MENTIONS=1 を設定します。その場合、Claude はメンションされたパスと、ファイルツールでそれらを読み込むよう促すメモを受け取ります。
以下の例は、append に独自のコミットルールを持つエージェント用です。トレーラーとフッターを削除するために両方の attribution キーを空の文字列に設定し、includeGitInstructions をオフにして、Claude Code 独自のコミットワークフロー指示があなたのものと競合しないようにします。
git log -1 で新しいコミットを確認します。メッセージは Co-Authored-By トレーラーなしで終わります。
Claude が受け取ったものを確認する
SDK メッセージストリームはシステムリマインダーを含まないため、コードが受け取るメッセージを読むことで、Claude が何を見たかは表示されません。それらを確認するには、Claude Code が送信するリクエストをログに記録します。- 生のリクエストログ:
OTEL_LOG_RAW_API_BODIESをfile:<dir>に設定します。Claude Code は各リクエストボディをそのディレクトリに書き込みます。 - 制御するゲートウェイ:
ANTHROPIC_BASE_URLをリクエストボディをログに記録するプロキシに指定します。
messages 配列を確認します。リマインダーは <system-reminder> タグでラップされたユーザーメッセージ内に表示されるか、一部のモデルでは system ロールを持つ別のメッセージとして表示されます。
4 つのアプローチすべての比較
4 つのカスタマイズ方法は、どこに存在するか、どのように共有されるか、およびclaude_code プリセットから何を保持するかが異なります。
「追加を使用」は TypeScript で
systemPrompt: { type: "preset", preset: "claude_code", append: "..." } を使用するか、Python で system_prompt={"type": "preset", "preset": "claude_code", "append": "..."} を使用することを意味します。CLAUDE.md はシステムプロンプト自体を変更しません。SDK はそのコンテンツをプロジェクトコンテキストとして会話に注入します。
アプローチを組み合わせる
これらのアプローチは組み合わせることができます。永続的な出力スタイルまたは CLAUDE.md は長期的な動作を設定し、append はセッション固有の指示を保存された設定に触れることなく上に重ねます。
出力スタイルとセッション固有の追加を組み合わせる
以下の例は、Code Reviewer 出力スタイルが既にアクティブであることを想定しています。append ブロックはセッション固有のフォーカス領域をペルソナの上に重ねるため、単一のレビュー セッションで保存された出力スタイルを変更することなく OAuth とトークン ストレージを優先できます。
関連項目
- 出力スタイル:CLI の出力スタイルを作成、管理、共有します。ファイル形式とストレージの場所を含みます
- Claude がプロジェクトを記憶する方法:CLAUDE.md に何を入れるか、どこに配置するか、効果的なプロジェクト指示の書き方
- TypeScript SDK リファレンス:
systemPrompt、settingSources、settingsを含む完全なOptions型 - Python SDK リファレンス:
system_promptとsetting_sourcesを含む完全なClaudeAgentOptions型 - 設定:出力スタイルおよび他の設定が保存される場所を含む
settings.jsonリファレンス