--append-system-prompt-file（アペンドシステムプロンプトファイル）

コーディング用Claude Codeはそのまま使いたいが、プロジェクト固有の長文ルール（コーディング規約・出力フォーマット・ドメイン知識）をファイルで管理してスクリプトから参照したい人

Claude Codeを起動するとき、デフォルトのコーディング助手の人格はそのまま残したまま、自分が決めた長文の追加ルールを「ファイル経由で」末尾に足し込む起動指定。文字列を直接書く版の --append-system-prompt と挙動はまったく同じで、違いはルール本体をテキストファイルに切り出して、複数のスクリプトから同じファイルを参照できる点にあります。

長い独自ルール、たとえばコーディング規約・出力フォーマット・ドメイン知識を毎回コマンドに直書きするのは現実的じゃない。だからファイルに逃がす。1ファイル直せば全スクリプトに同時に反映される。これがいちばんの存在意義。

噛み砕くと

新しい職場の初日、ロッカーに「うちの会社の細かいルール集」が貼ってある、みたいなイメージです。Claude Code側のデフォルトの人格・安全ルール・コーディング作法はそのまま、その紙に書かれた追加事項を「これも守ってね」と起動時に渡す。

違うのは紙の置き場所。--append-system-prompt は「コマンドの後ろに直接書く付箋」、こちらは「机の引き出しに入れた書類」。書類を1枚直せば、その引き出しを参照してる全員に変更が回る。直書き派だと全員のデスクの付箋を貼り替えないといけない。

公式の仕様：これは「ファイルの中身を末尾に足す」起動指定

Claude Code公式のCLIリファレンスは、システムプロンプト系の起動指定を4種類に分けて整理しています。

Claude Code provides four flags for customizing the system prompt. All four work in both interactive and non-interactive modes.

4種類の役割は次のとおり。

このページの主役は4行目。「ファイルの中身を末尾に足す」が公式仕様で、これ以上でも以下でもない。

公式はもう1点、重要な使い分け基準を書いている。

Choose based on whether Claude Code's default identity still fits your task. Use an append flag when Claude should remain a coding assistant that also follows your extra rules: per-invocation instructions, output formatting, or domain context for a -p script. Appending preserves the default tool guidance, safety instructions, and coding conventions, so you only supply what differs.

つまり「コーディング助手のままでいてほしい、その上で追加ルールを守らせたい」場面では append 系を使え、ということ。差し替え版は人格ごと書き換えるので、デフォルトの安全策やツール使用作法も全部消える。これは判断が分かれるポイント。

「TypeScript強制ルールをファイル化して複数スクリプトで使い回す」を例に、実際の手順を見る

Next.js + TypeScriptで個人開発をしていて、コードレビュー用の自動化スクリプトを2本動かしている状況で再現してみます。コンポーネント用とAPI用の2本に、同じ「TypeScript必須・Jest強制・eslint通過必須」のルールを効かせたい。

ステップ1: ルールをファイルにまとめる

まずホームフォルダの中に prompts フォルダを作って、その中にルール用のテキストファイルを置きます。

$ mkdir -p ~/prompts
$ vi ~/prompts/typescript-strict.txt

中身はこんな感じで、200字くらいの追加ルール。

このプロジェクトのレビューでは次のルールを必ず守ること。

1. すべてのコード提案は TypeScript で書く。JavaScript は出力しない。
2. テストは Jest で書き、レビュー時は対応テストの有無を必ず確認する。
3. eslint で pass しない書き方は指摘する。any型の濫用、未使用変数の放置など。
4. import 順序は eslint-plugin-import の設定に従う。
5. レビュー結果は Markdown のチェックリスト形式で返す。

ここで初心者がやりがちな勘違いを1つ予告しておくと、このファイルの中に You are a Python expert みたいな人格そのものを書き換える文を書いてはいけない。コーディング助手のデフォルト人格が残ったまま追加ルールだけ守らせるのが append 系の用途。人格を変えたいなら差し替え版の領分です。

ステップ2: 起動指定をつけて手動で確認する

まず対話モードで挙動を確かめます。

$ claude --append-system-prompt-file ~/prompts/typescript-strict.txt

