append-system-promptとsystem-promptの違い(Claude Code)

append-system-promptとsystem-promptの違い

claudeコマンドにはシステムプロンプトをカスタマイズするフラグが5つあり、そのうち4つが実際にテキストを設定します。--append-system-promptはデフォルトのシステムプロンプトの末尾にテキストを追記し、--system-promptはデフォルトのプロンプト全体を渡した文字列で置き換えます。どちらもインタラクティブモードと-p(非インタラクティブ)モードの両方で使えます。

claude --append-system-prompt "Always use TypeScript"

claude --system-prompt "You are a Python expert"

追記か置換かで、Claude Codeのデフォルトの振る舞いをどこまで残すかが決まります。

5つのフラグと役割の対応表

CLIリファレンスは、システムプロンプトを操作するフラグを次の5つに分けています。

テキスト版とファイル版の違いは、コマンドラインに直接書くか、ファイルから読むかだけです。置換系は置換、追記系は追記という挙動は変わりません。長文や共有ルールを置きたいときは、--append-system-prompt-fileが代替手段になります。

置換と追記は組み合わせられます。デフォルトを置き換えたうえで自分のテキストも足したいときは、置換系と追記系を一緒に渡します。置換は--system-promptか--system-prompt-file、追記は--append-system-promptか--append-system-prompt-fileです。

手元のv2.1.287でclaude --helpを絞り込むと、追記と置換の説明は次のように出ます。

claude --help | grep -A1 -e "--append-system-prompt " -e "--system-prompt "

  --append-system-prompt <prompt>       Append a system prompt to the default
                                        system prompt
--
  --system-prompt <prompt>              System prompt to use for the session

どちらを選ぶか

判断の軸は、Claude Codeのデフォルトの人格がその用途に合っているかどうかです。コーディングアシスタントのまま追加ルールを守らせたいなら追記、立場や権限モデルがClaude Codeの前提と違うなら置換です。

永続的なペルソナをプロジェクト内で切り替えたり共有したりしたい場合は、CLIフラグではなくoutput styleが候補です。プロジェクト共通で常に守らせたい規約は、システムプロンプトではなくCLAUDE.mdに書く方法もあります。-pモードでの自動化スクリプト全般の作法はheadless実行のガイドにあります。

テキスト版とファイル版を併用したときの結合順

v2.1.283で、--system-promptと--append-system-promptは、それぞれのテキスト形とファイル形を同時に渡せるように変わりました。両方を渡すと、Claude Codeは両方を使います。

順序はコマンドラインに書いた順では決まりません。--append-system-promptを先に書いても、ファイルの内容が先に並びます。

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

チームで共有するstyle.mdに共通ルールを置き、その場限りの指示だけを直書きで足す使い方になります。

置換するときは「固定部分」と「変わる部分」を分ける

置換用のテキストに、毎回同じ指示と、実行ごとに変わる文脈が混ざることがあります。その間に__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__だけを書いた行を置くと、Claude Codeは最初のその行でプロンプトを分け、その行自体を取り除きます。

You are a support triage agent. Classify each ticket as bug, billing, or how-to.
Reply with one label only.
__SYSTEM_PROMPT_DYNAMIC_BOUNDARY__
Ticket: #4821 — customer reports a duplicate charge

境界より上はキャッシュされたまま残り、下だけが実行ごとに変わります。v2.1.275以降が必要です。同じ動作はTypeScript SDKでは配列形式のSYSTEM_PROMPT_DYNAMIC_BOUNDARYで書けます。Python SDKに配列形式はありません。CLIの--system-prompt系は1つの文字列なので、マーカー行で代用する形です。

同じv2.1.275の更新履歴には、境界行を含む--system-promptで、境界より上のテキストがユーザーやマシンをまたいでキャッシュされるようになったとあります。

Agent SDKでは同じ操作をどう書くか

CLIのフラグには、Agent SDKのsystemPromptオプションに対応する書き方があります。追記はsystemPrompt: { type: "preset", preset: "claude_code", append: "..." }、置換は文字列をそのまま渡す形です。Pythonでファイルを渡すときはsystem_prompt={"type": "file", "path": "..."}と書きます。

systemPromptを指定しないと、SDKはツール呼び出しだけを扱う最小限のプロンプトを使います。claude_codeプリセットにある安全に関する指示などは入りません。この点は、既定でClaude Codeのシステムプロンプトを使うclaude -pとは違います。

CLIのフラグと同名の機能も、SDK側にあります。

• スナップショットの無効化: オブジェクト形でsnapshotをfalseにします。@anthropic-ai/claude-agent-sdkはv0.3.257以降、Pythonのclaude-agent-sdkはv0.2.153以降が必要です
• 動的セクションの除外: TypeScriptではexcludeDynamicSections: true、Pythonでは"exclude_dynamic_sections": Trueを渡します。TypeScript SDKはv0.2.98以降、Pythonはv0.1.58以降で、プリセット形でのみ有効です。カスタム文字列では無視されます

