Agent SDKのシステムプロンプトをカスタマイズする4つのアプローチ

Agent SDKのシステムプロンプトには3つの出発点がある

Agent SDKで query() を呼ぶとき、システムプロンプト(会話全体でClaudeの振る舞いを決める最初の指示)には3つの出発点があります。systemPrompt を何も指定しなければ、ツール呼び出しの最低限の指示だけを含む最小プロンプトが使われます。セキュリティ・安全性の指示や作業ディレクトリの環境情報は含まれません。これは claude -p の既定(Claude Codeのシステムプロンプトをそのまま使う)とは異なる点で、CLIと同じ挙動に揃えたいなら明示的に claude_code プリセットを指定する必要があります。

2つ目の出発点は claude_code プリセットです。systemPrompt: { type: "preset", preset: "claude_code" }(Pythonは system_prompt={"type": "preset", "preset": "claude_code"})と書くと、Claude Code CLIが使っているのと同じプロンプト(ツール利用ガイド・安全指示・環境コンテキスト)が使われます。3つ目は完全な自作文字列で、SDKは渡した内容だけをそのまま送信します。

どれを選ぶかの判断基準は「自分のエージェントがどれだけClaude Codeに近いか」です。人間が画面を見ながらストリーミング出力を確認し、作業を操縦するコーディングツールに近いほどプリセットが向き、遠いほど自作プロンプトが向きます。

比較対象 — CLAUDE.md・Output Styles・append・カスタムプロンプト

システムプロンプトそのものを直接書き換える手段は3つ(append / Output Styles / カスタム文字列)ですが、実務ではCLAUDE.mdも含めた4つの手段を比較検討することになります。CLAUDE.mdだけは経路が異なり、システムプロンプトではなく会話の中にプロジェクトのコンテキストとして注入されます。そのため、どのシステムプロンプト設定を選んでいてもCLAUDE.mdは並行して効きます。

評価軸 — どの基準で選ぶか

Claude Codeと「違う」と判断する材料は主に4つです。

• 利用形態が違う: 出力がターミナルで操縦する本人に読まれない(チャットUI・構造化出力の消費者・人が介在しない自動化)。ただしlintエラーを直すCIジョブのような無人のコーディング自動化は、作業内容自体がプリセットの想定どおりなのでプリセットのままで合う
• アイデンティティが違う: エージェントの名前や人格がClaude Codeとは別物になる(サポートbot、データ分析アシスタント、ドメイン特化のエージェントなど)
• 権限モデルが違う: 人間が各ステップを承認せず自律的に動く、あるいは扱うリソースが狭い範囲に限られる
• コーディング以外のタスク: プリセットの大半はコーディング向けの指示で、リサーチや文章生成、運用系のエージェントではその指示が本当に必要な指示と競合します

4つのアプローチの比較表

append を使う場合の正式な書き方は systemPrompt: { type: "preset", preset: "claude_code", append: "..." }(Pythonは対応するdict)です。CLAUDE.mdはこの表のどの設定とも独立して動くので、行としては同じ表に並べていますが仕組みは別枠だと覚えておく必要があります。

CLAUDE.mdでプロジェクトの前提を渡す

CLAUDE.mdはプロジェクトに紐づく永続的なコンテキストで、gitでチームと共有でき、コード変更なしに自動検出されます。SDK側では settingSources(Pythonは setting_sources)に読み込みたいレベルを含めるだけで有効になり、'project' はカレントディレクトリの CLAUDE.md / .claude/CLAUDE.md、'user' は ~/.claude/CLAUDE.md を読み込みます。既定では project / user の両方が有効です。明示的に指定した場合は、そこに挙げたレベルだけが読み込まれます(settingSources: ["project"] なら ~/.claude/CLAUDE.md 側は読まれません)。

import { query } from "@anthropic-ai/claude-agent-sdk";
 
for await (const message of query({
  prompt: "Add a new React component for user profiles",
  options: {
    systemPrompt: { type: "preset", preset: "claude_code" },
    settingSources: ["project"]
  }
})) {
  // ...
}

CLAUDE.mdの中身をどう設計するかは、システムプロンプトの選択とは独立した話です。書くべき内容や置き場所はClaude CodeのCLAUDE.mdを実用に引き上げる10のパターンにまとめています。

Output Stylesで永続的な人格を作る

Output Stylesはシステムプロンプトを書き換える設定をMarkdownファイルとして保存し、セッションやプロジェクトをまたいで再利用する仕組みです。~/.claude/output-styles/ に置けば全プロジェクトで、.claude/output-styles/ に置けばそのリポジトリのチームで共有できます。既定では claude_code プリセットのソフトウェアエンジニアリング指示を除いて独自の内容に置き換わり、それらを残したまま上乗せしたい場合はfrontmatterに keep-coding-instructions: true を指定します。有効化には settingSources に 'user' か 'project' のどちらかを含める必要があり、両方とも含めていないとOutput Style自体が読み込まれません。

---
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

TypeScript SDKでは query() に渡す settings オブジェクト内で outputStyle を指定して有効化しますが、keep-coding-instructions: true は環境変数 CLAUDE_CODE_SIMPLE_SYSTEM_PROMPT で短縮版システムプロンプトに切り替えているセッションでは効きません(短縮版自体にソフトウェアエンジニアリング指示が含まれないため、残す対象がありません)。Python SDKにはOutput Styleをプログラムから選択するオプションが無く、コードだけで完結させたい場合は append かカスタムプロンプトに頼ることになります。CLIから使う場合の切り替え手順(/config)はClaude Code output styleの切り替えは/configで行うで扱っています。

