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のデフォルトの振る舞いをどこまで残すかに直結します。--append-system-promptはツールの使い方に関するガイダンス、安全に関する指示、コーディング規約といったデフォルトプロンプトの中身をすべて維持したうえで、指定したテキストを末尾に足すだけです。一方--system-promptはデフォルトプロンプトを丸ごと捨てて、渡した文字列だけがシステムプロンプトになります。

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

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

--system-promptと--system-prompt-fileは同時に指定できません(相互排他)。テキストをコマンドライン上に直接書くか、ファイルから読み込むかの違いだけで、置換という挙動自体は同じだからです。これに対して追記系の2フラグは、どちらの置換フラグとも組み合わせられます。つまり「プロンプトを丸ごと置き換えたうえで、さらに追記する」という使い方も可能です。

--append-system-prompt-fileはコマンドライン上に収まらない長文のルールを追記したいときの代替手段です。

どちらを選ぶか

公式ドキュメントは選択基準を「Claude Codeのデフォルトの人格が、その用途に合っているかどうか」に置いています。

追記フラグが向くのは、Claude Codeが引き続きコーディングアシスタントとして振る舞いながら、追加のルールにも従ってほしい場合です。1回の呼び出しごとの指示、出力フォーマットの指定、-pスクリプトのためのドメイン知識の付与などが該当します。デフォルトのツール利用ガイダンスや安全に関する指示を保ったまま、差分だけを足せば済みます。

置換フラグが向くのは、対象とする用途・立場・権限モデルがClaude Codeの前提と異なる場合です。人間が監視しないパイプラインに組み込む、コーディング以外のタスクを担うエージェントとして動かす、といったケースです。置換はデフォルトプロンプトに含まれるツールガイダンスや安全指示も含めてすべて捨てるため、タスクに必要な指示は自分で書き切る責任を負います。

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

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

--append-system-promptと--system-promptが操作するのは、メインの会話のシステムプロンプトです。サブエージェントのシステムプロンプトを追記したい場合は--append-subagent-system-prompt(またはファイル版の--append-subagent-system-prompt-file)という別のフラグを使います。ネストしたサブエージェントにも適用されますが、会話をフォークしたサブエージェント(forked subagent)は元の会話のプロンプトをそのまま引き継ぐため対象外です。このフラグは非インタラクティブモード(-p)でのみ機能し、Claude Code v2.1.205以降が必要です。

--append-subagent-system-prompt-fileはv2.1.261以降で利用できます。サブエージェントの定義・並列実行の設計そのものはSub-agents完全ガイドで扱っています。

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

--exclude-dynamic-system-prompt-sectionsというフラグもあります。これは作業ディレクトリや環境情報、メモリのパス、gitリポジトリかどうかといったマシンごとに変わる部分をシステムプロンプトから最初のユーザーメッセージへ移すもので、追記・置換とは目的が異なります。同じタスクを複数のユーザーや複数のマシンで実行するとき、プロンプトキャッシュの再利用率を上げる用途に使います。このフラグはデフォルトのシステムプロンプトを使う場合にのみ働き、--system-promptまたは--system-prompt-fileを指定しているときは無視されます。-pと組み合わせて使う想定のフラグです。

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

システムプロンプトのカスタマイズで見落としやすいのが、変更が「いつ反映されるか」です。Claude Codeは既定で、会話の最初のリクエスト時にシステムプロンプト(システムプロンプトフラグで指定したテキストを含む)を一度だけ構築し、セッションに記録します。会話がコンパクションされるまでは、--resumeや--continueで会話に戻った後も含めて、以降のすべてのリクエストがその記録済みプロンプトを使い続けます。

つまり、--continueで会話を再開するときに別のシステムプロンプトフラグのテキストを渡しても(あるいは何も渡さなくても)、それがすぐには反映されません。反映されるのは、会話がコンパクションされたとき、または新しい会話を始めたときです。--resumeとの使い分けそのものはresumeとforkの違いで扱っています。

--append-system-promptのテキストを--continue実行のたびに調整したい場合など、リクエストごとにプロンプトを再構築したいときは--system-prompt-snapshot offを渡します。

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

この--system-prompt-snapshotフラグ自体はClaude Code v2.1.257以降が必要です。v2.1.265より前のバージョンでは、システムプロンプトフラグのいずれかを渡すこと自体が、--system-prompt-snapshot onを明示しない限り記録をオフにする挙動でした。

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は効果を持ちませんでした。

置換と追記を組み合わせる

--system-prompt(または--system-prompt-file)と--append-system-prompt(または--append-system-prompt-file)は併用できます。まずベースとなるプロンプトを丸ごと置き換え、そのうえで用途固有の指示だけを追記する、という構成です。

claude --system-prompt-file ./base-agent-prompt.txt \
  --append-system-prompt "Respond only in JSON matching the given schema"

このパターンは、複数のパイプラインで共通の基盤プロンプト(--system-prompt-file)を使い回しつつ、パイプラインごとに異なる出力要件(--append-system-prompt)だけを差し替えたいときに向いています。基盤側を1ファイルに集約しておけば、変更のたびに全パイプラインのコマンドラインを書き換える必要がありません。

--agentフラグとの違い

システムプロンプトのカスタマイズと混同しやすいのが--agentフラグです。--agentはセッションで使うエージェント(agent設定を上書きする)を指定するものであり、あらかじめ定義されたエージェント定義を選択する仕組みです。これに対して--system-prompt系のフラグは、テキストそのものを直接指定してシステムプロンプトを組み立てます。定義済みのエージェントを切り替えたいなら--agent、その場限りのテキストでプロンプトを調整したいなら--system-prompt系、という住み分けです。

バージョン要件早見表

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

手元のバージョンで挙動が本記事の説明と異なる場合、まずclaude --versionで確認します。更新履歴の追い方はClaude Codeの変更履歴をどこで確認するかにまとめています。

よくあるつまずき

• --system-promptと--system-prompt-fileを同時に指定するとエラーになる。相互排他のフラグなので、コマンドラインの直接指定かファイル読み込みかのどちらか一方を選ぶ
• 置換フラグを使うと安全指示も消える。 --system-promptはツールガイダンスや安全に関する指示を含むデフォルトプロンプト全体を捨てるため、無人で動かすパイプラインでは必要な指示を渡した文字列側に書き切る必要がある
• --continueのたびにテキストを変えても反映されないことがある。これは記録済みプロンプトを再利用する既定動作(--system-prompt-snapshot on)によるもので、バグではない。反映させたいなら--system-prompt-snapshot offを使う
• メインの会話とサブエージェントを混同しない。サブエージェント向けは--append-subagent-system-prompt(および-file版)であり、--append-system-promptはメインの会話にしか効かない

まとめ

--append-system-promptはデフォルトの振る舞いを残したまま指示を足す方法、--system-promptはデフォルトを捨てて総取り替えする方法です。コーディングアシスタントとしての性質を維持したいなら追記、無人パイプラインや非コーディング用途で前提から作り直したいなら置換を選びます。加えて、--system-prompt-snapshotが「変更したテキストがいつ効くか」を左右する点は、--continueや--resumeを多用する運用では見落としやすいポイントです。