サブエージェントのシステムプロンプトは別フラグ

--append-system-promptと--system-promptが操作するのは、メインの会話のシステムプロンプトです。サブエージェント側を足したいときは--append-subagent-system-prompt(ファイル版は--append-subagent-system-prompt-file)を使います。

ネストしたサブエージェントにも効きますが、会話をフォークしたサブエージェント(forked subagent)は元の会話のプロンプトを引き継ぐため対象外です。非インタラクティブモード(-p)でだけ働きます。ファイル版とテキスト版は同時に使えません。

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

必要なバージョンは、テキスト版がv2.1.205以降、ファイル版がv2.1.261以降です。サブエージェントの定義・並列実行の設計そのものはSub-agents完全ガイドで扱っています。

除外できるのはプロンプトの一部だけ

--exclude-dynamic-system-prompt-sectionsは、追記・置換とは目的が違うフラグです。作業ディレクトリ、環境情報、メモリのパス、git statusといったマシンごとに変わる部分を、システムプロンプトから最初のユーザーメッセージへ移します。同じタスクを複数のユーザーや複数のマシンで実行するとき、プロンプトキャッシュを使い回しやすくなります。

デフォルトのシステムプロンプトを使うときだけ働き、--system-promptまたは--system-prompt-fileを指定していると無視されます。-pと組み合わせる想定のフラグです。--helpの説明はこうです。

  --exclude-dynamic-system-prompt-sections
      Move per-machine sections (cwd, env info, memory paths, git status) from
      the system prompt into the first user message. Improves cross-user
      prompt-cache reuse. Only applies with the default system prompt (ignored
      with --system-prompt). (default: false)

再開したセッションでの挙動 — snapshotフラグの役割

システムプロンプトのカスタマイズで見落としやすいのが、変更が反映されるタイミングです。Claude Codeは既定で、会話の最初のリクエスト時にシステムプロンプトを一度だけ構築し、セッションに記録します。フラグで指定したテキストも、この時点で組み込まれます。

--helpはこの動作を次のように説明しています(v2.1.287)。

  --system-prompt-snapshot <on|off>     Record the system prompt once per
                                        conversation and reuse it verbatim on
                                        every request and resume. on (the
                                        default): the prompt is rendered on the
                                        conversation's first request — a
                                        --system-prompt or
                                        --append-system-prompt included — sent,
                                        and recorded; every later request and
                                        resume sends the record as-is, even when
                                        a later launch passes different text,
                                        until the conversation is compacted.
                                        off: never record; the prompt is
                                        rendered fresh every request (for
                                        iterating on prompt text). No effect
                                        where system-prompt recording is not yet
                                        enabled. (choices: "on", "off")

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

--resumeとの使い分けそのものはresumeとforkの違いで扱っています。

bare mode(--bareまたはCLAUDE_CODE_SIMPLE=1)で起動すると、記録が既定でオフになります。クラウドセッションは対象外です。--system-prompt-snapshot onを明示すれば記録されます。v2.1.268より前は、フィーチャーフラグを取得しないセッションがリクエストのたびにプロンプトを再構築していました。Amazon Bedrock、Google CloudのAgent Platform、Microsoft Foundryのセッションがその例です。この期間、--system-prompt-snapshotは効果を持ちません。

--agentフラグとの違い

混同しやすいのが--agentです。定義済みのエージェントをセッションに選ぶフラグです。--helpの説明は「Agent for the current session. Overrides the 'agent' setting.」です。--system-prompt系は、テキストそのものを渡してプロンプトを組み立てます。

バージョン要件早見表

システムプロンプト関連のフラグは追加された時期がばらばらです。古いClaude Codeでは、一部が使えません。

--system-prompt-snapshotの版数は、公式の2ページで食い違っています。CLIリファレンスはv2.1.257以降と書き、更新履歴で--system-prompt-snapshot offの追加が載っているのはv2.1.267です。v2.1.257からv2.1.266で使えないときは、この差が原因の可能性があります。確実に使うならv2.1.267以降です。

手元の挙動が本記事と違うときは、まずclaude --versionで版を確かめます。更新履歴の追い方はClaude Codeの変更履歴をどこで確認するかにまとめています。

ラッパーやフックから渡すとき

セルフホストランナーでは、v2.1.281からシステムプロンプトがコマンドライン上の文字列ではなく非公開のファイルとして渡されます。長いプロンプトで起動に失敗する問題を避けるための変更です。ラッパーやcommandフックが--system-promptや--append-system-promptを付け足しているなら、切り替えが必要です。ファイル版の--system-prompt-fileか--append-system-prompt-fileを使います。

まとめ

追記か置換かは二択ではなく、置換したうえで追記を足す組み合わせもあります。CLIからSDKへ処理を移すときは、systemPromptを省くとclaude_codeプリセットの安全指示が入らない点が判断の分かれ目になります。