Claude Code のシステムプロンプト: --append-system-prompt の使い方

Claude Code には、Claude に渡すシステムプロンプトをコマンドラインから変えるフラグが用意されています。「このスクリプトでは必ず TypeScript で書いてほしい」「出力は決まった形式にしたい」といった実行ごとの指示は、--append-system-prompt で既定のプロンプトの末尾に足すのが基本です。既定のプロンプトを丸ごと差し替える --system-prompt もありますが、こちらはツールの使い方や安全に関する指示まで消えるため、使いどころを選びます。

本記事は公式ドキュメント「CLI reference」の System prompt flags の節と、Agent SDK の「Modifying system prompts」に基づき、各フラグの書き方、追加と置き換えの使い分け、組み合わせ方、再開した会話で変更が反映されるタイミング、プロンプトキャッシュを効かせる書き方を日本語で解説します。

4つのフラグと基本の書き方

システムプロンプトの本文を指定するフラグは4つあります。文字列を直接渡すか、ファイルから読み込むかの違いと、既定のプロンプトに「追加」するか「置き換える」かの違いの組み合わせです。公式によれば、いずれも対話モードと非対話モード（-p）の両方で使えます。

フラグ	動作	例
`--append-system-prompt`	既定のプロンプトの末尾に文字列を追加する	`claude --append-system-prompt "Always use TypeScript"`
`--append-system-prompt-file`	ファイルの内容を既定のプロンプトの末尾に追加する	`claude --append-system-prompt-file ./style-rules.txt`
`--system-prompt`	既定のプロンプト全体を文字列で置き換える	`claude --system-prompt "You are a Python expert"`
`--system-prompt-file`	既定のプロンプト全体をファイルの内容で置き換える	`claude --system-prompt-file ./prompts/review.txt`

これに加えて、会話が最初に記録したプロンプトを使い続けるかどうかを決める --system-prompt-snapshot があり、公式はこれを含めた5つを「System prompt flags」としてまとめています（後述）。

長い指示や複数行のルールは、シェルの引用符の扱いで崩れやすいため、ファイル版のフラグを使うと管理しやすくなります。スクリプトから使う典型的な形は次のとおりです。

claude -p --append-system-prompt "Always reply in Japanese" "Summarize README.md"

追加と置き換えの使い分け

公式の判断基準は「Claude Code の既定の役割がそのタスクに合っているか」です。

追加（append 系）を使う場面: Claude をコーディングアシスタントとして動かしたまま、追加のルールに従わせたいとき。実行ごとの指示、出力形式、-p スクリプト向けのドメイン知識などが該当します。既定のツールの使い方、安全に関する指示、コーディングの慣習はそのまま残るので、違う部分だけを書けば済みます。
置き換え（system-prompt 系）を使う場面: 出力の使われ方、名乗る役割、権限の前提が Claude Code と異なるとき。たとえば人が見ていないパイプラインで動く、コーディング以外のエージェントなどです。置き換えると既定のプロンプトは全部なくなり、ツールの使い方や安全に関する指示も含まれません。タスクに必要な指示は自分で書き足す責任を負います。

Agent SDK のドキュメントでは「Claude Code と違う」の具体例として、出力をターミナルで本人が読まない（チャット UI や構造化出力の消費側）、Claude Code として名乗るべきでない（サポートボットなど）、人が各ステップを承認しない、コーディング以外のタスク、の4つを挙げています。一方で、lint エラーを直す CI ジョブや差分のレビューのような無人のコーディング自動化は、作業内容が既定のプロンプトの想定どおりなので、置き換えずに使う側に入ります。

CLAUDE.md や出力スタイルとの違い

フラグで変えたシステムプロンプトはそのセッション限りです。何度も切り替えて使う人格やチームで共有したい振る舞いには出力スタイル、プロジェクトで常に守らせたい約束事には CLAUDE.md を使うよう公式は案内しています。CLAUDE.md はシステムプロンプトそのものではなく、会話の中にプロジェクトの文脈として渡されるため、どのシステムプロンプトの設定とも併用できます。

フラグを組み合わせる

これらのフラグは同時に指定できます。既定のプロンプトを置き換えたうえで独自の指示を追記したい場合は、--system-prompt または --system-prompt-file に、--append-system-prompt または --append-system-prompt-file を組み合わせます。

Claude Code v2.1.283 以降では、同じ種類の文字列版とファイル版（たとえば --append-system-prompt と --append-system-prompt-file）も併用でき、両方が使われます。公式の例は次のとおりです。

