Claude Codeのsubagent指示をファイル化する

結論：長い指示はファイルへ移し、実行時の版を記録する

この機能の一次情報は、Anthropic公式のClaude Code v2.1.261リリースノートです。長いプロンプトを引数へ渡すとシェルの引用やログへの露出が起きるため、チームで同じ指示を再利用する課題に向きます。使う前には、対象バージョンと公式のsubagentsドキュメントを公開直前に確認してください。

何が変わるか：引数と指示ファイルを比較する

方法	向く場面	注意点
短い引数	一度だけの小さな補助指示	引用符、改行、shell historyを確認
指示ファイル	レビューして再利用する業務ルール	秘密情報を除外し、版とパスを記録
agent定義	役割・ツール・成果物を固定	全案件への影響と変更承認を管理

ファイル化の価値は、指示が長くなること自体ではありません。誰がいつ何を変えたかをdiffで見られ、subagentの結果が想定外だったときに「指示の版」「対象コード」「権限」を分けて調べられることです。利用者の個別情報、APIキー、token、顧客データは指示ファイルへ書かず、必要なら安全な実行環境の参照方法を別途設計します。

導入手順：小さな検証から始める7ステップ

1. Claude Codeをv2.1.261以降へ更新し、claude --versionの結果を記録します。
2. 「目的・対象ディレクトリ・禁止操作・成果物・完了条件」だけを指示ファイルへ書きます。
3. 秘密情報、実在の顧客データ、環境固有のtokenがないかレビューします。
4. 変更した指示ファイルをcommitし、subagentへ渡すcommitとファイルパスを固定します。
5. --append-subagent-system-prompt-fileで読み込み、最初はread-onlyの調査タスクを実行します。
6. subagentの出力、変更差分、実行logを確認し、指示どおりに動かなかった箇所を記録します。
7. 承認者がテスト結果を確認してから、変更を伴う作業へ対象を広げます。

指示ファイルには「必ず成功させる」と書くより、「テストが失敗したら停止し、失敗したコマンドと対象ファイルを報告する」と書く方が運用しやすくなります。subagentが生成した変更をそのままmergeせず、差分、テスト、依存関係、機密情報の混入を人間が確認する境界を残してください。

実務では、指示ファイルを「役割」「入力」「許可された操作」「禁止操作」「出力形式」「検証方法」の順に分けると、レビューする人が意図を追いやすくなります。調査用subagentなら読み取り対象と書き込み禁止を明記し、実装用なら変更可能なdirectory、test、失敗時の停止条件を加えます。役割の違うファイルを一つへ統合しないことが、過剰な権限を抑えます。

導入前後は同じtaskを二つの方法で実行し、指示の解釈、変更ファイル数、テスト結果、レビュー時間を比較します。差が出たときは、ファイル化、モデル、context、repository状態を分けて記録します。共通指示が長すぎてcontextを圧迫するなら、常に必要な規約と案件固有の補足を分割します。

企業運用の判断：共通化する指示と案件ごとの指示を分ける

共通ファイルへ置くのは、コーディング規約、テスト必須、禁止操作、出力形式など、複数案件で変わりにくい内容です。一方、顧客固有の要件、リリース日、対象branch、障害対応の制約は案件ファイルや実行時の入力へ分けます。混ぜると、共通指示の更新が意図せず全案件へ波及します。

比較する指標は、生成時間だけにしません。指示ファイルの変更回数、レビュー差し戻し、テスト失敗率、不要なファイル変更、権限確認の件数を小さなpilotで測ります。subagentのモデル指定や利用量は、既存のモデル優先順位のガイドと企業向けコスト管理に接続し、指示ファイル導入を費用管理から切り離さないようにします。

運用を止める条件もファイルに含めます。対象外のdirectoryを変更した、テストが未実行、指示の版が台帳と違う、秘密情報を参照した、という場合は成果物を採用せずに人間確認へ戻します。これにより、同じ指示を再利用しても、判断の境界が毎回説明できます。

チーム内で配布する場合は、ファイル名だけでなく所有者と有効期限を表示します。古い規約を参照したsubagentの出力を採用しないよう、実行前にcommitを照合し、更新時は代表的なtaskを再評価します。追加した指示が本当に必要かを定期的に見直すことも、contextとレビュー負荷を抑える実務上のチェックになります。

チェックリスト：実行を広げる前に

バージョンを固定したか／指示ファイルに秘密情報がないか／対象pathと禁止操作が明記されているか／成功条件と停止条件があるか／commitとファイル版を記録したか／subagentの権限を最小化したか／差分とtestを人間が確認したか／rollbackできるか／変更ownerと期限を決めたか、を確認します。

既存のClaude Code権限設定や監査ログと判断記録も合わせて確認すると、指示の再利用と作業の承認を同じ運用台帳へつなげられます。指示ファイルを増やすこと自体を成果にせず、作業の境界が説明できるかで判断してください。

よくある質問

コマンドラインに指示を書かなくてよくなりますか？

長いsubagentシステムプロンプトはファイルへ分離できます。ただし、実行時のタスク、対象、権限、承認は別に管理し、すべてをファイルへ詰め込まない方が変更範囲を追跡しやすくなります。

指示ファイルは毎回commitが必要ですか？

チームで再利用するなら、少なくとも実行時のhashまたはcommitを記録します。未レビューのローカルファイルをCIへ渡す場合は、出所が分からないため停止条件にしてください。

ファイル化すれば安全に自動実行できますか？

できません。ファイル化は入力経路の整理です。権限、sandbox、レビュー、テスト、停止条件を別に設計してください。

公式情報と無料診断

オプションの追加は公式リリースノート、subagentの考え方はAnthropic公式ドキュメントを公開直前にreadbackします。Miraigentの無料診断では、指示の正本、権限、レビュー、停止条件を業務ごとに整理できます。