Skip to main content
ツールと拡張機能

システムプロンプト

Qoder CLI のシステムプロンプトを置き換えるか拡張し、読み込む指示ファイルを制御して、実際にコンテキストへ入った内容を確認します。

システムプロンプトは、汎用モデルをどのような Agent にするかを決めます。口調、優先順位、そして譲れないルールがここで決まります。 Qoder Agent SDK は3つの層を提供し、これらは組み合わせられます。影響の小さい層から始め、必要な場合にのみ次の層へ進んでください。
層仕組み適した場面
プリセットに追記するsystemPrompt / system_prompt のプリセット形式Qoder CLI の Agent 挙動を保ったまま、独自のルールを加えたい
指示ファイルを読み込むsettingSources / setting_sourcesルールがリポジトリにあり、人にも Agent にも適用したい
完全に置き換えるsystemPrompt / system_prompt の文字列コーディング以外の用途の Agent を作り、独自の行動規約を定義したい
両言語がこの3つの層すべてに対応しています。Python にはファイルから読み込む形式もあり、TypeScript にはありません。ファイルからプロンプトを読み込むを参照してください。

プリセットに追記する

推奨される既定の方法です。Qoder CLI プリセットには、長いタスクで Agent が収束するために必要なツール利用の規律、タスク計画の挙動、出力の慣習が含まれています。追記形式はそれらをすべて保ち、末尾に独自のルールを加えます。 
options: {
  systemPrompt: {
    type: 'preset',
    preset: 'qodercli',
    append: [
      'Always write tests before implementation.',
      'Never edit files under vendor/.',
      'Reply in Japanese.',
    ].join('\n'),
  },
}
チームの取り決めに相当するルールは、この形式を優先してください。3つのルールを加えるためにプロンプト全体を書き換えると、変更する意図のなかった挙動まで失われます。

プロンプトを完全に置き換える

文字列を渡すとプリセットが上書きされます。Agent はツールとループを保持しますが、それ以外の挙動については何も前提が置かれません。 
options: {
  systemPrompt: `You are a release auditor.

Inspect the repository and report findings. You may read files and run
read-only commands. Never modify the working tree. Answer with a numbered
list of findings, each tagged CRITICAL, WARNING, or INFO.`,
}
この層があることで、SDK の用途はコーディング支援を超えて広がります。トリアージ Agent、データ分析 Agent、ドキュメント Agent はいずれもプロンプトを置き換えつつ、同じ Harness を再利用できます。Agent ループ、ツール実行、権限の検証、セッション管理はそのまま維持されます。
完全な置き換えは、プリセットのスタイルとともにその安全上の制約も取り除きます。置き換えたプロンプトに変更の検証や作業ディレクトリ内に留まることが書かれていなければ、Agent はそれに従う指示を持ちません。完全に置き換える場合は、明示的な権限制御と併用してください。

ファイルからプロンプトを読み込む

Python SDK には、ディスクからプロンプトを読み込む3つ目の形式があります。長いプロンプトをアプリケーションコードから切り離し、単独でバージョン管理やレビューを行えます。 
options = QoderAgentOptions(
    system_prompt={"type": "file", "path": "./prompts/release-auditor.md"},
)
対応言語：Python のみ。TypeScript には対応する形式がありません。TypeScript では自らファイルを読み込み、その内容を文字列として渡してください。

ファイルシステムから指示を読み込む

指示ファイルを使うと、ルールをそれが適用されるコードの近くに置けるため、人と Agent の双方に同じ指針が働きます。settingSources はセッションがどのファイルを読み込むかを決めます。 
// ユーザー単位、プロジェクト単位、ローカルの指示ファイルを読み込む（CLI の既定動作）
options: { settingSources: ['user', 'project', 'local'] }

// ディスクからは何も読み込まない —— アプリケーションが唯一の情報源になる
options: { settingSources: [] }
マルチテナントやホスティング環境では settingSources: [] を使用してください。そうでない場合、Agent の挙動は Qoder CLI を実行するマシンにたまたま存在するファイルに左右され、ホスト間で実行結果を再現できなくなります。

実際に読み込まれた内容を確認する

プロンプトの問題は、多くの場合「そのファイルが読み込まれていると知らなかった」ことに起因します。InstructionsLoaded Hook は指示ファイルごとに1回発火するため、推測ではなく実際の構成を記録できます。 
options: {
  hooks: {
    InstructionsLoaded: [
      {
        hooks: [
          async (input) => {
            console.log(`[instructions] ${input.memory_type} ${input.file_path} (${input.load_reason})`);
            return {};
          },
        ],
      },
    ],
  },
}
フィールド値意味
memory_typeUser、Project、Local、Managedファイルがどのスコープから来たか
load_reasonsession_start、nested_traversal、path_glob_match、include、compact読み込まれた理由
file_pathパス読み込まれたファイル
見落とされやすいのは nested_traversal と include です。指示ファイルは他のファイルを取り込めるため、実際に有効なプロンプトは自分が書いた1つのファイルより大きくなり得ます。

出力スタイルは個別に調整する

出力スタイルは、行動ルールを変えずに Agent の結果の見せ方を調整します。Query のオプションではなく、設定レベルの値です。 
options: {
  settings: { outputStyle: 'concise' },
}
現在のスタイルと選択可能な一覧は、セッション初期化メッセージから取得できます。 
const init = await q.initializationResult();
console.log(init.output_style, init.available_output_styles);
「冗長すぎる」「形式が違う」という問題には出力スタイルを、「誤った処理をした」という問題には systemPrompt を使ってください。

次のステップ

  • カスタムツール —— 振る舞い方だけでなく、Agent ができることを拡張する
  • Skills —— 再利用可能な指示を名前で呼び出せる形にまとめる
  • サブ Agent —— 委譲したタスクに独自のプロンプトとツールセットを与える
  • Hooks —— 各ライフサイクル地点でセッションを確認し介入する
クイックスタート
基本概念
会話とセッション
ツールと拡張機能
制御と安全性
リファレンス