起動したら「適当な React コンポーネントを書いて」と頼んでみる。TypeScript で返ってくれば、ファイルの中身が末尾に足されていることが分かる。JavaScript で返ってきたらルールが効いていないので、ファイルの場所指定のスペルや、ルートから書く絶対の場所指定にしているか、を見直します。

ステップ3: 自動レビュースクリプトに組み込む

確認できたら、2本のレビュースクリプトに同じ起動指定を仕込みます。

#!/bin/bash
# review-component.sh
claude -p "$(cat src/components/$1.tsx) このコンポーネントをレビューして" \
  --append-system-prompt-file ~/prompts/typescript-strict.txt

#!/bin/bash
# review-api.sh
claude -p "$(cat src/app/api/$1/route.ts) このAPIをレビューして" \
  --append-system-prompt-file ~/prompts/typescript-strict.txt

2本とも同じファイルを参照しているのがポイント。-p は対話モードに入らずに1問1答で結果を返す起動の仕方で、自動化の台本に組み込むときの定番です。

ステップ4: ルールを直すときは1ファイル更新するだけ

運用していくと「テストカバレッジ80%以上を必須にしたい」みたいな追加要求が出てきます。そのときは ~/prompts/typescript-strict.txt の中身を編集してルールを足すだけ。

$ vi ~/prompts/typescript-strict.txt
# 6. 関連テストがある場合、カバレッジ80%以上を維持していることを確認する。

$ ./review-component.sh Button   # 次回実行から新ルールが効く

スクリプト2本のコードはまったく触らない。これが直書き版に対する稼ぎどころです。

ステップ5: 差し替え系と組み合わせる応用

公式はもう1つ余地を残していて、append 系は差し替え系と併用できると書いています。

The append flags can be combined with either replacement flag.

たとえば「Pythonエキスパートに人格ごと差し替えた上で、社内コーディング規約だけはファイルから読ませる」みたいな運用が可能。

$ claude --system-prompt "You are a Python expert" \
  --append-system-prompt-file ~/prompts/company-style.txt

ただし --system-prompt と --system-prompt-file 同士は同時に使えない、と公式に書かれています。差し替えは1回まで、追加は重ねられる、と覚えておくのが安全。

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

• やってくれる: 起動時にファイルを読み込んで、Claude Codeデフォルトの前提指示文の末尾に追加する。コーディング助手のデフォルト人格・安全策・ツール使用作法はそのまま残る
• やってくれる: 同じファイルを複数のスクリプトから参照する運用。1ファイル直せば全スクリプトに同時反映
• やってくれない: セッション中にファイルを書き換える行為への追従。今動いてるセッションには反映されません。起動時のスナップショットを読むだけ
• やってくれない: 永続化。これは今回起動した1セッションだけに効く。次の起動でまた渡さないと忘れられる
• 意味が薄い場面: ルールが短い1〜2行で済むなら直書き版で十分。プロジェクト全体で常に効かせたいなら CLAUDE.md に書いた方が自動で読まれる

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

シナリオ1: 個人開発で複数のレビュースクリプトに同じルールを効かせるとき

さっきの実演そのもの。Next.js + TypeScriptの個人開発で、review-component.sh / review-api.sh / review-test.sh のように用途別レビュースクリプトを増やしていくと、全部に同じ「TypeScript必須・Jest強制」を効かせたくなる。ここで ~/prompts/typescript-strict.txt をファイルとして切り出しておけば、ルール追加のたびにファイルを1か所だけ直せば済みます。スクリプト本体には --append-system-prompt-file ~/prompts/typescript-strict.txt の1行が並んでるだけ。私はこの形を採ると、レビュースクリプトの本体コードが薄くなって読みやすくなると感じています。

シナリオ2: 出力フォーマット強制（JSON固定・Markdown表強制）を1本のスクリプトに長文で持たせるとき

たとえば「議事録テキストを食わせて、決まったJSON構造で返してほしい」みたいな -p スクリプト。フィールド定義・null許容ルール・例外処理の指示を全部書くと200〜500字になりがちで、自動化台本の上で直書きするとエスケープが地獄になります。これは ~/prompts/meeting-to-json.txt として外出ししたほうが見通しがいい。スクリプト側は claude -p "$(cat minutes.txt)" --append-system-prompt-file ~/prompts/meeting-to-json.txt の1行で済みます。

