claude_code プリセットから始めます。異なるサーフェス、アイデンティティ、またはパーミッションモデルを持つエージェント向けに独自のプロンプトを作成します。
このページでは以下をカバーしています:
- システムプロンプトの仕組み。プリセット、プリセットと
appendの組み合わせ、カスタムプロンプトの間で選択するための決定テーブル付き - エージェントの動作をカスタマイズする方法。CLAUDE.md ファイル、出力スタイル、
append、またはカスタム文字列を使用 - 4 つのアプローチを比較する方法。永続性、スコープ、および保持される内容による比較
- アプローチを組み合わせてカスタマイズ方法を重ねる方法
システムプロンプトの仕組み
システムプロンプトは、会話全体を通じて 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.md は異なるパスを取ります。SDK がそれを読み込み、システムプロンプトではなくプロジェクトコンテキストとして会話に内容を注入するため、選択したシステムプロンプトに関係なく動作を形作ります。Skills、hooks、およびpermissionsもシステムプロンプト外で動作を形作り、独自のページで説明されています。
プロジェクトレベルの命令用の CLAUDE.md ファイル
CLAUDE.md ファイルは Claude に永続的なプロジェクトコンテキストと命令を提供します。SDK は会話に内容を注入し、システムプロンプトには注入しないため、任意のシステムプロンプト設定で機能します。CLAUDE.md に何を入れるか、どこに配置するか、効果的な命令を書く方法については、Claude がプロジェクトを記憶する方法を参照してください。このセクションでは 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.md を claude_code プリセットと共に読み込むため、Claude は完全なコーディングエージェントプロンプトとプロジェクトの規約の両方にアクセスできます。
settingSources 配列を渡す場合は読み込まれません。
永続的な設定のための出力スタイル
出力スタイルは Claude のシステムプロンプトを変更する保存された設定です。マークダウンファイルとして保存され、セッションとプロジェクト全体で再利用できます。出力スタイルを作成する
出力スタイルは、frontmatterのメタデータを含むマークダウンファイルで、その後にプロンプトコンテンツが続きます。すべてのプロジェクトで利用可能なユーザーレベルのスタイルの場合は~/.claude/output-styles/ に保存するか、チームと共有してコミットできるプロジェクトレベルのスタイルの場合はリポジトリの .claude/output-styles/ に保存します。
デフォルトでは、カスタム出力スタイルは claude_code プリセットのソフトウェアエンジニアリング命令を独自のもので置き換えます。それらを保持し、命令を上に重ねるには、frontmatter で keep-coding-instructions: true を設定します。エージェントがまだソフトウェアエンジニアリング作業を行っている場合は、それらを保持してください。役割全体を置き換える場合は、それらを除外してください。
以下の例はコードレビュー担当者のペルソナを定義しています。コードレビューは依然として Claude Code のセキュリティとコード品質ガイダンスの恩恵を受けるため、コーディング命令を保持します。プロジェクト全体で利用可能にするために ~/.claude/output-styles/code-reviewer.md として保存します。
~/.claude/output-styles/code-reviewer.md
出力スタイルをアクティブ化する
作成後、以下を通じて出力スタイルをアクティブ化します。-
CLI:
/configを実行し、出力スタイルを選択 -
設定:
.claude/settings.local.jsonでoutputStyleを設定 -
TypeScript SDK:
query()に渡されるインラインのsettingsオブジェクト内でoutputStyleを設定するか、settingsをoutputStyleを設定する設定ファイルに指定します。outputStyleはトップレベルのOptionsフィールドではありません:
.claude/settings.local.json に書き込めないコードのみのデプロイメントの場合は、append またはカスタムプロンプト文字列を代わりに使用してください。
SDK ユーザーへの注記: 出力スタイルは、オプションに settingSources: ['user'] または settingSources: ['project'](TypeScript)/ setting_sources=["user"] または setting_sources=["project"](Python)を含める場合に読み込まれます。
claude_code プリセットに追加する
Claude Code プリセットを append プロパティと共に使用して、カスタム命令を追加しながら、すべての組み込み機能を保持できます。
ユーザーとマシン全体でプロンプトキャッシングを改善する
デフォルトでは、同じclaude_code プリセットと append テキストを使用する 2 つのセッションでも、異なる作業ディレクトリから実行される場合、プロンプトキャッシュエントリを共有することはできません。これは、プリセットが append テキストの前のシステムプロンプトにセッションごとのコンテキストを埋め込むためです。作業ディレクトリ、git リポジトリであるかどうか、プラットフォーム、アクティブなシェル、OS バージョン、および自動メモリパスです。そのコンテキストに違いがあると、異なるシステムプロンプトが生成され、キャッシュミスが発生します。CLAUDE.md コンテンツはシステムプロンプトに影響しません。SDK がそれを会話に注入し、システムプロンプトには注入しないためです。
セッション全体でシステムプロンプトを同じにするには、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 以降が必要です。プリセットオブジェクト形式にのみ適用され、systemPrompt が文字列の場合は効果がありません。append ブロックを excludeDynamicSections と組み合わせているため、異なるディレクトリから実行されるエージェントのフリートが同じキャッシュされたシステムプロンプトを再利用できます。
--exclude-dynamic-system-prompt-sectionsを参照してください。
カスタムシステムプロンプト
カスタム文字列をsystemPrompt として提供して、デフォルトを完全に独自の命令に置き換えることができます。
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 を使用する場合
CLAUDE.md は、セッションで使用されるシステムプロンプトに関係なく、プロジェクト内のすべてのセッションに適用すべき命令に使用します。コーディング標準、一般的なコマンド、アーキテクチャコンテキスト、チーム規約などです。CLAUDE.md はリポジトリにコミットされるため、それが説明するコードと同期を保ちます。詳細なガイダンスについては、CLAUDE.md に追加する場合を参照してください。 CLAUDE.md ファイルはproject 設定ソースが有効な場合に読み込まれます。これはデフォルトの query() オプションの場合です。TypeScript で settingSources または Python で setting_sources を明示的に設定する場合は、プロジェクトレベルの CLAUDE.md の読み込みを続けるために 'project' を含めてください。
出力スタイルを使用する場合
出力スタイルは、アプリケーションコードを変更することなく CLI と SDK 全体で再利用したいペルソナ用です。.claude/output-styles 内のファイルとして存在するため、同じペルソナは CLI の /config から、および一致する設定ソースを読み込むすべての SDK セッションから利用できます。
最適な用途:
- セッション全体での永続的な動作変更
- チーム共有設定
- コードレビュアー、データサイエンティスト、DevOps アシスタントなどの特殊なアシスタント
- バージョン管理が必要な複雑なプロンプト変更
- 専用 SQL 最適化アシスタントの作成
- セキュリティ重視のコードレビュアーの構築
- 特定の教育学を持つティーチングアシスタントの開発
systemPrompt を追加で使用する場合
claude_code プリセットがすでに製品に適合しており、追加の命令をレイヤーするだけで済む場合は、append を使用します。プリセットのツールガイダンス、安全ルール、コーディング規約を再実装することなく保持します。
最適な用途:
- 特定のコーディング標準または設定の追加
- 出力フォーマットのカスタマイズ
- ドメイン固有の知識の追加
- 応答詳細度の変更
- ツール命令を失わずに Claude Code のデフォルト動作を強化する
カスタム systemPrompt を使用する場合
開始点を決定するで説明されているように、エージェントのサーフェス、アイデンティティ、または権限モデルが Claude Code のものと異なる場合は、カスタムプロンプトを使用します。ツールガイダンスと安全ルールを含む、エージェントが必要とする完全な命令セットを定義します。
最適な用途:
- Claude の動作を完全に制御
- 特殊なシングルセッションタスク
- 新しいプロンプト戦略のテスト
- デフォルトツールが不要な状況
- ユニークな動作を持つ特殊なエージェントの構築
アプローチの組み合わせ
これらのメソッドは組み合わせることができます。永続的な出力スタイルまたは 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リファレンス