claude -p --append-system-prompt-file ./style.md --append-system-prompt "Always reply in French" "Summarize README.md"

このとき Claude が受け取るのは、既定のシステムプロンプト、style.md の内容、空行、Always reply in French の順です。コマンドラインで --append-system-prompt を先に書いても、ファイルの内容が先に来る点に注意してください。

サブエージェントへの追記

非対話モード（-p）では、サブエージェントのシステムプロンプトにも追記できます。--append-subagent-system-prompt（v2.1.205 以降）と、そのファイル版の --append-subagent-system-prompt-file（v2.1.261 以降）です。入れ子のサブエージェントにも適用されますが、会話自身のプロンプトを再利用するフォーク型のサブエージェントは対象外で、2つのフラグは併用できません。

claude -p --append-subagent-system-prompt "Cite file paths in every answer" "query"

再開した会話での反映タイミング

見落としやすいのが、--resume や --continue で会話を再開したときの挙動です。既定では、Claude Code は会話の最初のリクエストで、フラグの指定を反映したシステムプロンプトを一度だけ組み立ててセッションに記録します。その後のリクエストは、会話がコンパクションされるまで、再開後も含めてこの記録済みのプロンプトを使います。

つまり、再開時に別の文字列を渡しても（あるいはフラグを外しても）、すぐには効きません。新しい指定が反映されるのは、会話がコンパクションされた後か、新しい会話を始めたときです。

--system-prompt-snapshot off で毎回組み立て直す

追記する文言を調整しながら --continue で試すような場面では、--system-prompt-snapshot off を付けると、リクエストのたびにプロンプトを組み立て直します（v2.1.257 以降）。既定値は on です。

claude --append-system-prompt "Draft rules" --system-prompt-snapshot off

Agent SDK のドキュメントは、本番では記録を有効のままにするよう勧めています。記録をオフにして再開した会話のプロンプトが変わると、そのリクエストはセッションのプロンプトキャッシュを再利用できないためです。また、--bare で起動した場合（クラウドセッションを除く）は、--system-prompt-snapshot on を付けない限り記録はオフのままです。会話の途中で指示を変えたいだけなら、システムプロンプトではなく次のメッセージで伝える方法も案内されています。

プロンプトキャッシュを効かせる

同じタスクを多くのユーザーやマシンで流す場合、システムプロンプトの内容が少しでも違うとプロンプトキャッシュを共有できません。公式は2つの手段を用意しています。

ユーザーごとの文脈を外に出す

既定のプロンプトには、auto memory の保存場所のようにユーザーやマシンごとに異なる情報が含まれます。--exclude-dynamic-system-prompt-sections を付けると、こうした情報をシステムプロンプトから最初のユーザーメッセージへ移し、異なるユーザーやマシン間でもキャッシュを再利用しやすくします。既定のシステムプロンプトのときだけ働き、--system-prompt や --system-prompt-file を指定した場合は無視されます。複数ユーザー向けのスクリプト処理で -p と組み合わせて使う想定です。

claude -p --exclude-dynamic-system-prompt-sections "query"

移した内容はユーザーメッセージとして Claude に届くため、システムプロンプトにあるときより auto memory の指示に従う一貫性がわずかに下がる可能性がある、と SDK のドキュメントは注意しています。

置き換えたプロンプトに境界を入れる

置き換え用の文章に「毎回同じ指示」と「実行ごとに変わる文脈」が混ざっている場合は、両者の間に __SYSTEM_PROMPT_DYNAMIC_BOUNDARY__ だけを書いた行を入れます。Claude Code は最初のその行でプロンプトを2つのブロックに分けて行自体を取り除くので、上側は変わらずキャッシュされ、下側だけが変わります（v2.1.275 以降）。

あなたは社内のサポート担当エージェントです。
（毎回同じ指示）
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__
顧客のプラン: Enterprise

ただし、この分割が行われるのは Claude API を直接呼ぶ場合と Claude Platform on AWS で動かす場合だけです。Amazon Bedrock、Google Cloud の Agent Platform、Microsoft Foundry、LLM ゲートウェイ経由などでは、1つのブロックとしてまとめて送られます。プログラムから細かく制御したい場合は Agent SDK の systemPrompt オプションを使う方法もあります。

本記事は Anthropic 公式ドキュメント「CLI reference」（System prompt flags）と「Modifying system prompts」（Agent SDK）に基づく非公式の日本語解説です（確認日 2026-10-06）。仕様やバージョン要件は更新される場合があるため、利用前にCLI リファレンスとシステムプロンプトの変更（Agent SDK）をご確認ください。