シナリオ3: ドメイン知識を -p スクリプトに与えるとき

家計簿アプリの開発で、社内固有のお約束をコードレビュースクリプトに知らせたい場面。たとえば「うちのDBではユーザーIDをuid、取引IDをtxidと呼ぶ。txid はULIDで生成」のような社内用語・略語・製品名の定義です。これも ~/prompts/domain-glossary.txt に切り出して append すると、用語の追加・改名のたびに辞書ファイルだけ直せば全レビューが追従します。CLAUDE.md に書いてもいいんですが、CLAUDE.md は対話モード前提でプロジェクトフォルダで claude を叩いたときに自動で読まれる仕組み。-p ベースの自動化スクリプトをプロジェクト外のフォルダから叩く運用だと、明示的にファイルを指定するこちらの方が事故が少ない。

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

• セッション中にファイルを書き換えても反映されない。この起動指定はClaude Code起動のその瞬間に1回だけファイルを読みます。セッションを開いたまま ~/prompts/typescript-strict.txt を編集しても、いま動いてる会話には影響しない。新しい起動で初めて反映されるので、ルール変更したら一度 Ctrl+D で抜けて再起動する
• ルートから書かない場所指定にして「ファイルが見つからない」エラー。./prompts/rules.txt のような書き方は、コマンドを叩いた場所からの相対の場所指定として解釈されます。別のフォルダから叩くと見失う。基本は ~/prompts/... や /Users/yourname/prompts/... のようにルートから書く形にしておく方が事故が少ない
• 「TypeScript必須」を毎回付けたいなら CLAUDE.md に書いた方が早い。公式は次のように明記している。"These flags apply only to the current invocation. ... For project conventions Claude should always follow, use CLAUDE.md"。永続的なプロジェクト規約はCLAUDE.md側の仕事。この起動指定は1回限りなので、毎回手で渡す前提のもの。スクリプトに組み込む場面ならそれでいいけど、対話モードで毎回打ってるならCLAUDE.mdに引っ越したほうが楽です
• 対話モードで毎回手打ちするのは割に合わない。公式の memory ページにも次のように書かれている。"This must be passed every invocation, so it's better suited to scripts and automation than interactive use."。本領は -p スクリプトに組み込んだ自動化用途
• ファイル内に「You are a Python expert」のような人格書き換え文を書くと、デフォルト人格と二重人格状態になる。append 系はあくまでデフォルトの末尾に足すだけで、上書きはしない。人格まで差し替えたいなら差し替え版の仕事。append のファイルには「追加ルールだけ」を書く
• 差し替え系2つは同時には使えない。--system-prompt と --system-prompt-file は公式が mutually exclusive と書いているので、どちらか1つ。append 系はそれと組み合わせることができる、というのが正しい理解
• ファイルの場所指定にスペースが入ると壊れがち。~/My Prompts/rules.txt のようなフォルダ名はクォートで囲むか、スペースを使わない命名にしておくのが安全。自動化スクリプトに埋め込むときは特に

書き方

claude --append-system-prompt-file [ファイルの場所]

[ファイルの場所] には、ルールを書いたテキストファイルの場所を、ルートから書く形（~/prompts/rules.txt など）で指定する。-p（プリント・モード）と組み合わせて自動化の台本に埋め込むのが本領。

やってみるとこうなる

入力

claude --append-system-prompt-file ~/prompts/typescript-strict.txt

出力例

（対話モードが起動。ファイルの中身が起動時の前提指示文の末尾に追加された状態で会話が始まる。試しに「適当な React コンポーネントを書いて」と頼むと、~/prompts/typescript-strict.txt に書いた『TypeScript必須・Jest強制』のルールに従って、TypeScript で、テスト想定込みのコードが返ってくる）

関連項目

• --append-system-prompt（アペンドシステムプロンプト）
• --system-prompt-file（システムプロンプトファイル）
• --system-prompt（システムプロンプト）
• CLAUDE.md
• /memory（メモリ）

公式ドキュメント

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