--append-system-prompt（アペンドシステムプロンプト）

Claude Codeのコーディング用デフォルト挙動はそのまま使いつつ、プロジェクト固有のルールを1回限り足したい人

Claude Codeのコーディング用デフォルトの振る舞いはそのまま残しつつ、「このセッションだけはTypeScriptで書け」「テストはJestを完走してから完了報告しろ」みたいな追加ルールを、起動時に1回限りで足したい時に使う指定が --append-system-prompt。デフォルトの中身を消さず、その後ろに自分のテキストを連結する形で渡す。

CLAUDE.mdに書いて永続化するほどでもない、まだ試運転中のルールを、そのセッションだけ重ねたい場面にハマる。

噛み砕くと

新しい職場に外部スタッフを呼んだとき、「今日の現場ルールはこれね」と1枚メモを渡すイメージ。スタッフの基礎スキルはそのまま、その上に今日限定の現場ルールを上乗せする。明日また呼んだら、そのメモは持ってきていないので、また同じメモを渡す必要がある。

そういう「今日だけのメモ」を起動時に1枚渡す動きをするのが --append-system-prompt。

大事な前提：デフォルトを消すのではなく「後ろに足す」

名前が似ている兄弟分に --system-prompt があるが、こちらはデフォルトを丸ごと置き換える動き。--append-system-prompt は置き換えではなく末尾に追加。デフォルトに入っているコーディング用の振る舞い・ツール操作のガイド・安全側の指示は全部残ったまま、その後ろに自分のテキストが連結される。

だから渡すテキストは「あなたはPythonエキスパートです」みたいな人格そのものを書き直す系の文章は不向き。デフォルトのコーディング支援役という土台はそのままに、その上に「今回はこれを守って」と上乗せするニュアンスで書く。

「Next.js個人開発でTypeScript必須・Jest完走を1セッション限定で足す」を例に、実際の手順を見る

ステップ1: いつもどおりプロジェクトのフォルダに入る

個人開発のNext.jsプロジェクトのフォルダで作業を始める前提。まだCLAUDE.mdに「TypeScript必須」「テストはJestで npm test を通してから完了報告」のルールは書いていない、試運転中という状況。

$ cd ~/projects/my-next-app

ステップ2: 追加ルール付きでClaude Codeを起動する

普段は claude だけで起動するところに、--append-system-prompt を後ろに足して、追加ルールの文字列をダブルクオートで囲んで渡す。

$ claude --append-system-prompt "Always use TypeScript. Run 'npm test' and ensure all tests pass before claiming a task is done."

起動後の対話画面はいつもと変わらない。見た目は同じ。けれど内部では、デフォルトのシステムプロンプトの末尾に渡したテキストが連結された状態で動いている。

ステップ3: 普通にタスクを依頼する

たとえばログイン画面のフォームを追加してもらう依頼を投げる。

ログインフォームのコンポーネントを追加して、useStateでメールとpasswordを管理してほしい

追加ルールを渡していなかった場合、Claudeは状況次第でJavaScriptかTypeScriptかを選ぶ余地がある。今回は「Always use TypeScript」を末尾に足しているので、.tsx ファイルで作ってくる確率が大きく上がる。

ステップ4: 作業の終わり際にテスト実行を求める動きを確認

作業が一段落すると、追加ルールに書いた「Run 'npm test' and ensure all tests pass before claiming a task is done.」を意識して、勝手に npm test を実行しようとする動きが出やすくなる。テストが落ちた場合は、完了報告の前にコードを直す方向に動く。

ここで初心者がやりがちな勘違いがある。このルールは「絶対遵守の命令」ではなく、強い指針として効くだけ。会話の文脈や依頼内容次第では、Claudeが判断してテスト実行をスキップすることもある。100%の強制力ではないという前提で使う。

ステップ5: セッションを終了する

ターミナルを閉じる、/exit で抜ける、別ウィンドウで claude を起動する、のいずれかをやった瞬間に追加ルールは消える。次に claude だけで立ち上げたら、もうTypeScript必須もJest完走もどこにも残っていない。

ステップ6: 試運転で良さそうなら CLAUDE.md に格上げする

2〜3セッション使ってみて「やっぱりこのルールは恒久化したい」と感じたら、プロジェクトのルートに CLAUDE.md を作って同じ内容を書き写す。CLAUDE.md はそのプロジェクトのフォルダで claude を立ち上げた時に毎回自動で読まれるので、起動コマンドを長くしなくて済む。

つまり --append-system-prompt は何をしてくれるのか

• やってくれる: デフォルトのコーディング支援役の振る舞いを残したまま、その後ろに「今回限定の追加ルール」を1セッション分だけ重ねる
• やってくれる: 対話モードでも、-p での非対話実行でも、同じように追加ルールを効かせる
• やってくれる: --system-prompt（置き換え版）と同時に使える。たとえば claude --system-prompt "あなたはSQLの専門家です" --append-system-prompt "出力は必ず日本語で" のように、まず土台ごと置き換えてから追加ルールを末尾に足す使い方が可能。--system-prompt と --system-prompt-file は互いに排他だが、--append-system-prompt はどちらとでも組み合わせられる
• やってくれない: ルールの永続化。次のセッションには持ち越されない。毎回同じテキストを打つ必要がある
• やってくれない: 100%の強制。指針として効くが、文脈次第ではClaudeが判断で外すこともある
• 意味が薄い場面その1: 同じルールを毎日使う場合は、いちいち書かずに CLAUDE.md に書いた方が早い
• 意味が薄い場面その2: ペルソナごと切り替えたい場合は、output styles の方が向く

