SpyBara
Go Premium

agent-sdk/modifying-system-prompts.md 2026-09-17 05:00 UTC to 2026-09-18 23:58 UTC

This page contains 52 additions and 35 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Tue 22 23:59

システムプロンプトの変更

claude_code プリセットとカスタムシステムプロンプトの間で選択し、CLAUDE.md、出力スタイル、append、または完全にカスタムなプロンプトで動作をカスタマイズします。

システムプロンプトは Claude の動作、機能、応答スタイルを定義します。人間が作業を監視して操舵する CLI または IDE のようなコーディングツール向けに 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 にどの程度似ているかです：リポジトリで動作するコーディングエージェント。人間がストリーミング出力を監視して作業を指導します。製品がそれから遠いほど、独自のプロンプトを作成する必要があります。

構築しているもの 使用するもの 得られるもの
人間が監視して指導する CLI または IDE のようなコーディングツール。Claude Code のデフォルトが必要なもの claude_code プリセット Claude Code プロンプト（ツールガイダンス、安全ルール、環境コンテキストを含む）
同じ種類のツール、プラス、コーディング標準、出力形式、またはドメインコンテキストなどの製品固有のルール claude_code プリセット（append 付き） 上記のすべて。プリセットの後に命令が追加されます。何も削除されないため、これは最もリスクが低いカスタマイズです
異なるサーフェス、アイデンティティ、または権限モデルを持つエージェント、またはコーディング以外のエージェント カスタムプロンプト文字列 作成したもののみ。エージェントが必要とするツールガイダンスと安全命令を置き換える責任があります
ツール呼び出しループが薄く、エージェントペルソナがなく、ユーザープロンプトですべての動作を提供する systemPrompt オプションなし 最小限のデフォルト：ツール呼び出しサポートのみ

「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 はコーディングエージェントプロンプトとプロジェクトの規約の両方を持ちます。

import { query } from "@anthropic-ai/claude-agent-sdk";

const messages = [];

for await (const message of query({
prompt: "Add a new React component for user profiles",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code" // Use Claude Code's system prompt
},
settingSources: ["project"] // Loads CLAUDE.md from project
}
})) {
messages.push(message);
}

// Now Claude has access to your project guidelines from CLAUDE.md

いずれかの例を実行すると、SDK は Claude が作業する際にメッセージをストリーミングします。システム初期化メッセージ、アシスタントメッセージ、ツール結果を含むユーザーメッセージ、およびセッション結果を含む最終結果メッセージです。

CLAUDE.md はプロジェクト内のすべてのセッションで永続的であり、git を通じてチームと共有され、コード変更なしで自動的に検出されます。空の settingSources 配列を渡す場合は読み込まれません。

永続的な設定のための出力スタイル

出力スタイルは、Claude のロール、トーン、および出力形式を変更する保存された指示セットです。マークダウンファイルとして保存され、セッションとプロジェクト全体で再利用できます。

出力スタイルを作成する

出力スタイルは、メタデータの frontmatter の後にプロンプトコンテンツが続くマークダウンファイルです。すべてのプロジェクトで利用可能なユーザーレベルのスタイルの場合は ~/.claude/output-styles/ に保存し、リポジトリ内のプロジェクトレベルのスタイルの場合は .claude/output-styles/ に保存してチームと共有できます。

カスタム出力スタイルは claude_code プリセットのソフトウェアエンジニアリング指示を除外し、独自のものを使用します。それらを保持し、指示を上に重ねるには、frontmatter で keep-coding-instructions: true を設定します。これらの指示は Claude Code の完全なシステムプロンプトにのみあるため、この設定は CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT でオンまたはオフにピン留めする短いシステムプロンプトのセッションには影響を与えません。エージェントがまだソフトウェアエンジニアリング作業を行っている場合は保持します。ロール全体を置き換える場合は除外します。

以下の例は、コーディング指示を保持するコードレビュー担当者のペルソナを定義します。コードレビューは Claude Code のセキュリティとコード品質ガイダンスから引き続き利益を得るためです。~/.claude/output-styles/code-reviewer.md として保存して、プロジェクト全体で利用可能にします。

---
name: Code Reviewer
description: Thorough code review assistant
keep-coding-instructions: true
---

