SpyBara
Go Premium

agent-sdk/modifying-system-prompts.md 2026-06-09 06:34 UTC to 2026-06-10 23:57 UTC

62 added, 22 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

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

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 に何を入れるか、どこに配置するか、効果的な命令を書く方法については、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 は完全なコーディングエージェントプロンプトとプロジェクトの規約の両方にアクセスできます。

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

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

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

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

出力スタイルを作成する

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

デフォルトでは、カスタム出力スタイルは claude_code プリセットのソフトウェアエンジニアリング命令を独自のもので置き換えます。それらを保持し、命令を上に重ねるには、frontmatter で keep-coding-instructions: true を設定します。エージェントがまだソフトウェアエンジニアリング作業を行っている場合は、それらを保持してください。役割全体を置き換える場合は、それらを除外してください。

以下の例はコードレビュー担当者のペルソナを定義しています。コードレビューは依然として 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 フィールドではありません

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

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 を使用する場合

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 とトークン ストレージを優先することができます：

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

// Assuming "Code Reviewer" output style is active (via /config or settings)
// Add session-specific focus areas
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);
}

関連項目