使いどころ3シナリオ（具体題材で再現）

シナリオ1: 個人開発で「このプロジェクトだけTypeScript縛り」を試運転したいとき

個人で動かしている小さなWebアプリで、最近「JSとTSが混在していて読みにくいから、これからの新規ファイルは全部TSで揃えたい」と思い始めた。けれどCLAUDE.mdに書いて恒久化するのは、まだ自分の中で結論が出ていない。こういう時に claude --append-system-prompt "All new files must be TypeScript (.ts or .tsx). Do not create .js or .jsx." で2〜3セッション試す。違和感がなければCLAUDE.mdに格上げする。

シナリオ2: 料理ブログのDBコードを書く時、SQL書式を統一したいとき

料理ブログのレシピDBを設計している最中で、SQL文の書式が人によってバラバラだと後で読み返したときにつらい。今日の作業だけは「SQLキーワードは全部大文字 (SELECT / FROM / WHERE)、テーブル名はsnake_case」と縛りたい。claude --append-system-prompt "When writing SQL, use uppercase for keywords (SELECT, FROM, WHERE) and snake_case for table and column names." で起動すると、その日に出てくるSQL案がほぼ統一されたスタイルで返ってくる。

シナリオ3: 非対話モードで自動化スクリプトの出力フォーマットを揃えたいとき

家計簿アプリの自動化で、毎日の支出ログをClaudeに要約させてSlackに投げる自動化スクリプトを組んでいる。claude -p "今日の支出ログを要約して" --append-system-prompt "Output must be in this format: 1 line summary, then 3 bullet points. Use Japanese." のように非対話モードに追加ルールを連結すると、毎回同じ書式の要約が返ってきて、Slackへの整形コストが減る。-p での1発呼びで出力フォーマットを縛る用途は、公式ドキュメントが推奨している使い方そのもの。

初心者が踏みやすい落とし穴

• 対話モードで毎回手打ちするなら CLAUDE.md か output styles にする。公式ドキュメントは「毎回の起動のたびに渡す必要があるため、スクリプトや自動化に向いている」と明示している。claude を対話で立ち上げるたびに長い追加ルールを手打ちするのは手間が増えるだけ。定常的に使いたいルールは CLAUDE.md に書けば自動で読まれる。--append-system-prompt が本領を発揮するのは -p に組み込んだ自動化スクリプトで毎回同じ出力フォーマットを固定する場面
• 毎回同じルールを足すなら CLAUDE.md に書く方が早い。--append-system-prompt は1セッション限りなので、TypeScript必須を恒久化したいなら CLAUDE.md にそう書く。公式ドキュメントも「プロジェクトの規約は CLAUDE.md、起動ごとの一時ルールは append」と棲み分けを明示している
• ペルソナごと切り替えたいなら output styles を使う。コーディング役 → 校正役 → ライター役、と頻繁にペルソナを切り替える運用で --append-system-prompt に長文を毎回貼り付けるのは管理がしんどい。output styles なら名前で呼び出せる
• 「You are a Python expert」みたいな人格書き換え文を渡さない。これは --system-prompt（置き換え版）で書く類のテキスト。--append-system-prompt は「デフォルトの後ろに付け足す」ので、人格定義を渡すとデフォルトのコーディング支援役と二重人格状態になり、動きが読みづらくなる
• 100%の強制力ではない。「Always use TypeScript」と書いてもClaudeが文脈判断で .js を作ってくる可能性はゼロにはならない。テストで明示的に検証する、CLAUDE.mdとの併用で念押しする、などの保険を組み合わせる
• ターミナルのクオート解釈で事故る。渡すテキストの中に " や $ が入っていると、ターミナル側が解釈してしまって意図通りに渡らないことがある。長文を渡すなら --append-system-prompt-file ./style-rules.txt のようにファイル渡しの兄弟分に切り替える方が安全
• ルールが多すぎると効きが薄まる。10個も20個も追加ルールを並べると、後ろの方の指示は無視されやすい。本当に守ってほしいものを3〜5個に絞って書く方が結果が安定する

書き方

claude --append-system-prompt "追加ルール本文（英語・日本語どちらでも可）"

やってみるとこうなる

入力

claude --append-system-prompt "Always use TypeScript. Run 'npm test' and ensure all tests pass before claiming a task is done."

出力例

起動後の対話画面はいつもと同じ見た目。内部ではデフォルトのシステムプロンプトの末尾に渡した文字列が連結された状態で動き、コーディング依頼を投げると追加ルールを意識した動きになる。セッション終了で追加ルールは消える。

関連項目

• --system-prompt（システムプロンプト）
• --system-prompt-file（システムプロンプトファイル）
• --append-system-prompt-file（アペンドシステムプロンプトファイル）
• CLAUDE.md
• /output-styles（準備中）

公式ドキュメント

https://code.claude.com/docs/en/cli-reference