You are an expert code reviewer.

For every code submission:
1. Check for bugs and security issues
2. Evaluate performance
3. Suggest improvements
4. Rate code quality (1-10)

出力スタイルを有効化する

作成後、出力スタイルは以下を通じて有効化します。

  • 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 フィールドではありません。

    const options = { settings: { outputStyle: "Explanatory" } };

Python SDK では、JSON 文字列（例：'{"outputStyle": "Explanatory"}'）または outputStyle を設定する設定ファイルへのパスを取る settings オプションを通じて outputStyle を設定します。

SDK ユーザーへの注意: 出力スタイルは、オプションに settingSources: ['user'] または settingSources: ['project']（TypeScript）/ setting_sources=["user"] または setting_sources=["project"]（Python）を含める場合に読み込まれます。

`claude_code` プリセットに追加する

Claude Code プリセットを append プロパティと共に使用して、すべての組み込み機能を保持しながらカスタム指示を追加できます。

import { query } from "@anthropic-ai/claude-agent-sdk";

const messages = [];

for await (const message of query({
prompt: "Help me write a Python function to calculate fibonacci numbers",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "Always include detailed docstrings and type hints in Python code."
}
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

ユーザーとマシン全体でプロンプトキャッシングを改善する

デフォルトでは、同じ claude_code プリセットと append テキストを使用する 2 つのセッションは、異なるワーキングディレクトリから実行される場合でも、プロンプトキャッシュエントリを共有できません。これは、プリセットが append テキストの前にシステムプロンプトにセッションごとのコンテキストを埋め込むためです。ワーキングディレクトリ、git リポジトリであるかどうか、プラットフォーム、アクティブなシェル、OS バージョン、および自動メモリパスです。そのコンテキストの違いはシステムプロンプトの違いを生じ、キャッシュミスになります。CLAUDE.md コンテンツはシステムプロンプトに影響を与えません。SDK がそれをシステムプロンプトではなく会話に注入するためです。

セッション全体でシステムプロンプトを同一にするには、TypeScript で excludeDynamicSections: true を設定するか、Python で "exclude_dynamic_sections": True を設定します。セッションごとのコンテキストは最初のユーザーメッセージに移動し、静的プリセットと append テキストのみがシステムプロンプトに残るため、同一の設定はユーザーとマシン全体でキャッシュエントリを共有できます。

次の例は、共有 append ブロックを excludeDynamicSections と組み合わせるため、異なるディレクトリから実行されるエージェントのフリートが同じキャッシュされたシステムプロンプトを再利用できます。

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
prompt: "Triage the open issues in this repo",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: "You operate Acme's internal triage workflow. Label issues by component and severity.",
excludeDynamicSections: true
}
}
})) {
// ...
}

トレードオフ: ワーキングディレクトリ、git リポジトリフラグ、プラットフォーム、アクティブなシェル、OS バージョン、および自動メモリパスは引き続き Claude に到達しますが、システムプロンプトではなく最初のユーザーメッセージの一部として到達します。ユーザーメッセージの指示はシステムプロンプトの同じテキストよりもわずかに低い重みを持つため、Claude は現在のディレクトリまたは自動メモリパスについて推論する際にそれらに依存する可能性が低くなります。セッション間のキャッシュ再利用が最大限に権威あるコンテキストよりも重要な場合、このオプションを有効にします。

非対話型 CLI モードの同等のフラグについては、--exclude-dynamic-system-prompt-sections を参照してください。

カスタムシステムプロンプト

カスタム文字列を systemPrompt として提供して、デフォルトを独自の指示で完全に置き換えることができます。

import { query } from "@anthropic-ai/claude-agent-sdk";

const customPrompt = `You are a Python coding specialist.
Follow these guidelines:
- Write clean, well-documented code
- Use type hints for all functions
- Include comprehensive docstrings
- Prefer functional programming patterns when appropriate
- Always explain your code choices`;

const messages = [];

for await (const message of query({
prompt: "Create a data processing pipeline",
options: {
systemPrompt: customPrompt
}
})) {
messages.push(message);
if (message.type === "assistant") {
console.log(message.message.content);
}
}

Python では、文字列として渡す代わりに 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 が受け入れる形式をリストします。

