Pi Agent プロンプトテンプレート
プロンプトテンプレートは、事前定義された Markdown フラグメントです。短いコマンドを入力するだけで完全なプロンプトに展開でき、反復作業の効率を高めます。
テンプレートの概要
プロンプトテンプレートの仕組みは簡単です:
- Markdown ファイルを作成し、テンプレートの内容を定義します
- エディターで入力します`/テンプレート名`で呼び出します
- テンプレートは自動的に展開され、エディターに挿入されます
テンプレートはパラメータ置換に対応しており、同じテンプレートをさまざまな具体的なシナリオで使用できます。
テンプレートの作成
テンプレートは YAML Frontmatter を備えた Markdown ファイルです。
ファイル名(.md を除く)がそのままテンプレートのコマンド名になります。
コードレビューテンプレートを作成します:
例
description: 現在の git ステージング変更をレビューする
---
ステージングエリアの変更(git diff --cached)をレビューし、次の点に重点を置きます:
- 潜在的なバグと論理エラー
- セキュリティ問題
- エラーハンドリングと境界条件
- パフォーマンス問題
保存先は~/.pi/agent/prompts/review.mdの後、エディターで入力します/reviewすると展開して使用できます。
テンプレートの場所
Pi Agent はテンプレートを決められた複数の場所で検索します。それぞれ適用範囲が異なります。
| 場所 | 適用範囲 |
|---|---|
| ~/.pi/agent/prompts/*.md | グローバルテンプレート。すべてのプロジェクトで利用可能 |
| .pi/prompts/*.md | プロジェクトテンプレート。プロジェクトが信頼された後にのみ読み込まれます |
| Pi Packages の prompts/ ディレクトリ | パッケージ内のテンプレート |
| --prompt-template パス | コマンドラインから一時的に読み込み |
テンプレートの検出は非再帰的であり、prompts/ サブディレクトリ内のテンプレートは自動的に読み込まれません。
テンプレートをサブディレクトリに置く場合は、settings.json の prompts 配列にそのパスを明示的に追加する必要があります。
パラメータシステム
テンプレートは豊富なパラメータシステムをサポートしており、同じテンプレートをさまざまなシナリオに適応させられます:
| 構文 | 意味 | 例 |
|---|---|---|
| $1, $2, $3... | 位置パラメータ | $1 は最初のパラメータを表します |
| $@ または $ARGUMENTS | すべてのパラメータを結合 | すべてのパラメータをスペースで連結します |
| ${1:-デフォルト値} | デフォルト値付きパラメータ | パラメータが存在し空でない場合はそのパラメータを使用し、それ以外の場合はデフォルト値を使用します |
| ${@:N} | N 番目のパラメータ以降 | ${@:2} は 2 番目以降のすべてのパラメータを取得します |
| ${@:N:L} | N 番目から L 個取得 | ${@:2:3} は 2 番目から 4 番目までのパラメータを取得します |
$ARGUMENTS はすべてのパラメータをそのまま連結します。単に 1 つのテキストブロックだけが必要なテンプレートに適しています:
例
description: 中国語の文章を自然な英語に翻訳する
argument-hint: "<翻訳したい中国語>"
---
以下の内容を自然な英語に翻訳し、翻訳文のみを出力してください:
$ARGUMENTS
保存名は~/.pi/agent/prompts/translate.mdの後、次を使用します/translate でこの文章を英語に翻訳します呼び出します。
パラメータ付きテンプレートの例
次のテンプレートは位置パラメータと末尾パラメータを組み合わせて使用します。「型 + 名前 + 補足説明」のような入力に適しています。
例
description: 指定されたフレームワークでコンポーネントを作成する
argument-hint: "<フレームワーク> <コンポーネント名> [機能説明]"
---
$1 を使って $2 コンポーネントを作成し、機能は次のとおり:${@:3}
$1 は最初のパラメータをフレームワークとして取得し、$2 は 2 番目のパラメータをコンポーネント名として取得します。
${@:3} は 3 番目のパラメータ以降のすべての内容を表し、断片的な機能説明を担います。
使用方法:
/component React Button "onClick 事件处理" "disabled 状态支持" "loading 加载状态"
展開後の結果:
使用 React 创建一个 Button 组件,功能包括:onClick 事件处理 disabled 状态支持 loading 加载状态
デフォルト値の例
パラメータがない場合はデフォルト値で補完するため、テンプレートはパラメータなしで呼び出しても正常に動作します。
例
description: 現在のプロジェクトの状態を要約する
---
${1:-5} 個の要点で、現在のプロジェクトの主な変更と状態を要約してください。
保存先は~/.pi/agent/prompts/summarize.mdの後、次を使用します/summarize呼び出します。
を使用すると/summarizeデフォルトで 5 つの要点を出力します。
を使用すると/summarize 1010 つの要点を出力します。
2 つの呼び出しの展開結果の比較は次のとおりです:
/summarize → 用 5 个要点总结当前项目的主要变更和状态。 /summarize 10 → 用 10 个要点总结当前项目的主要变更和状态。
argument-hint パラメータのヒント
Frontmatter に設定するとargument-hintテンプレートが必要とするパラメータをユーザーが把握できます:
例
description: URL から PR をレビューし、コードと問題を分析する
argument-hint: "<PR-URL>"
---
以下の PR のコード変更をレビューし、セキュリティとパフォーマンスの問題に重点を置いてください:$1
オートコンプリートのドロップダウンメニューでは、このテンプレートは次のように表示されます:
→ pr <PR-URL> — 从 URL 审查 PR,分析代码和问题
保存先は~/.pi/agent/prompts/pr-review.mdの後、次を使用します/pr-review https://github.com/サンプル/repo/pull/12呼び出します。
使用する`<山かっこ>`は必須パラメータを表し、`[角かっこ]`はオプションパラメータを表します。
実用的なテンプレートの例
以下の 3 つのテンプレートは、日常開発で最もよくある 3 種類のリクエストをカバーしています。そのままコピーして必要に応じて調整できます。
Git コミットメッセージ生成
次のテンプレートは Conventional Commits 規約に従ってコミットメッセージを生成します。
例
description: git diff に基づいて規約に沿ったコミットメッセージを生成する
---
git diff --cached の内容を確認し、規約に沿った git commit メッセージを 1 件生成してください。
Conventional Commits 規約に従い、形式:type(scope): description
タイプには feat, fix, refactor, docs, test, chore が含まれます
保存先は~/.pi/agent/prompts/commit.mdの後、変更をステージングしてから次を使用します/commit呼び出します。
コードリファクタリング依頼
次のテンプレートはリファクタリングの目標を明確なチェック項目に分解し、AI が単にフォーマットだけを変更して構造を変えないことを防ぎます。
例
description: 指定されたコードモジュールをリファクタリングする
argument-hint: "<ファイルパスまたはモジュール名>"
---
$1 のコードをリファクタリングします。目標:
1. コードの可読性を向上させる
2. 重複コードを排除する
3. エラーハンドリングを改善する
4. 既存の機能を変更しない
変更する前に、まずリファクタリング計画を説明してください。
保存先は~/.pi/agent/prompts/refactor.mdの後、次を使用します/refactor src/utils/date.ts呼び出します。
Bug 修正依頼
次のテンプレートは AI に固定の手順で調査・解決させ、「いきなりコードを変更する」ケースを減らします。
例
description: 指定された Bug を体系的に調査して修正する
argument-hint: "<Bug の説明>"
---
以下の Bug の調査と修正を手伝ってください:$1
次の手順に従ってください:
1. まず Bug の期待される動作と実際の動作を理解する
2. 関連するコードファイルを見つける
3. 考えられる原因を分析する
4. 修正案を提案する
5. 修正を実装する
6. 修正が正しいかどうかを検証する
各ステップで、あなたの発見と推論を説明してください。
保存先~/.pi/agent/prompts/fix-bug.md後、使用して/fix-bug ログイン後にリストが更新されない呼び出します。
テンプレート読み込みルール
テンプレートの発見と読み込みは以下のルールに従います。「テンプレートが表示されない」問題を調査するときは、まずここを確認してください。
| ルール | 説明 |
|---|---|
| 非再帰的な発見 | prompts/ ディレクトリ内のテンプレート発見は非再帰的であり、サブディレクトリ内のテンプレートは自動的に発見されません |
| サブディレクトリは明示的な宣言が必要 | サブディレクトリ内のテンプレートを読み込む必要がある場合は、settings.json の prompts 配列にパスを明示的に追加してください |
| description のフォールバック | もしdescription空の場合、Pi Agent はファイルの最初の空でない行のテキストを説明として使用します |
| 自動発見の無効化 | によって--no-prompt-templates自動発見を無効にしますが、明示的に--prompt-template指定されたテンプレートは引き続き読み込まれます |
その他の拡張機能/テンプレート名 を入力しても補完リストに表示されない場合は、ファイルが prompts/ ルートディレクトリにあるかどうかを最初に確認してください。
.pi/prompts/ に置かれたプロジェクトテンプレートは、先にプロジェクト信頼チェックを通過する必要があります。そうしないと同様に読み込まれません。