SpyBara
Go Premium

agent-sdk/modifying-system-prompts.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 103 additions and 91 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.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.md を claude_code プリセットと共に読み込むため、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：/config を実行し、出力スタイルを選択

  • 設定：.claude/settings.local.json で outputStyle を設定

  • TypeScript SDK：query() に渡されるインラインの settings オブジェクト内で outputStyle を設定するか、settings を outputStyle を設定する設定ファイルに指定します。outputStyle はトップレベルの Options フィールドではありません。

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

Python SDK には、出力スタイルをプログラムで選択するオプションはありません。.claude/settings.local.json に書き込めないコードのみのデプロイメントの場合は、append またはカスタムプロンプト文字列を代わりに使用してください。

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 では利用できません。Python SDK の 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 つの文字列を渡すのと同じです。

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);
}

関連項目