appendでclaude_codeプリセットに追記する

claude_code プリセットの内容をすべて残したまま、独自の指示だけを末尾に足したいときは append を使います。組み込み機能を何も削らないため、4つの中で最もリスクの低いカスタマイズです。

options: {
  systemPrompt: {
    type: "preset",
    preset: "claude_code",
    append: "Always include detailed docstrings and type hints in Python code."
  }
}

プロンプトキャッシュを複数セッション間で共有する

claude_code プリセットは、作業ディレクトリやgitリポジトリかどうか、OS、シェルといったセッション固有のコンテキストを append の指示より前に埋め込みます。そのため同じプリセットと同じ append を使っていても、実行するディレクトリが違うだけでシステムプロンプトの中身が変わり、プロンプトキャッシュがヒットしなくなります。多数のエージェントを異なるディレクトリで動かす構成では、これがキャッシュコストに直結します。

excludeDynamicSections: true(Pythonは exclude_dynamic_sections: True)にはSDKバージョン要件があります。TypeScriptは @anthropic-ai/claude-agent-sdk v0.2.98以降、Pythonは claude-agent-sdk v0.1.58以降が必要です。これを設定すると、セッション固有のコンテキストがシステムプロンプトから最初のユーザーメッセージ側に移り、静的なプリセットと append の部分だけが残るため、異なるディレクトリで動く複数のセッションが同じキャッシュエントリを共有できます。この設定はプリセットをオブジェクトで指定した場合にのみ有効で、systemPrompt が文字列のときは効果がありません。トレードオフとして、作業ディレクトリなどの環境情報はユーザーメッセージ側に回るため、システムプロンプトに置くよりもClaudeが軽く扱う可能性があります。キャッシュの再利用がそのコストに見合う場合に使う設定です。

完全カスタムプロンプトに置き換える

systemPrompt に文字列を渡すと、既定のプロンプトを完全に自分の指示だけに置き換えられます。この経路を選ぶと、既定で付いてくるツールガイド・安全指示・環境コンテキストはすべて失われ、必要なものは自分で明記する責任が生じます。制御は最大ですが、その分準備すべきことも最も多い選択肢です。

Pythonでは大きなカスタムプロンプトを文字列で直接渡すと、CLIサブプロセスへの起動引数として渡される都合上、OSの引数長上限を超えて起動そのものに失敗することがあります(Linuxでは Argument list too long)。長いプロンプトは system_prompt={"type": "file", "path": "..."} でファイルから読み込む形にします。

使い分け早見表

アプローチは組み合わせられる

これらの手段は排他的ではありません。Output StylesやCLAUDE.mdで長期的な振る舞いを決め、その上に append でセッション固有の指示を重ねるという組み合わせが典型です。たとえばCode ReviewerというOutput Styleを有効にした状態で、そのセッションだけ「OAuth 2.0への準拠を優先してレビューして」という append を足せば、保存済みの設定自体は変えずに一時的な重点だけを切り替えられます。

よくある質問

CLAUDE.mdとシステムプロンプトはどちらが優先されますか

競合する概念ではありません。CLAUDE.mdは会話の中にプロジェクトコンテキストとして注入され、システムプロンプト(既定・プリセット・カスタムのいずれか)とは別の経路で並行して効きます。

claude_codeプリセットを指定しないとどうなりますか

ツール呼び出しの最低限の指示だけを含む最小プロンプトになります。セキュリティ指示や環境コンテキストは含まれないため、CLIと同じ挙動を期待する場合は明示的にプリセットを指定します。

Output StylesとCLAUDE.mdは何が違いますか

Output Stylesはシステムプロンプトそのものを書き換える設定で、人格や出力形式を変えます。CLAUDE.mdはシステムプロンプトを変えず、プロジェクトの前提知識を会話に足す仕組みです。

excludeDynamicSectionsはどんなときに使いますか

多数のエージェントを異なる作業ディレクトリで動かしていて、プロンプトキャッシュのヒット率を上げたいときに使います。環境情報がユーザーメッセージ側に回るトレードオフを許容できる場合に選びます。

カスタムプロンプトに置き換えてもツールは使えますか

使えます。ただし既定のツールガイドは含まれなくなるため、どのツールを使ってよいか、どう安全に扱うかをプロンプト側に自分で書く必要があります。書き忘れるとエージェントがツールの使いどころを誤ることがあります。

まとめ

Agent SDKのシステムプロンプトは、何もしなければ最小構成、claude_code プリセットでClaude Code相当、カスタム文字列で完全に自分の指示、という3つの出発点から選びます。CLAUDE.mdはこれらと独立した経路で常に並行して効くので、比較表の4手法は「システムプロンプトをどう書くか」、CLAUDE.mdは「会話にどんな前提を足すか」という別の軸だと捉えると迷いません。まずは claude_code プリセット+append から始め、利用形態やアイデンティティがClaude Codeと大きく離れてきた段階でカスタムプロンプトへ移行するのが無理のない順序です。