プロンプトを分割するには、@anthropic-ai/claude-agent-sdk から SYSTEM_PROMPT_DYNAMIC_BOUNDARY をインポートし、2 つの部分の間の配列要素として渡します。SDK はマーカーの前の文字列を 1 つのテキストブロックとして送信し、その後の文字列を 2 番目のブロックとして送信します。各ブロックは独自のキャッシュブレークポイントを持ちます。以下の例では、サポートエージェントがトリアージ指示をファイルから読み込み、各リクエストで 1 つのチケットの詳細を受け取るため、指示はキャッシュされたままでチケットの詳細が変わります。

import { readFile } from "node:fs/promises";
import { query, SYSTEM_PROMPT_DYNAMIC_BOUNDARY } from "@anthropic-ai/claude-agent-sdk";

// Identical on every request
const instructions = await readFile("triage-instructions.md", "utf8");
// Different on every request
const ticketContext = "Customer plan: Enterprise. Other open tickets from this customer: 3.";

for await (const message of query({
  prompt: "Triage ticket 4821",
  options: {
    systemPrompt: [instructions, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, ticketContext]
  }
})) {
  // ...
}

Track cache tokens は各結果メッセージの cache_creation_input_tokens および cache_read_input_tokens フィールドについて説明します。

SDK は配列から次のようにブロックを組み立てます。

  • SDK はマーカーの各側の文字列をそれらの間に空行を入れて結合し、マーカー自体を削除するため、マーカーテキストは Claude に到達しません。
  • マーカーを複数回含める場合、最初のものが分割であり、SDK は他のものを削除します。
  • マーカーを除外する場合、SDK はすべての文字列を 1 つのブロックに結合します。これは 1 つの文字列を渡すのと同じです。

既存のセッションのプロンプトを変更する

デフォルトでは、resume または continue でセッションに戻るときに異なる append またはカスタムプロンプトを渡す場合、Claude は次のターンでそれを見ません。Claude Code はセッションの最初のリクエストでシステムプロンプトを記録し、セッションがコンパクト化されるまでそのレコードを再利用します。新しいテキストはその後のコンパクト化後、または新しいセッションで有効になります。

セッション中に Claude の指示を更新する

システムプロンプトに入れた指示がセッション実行中に変わる必要がある場合（例えば、ユーザーがエージェントを読み取り専用モードに切り替えたり、アプリで設定を編集したりした場合）、systemPrompt を変更する代わりに会話で新しい指示を送信します。

  • 次のメッセージで: 送信する次のユーザーメッセージに新しい指示を含めます。
  • フックから: UserPromptSubmit または PostToolUse hook 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 は効果がありませんでした。

4 つのアプローチすべての比較

4 つのカスタマイズ方法は、どこに存在するか、どのように共有されるか、および claude_code プリセットから何を保持するかが異なります。

機能 CLAUDE.md 出力スタイル systemPrompt を追加 カスタム systemPrompt
永続性 プロジェクトごとのファイル ファイルとして保存 セッションのみ セッションのみ
再利用性 プロジェクトごと プロジェクト全体 コード重複 コード重複
管理 ファイルシステム上 CLI + ファイル コード内 コード内
デフォルトツール 保持 保持 保持 失われる（含まれない限り）
組み込みセキュリティ 維持 維持 維持 追加する必要がある
環境コンテキスト 自動 自動 自動 提供する必要がある
カスタマイズレベル 追加のみ デフォルトを置き換え 追加のみ 完全な制御
バージョン管理 プロジェクトと共に はい コードと共に コードと共に
スコープ プロジェクト固有 ユーザーまたはプロジェクト コードセッション コードセッション

「追加を使用」は 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 とトークン ストレージを優先できます。

import { query } from "@anthropic-ai/claude-agent-sdk";

// "Code Reviewer" 出力スタイルがアクティブであると仮定（/config または settings 経由）
// セッション固有のフォーカス領域を追加
const messages = [];

for await (const message of query({
prompt: "Review this authentication module",
options: {
systemPrompt: {
type: "preset",
preset: "claude_code",
append: `
For this review, prioritize:
- OAuth 2.0 compliance
- Token storage security
- Session management
`
}
}
})) {
messages.push(message);
}

関連項目