開発者がプロンプトに出会う場面は 2 つあります。AI アシスタントにコードの変更を頼むときと、アプリケーションに組み込むプロンプトを書くときです。必要なスキルは重なりますが、失敗の起こり方は異なります。このガイドは両方を扱います。
パート 1：AI コーディングアシスタント向けのプロンプト
願望ではなく仕様を書く
1 文だけを与えられたコーディングアシスタントは、範囲、制約、そして「完了」の意味を推測しなければなりません。良いチケットに書くのと同じことを与えましょう。
fix login issue and make google login work and don't break anything
## Objective
Fix the login failure and make Google login work.
## Constraints
- Do not change the existing email and password flow.
- Keep the public API of AuthService unchanged.
## Edge cases
- Expired or revoked OAuth tokens.
- A Google account whose email already exists as a password account.
## Testing
- Add unit tests for the token exchange and the account-linking path.
## Acceptance criteria
- Existing auth tests pass. New tests cover both edge cases.
## Expected output
A summary of the cause, then the changed files as diffs.
2 つ目のプロンプトは書くのに 1 分余計にかかりますが、「そういう意味ではなかった」というやり取りを 1 往復減らせます。PromptFlowEngine の VS Code 拡張機能は、1 行のタスクと関連ファイルから、この構造を生成します。
すべてのコードではなく、適切なコードを渡す
コンテキストウィンドウは大きいですが、注意力は無限ではありません。変更が触れるファイル、守るべきインターフェース、プロジェクトの規約を示す例を 1 つ含めましょう。生成ファイル、ロックファイル、無関係なモジュールは除きます。
変えてはいけないことを書く
アシスタントは依頼に合わせて最適化します。後方互換性、公開インターフェース、性能が重要なら、そう書きましょう。「何も壊さないで」はモデルが確認できる制約ではありませんが、「GET /orders のレスポンススキーマは変更しない」は確認できます。
大きな変更では計画を求める
小さな編集を超えるものは、まず計画を求め、レビューしてから実装を求めます。これはコードに適用したプロンプトチェーンで、コードが書かれる前に誤ったアプローチを見つけられます。
返ってきたものを検証する
差分を読みましょう。テストを実行しましょう。大きな変更では、元のタスクと変更後のファイルをモデルに渡すレビュー用プロンプトを書き、変更が受け入れ基準を満たしていない箇所を挙げさせます。
パート 2：アプリケーション内のプロンプト
プロンプトをバージョン管理に置く
プロンプトはプログラムの振る舞いの一部です。ファイルに保存し、変更はプルリクエストでレビューし、バージョンにタグを付けます。プロンプトの管理とバージョニングを参照してください。
区切り付きの変数を使うテンプレートにする
ユーザー入力を指示に連結してはいけません。名前付きの変数を使い、それぞれをタグで囲みます。
PROMPT = """Classify the support ticket in the tags as billing, bug, or other.
Return only the label.
<ticket>
{ticket}
</ticket>"""
構造化された出力を要求して検証する
コードがレスポンスを解析するなら、スキーマに沿った JSON を要求し、提供元に構造化出力の機能があればそれを使い、結果を使う前に検証します。構造化出力のプロンプトを参照してください。
トークンの予算を立てる
固定のプロンプトが何トークン使うかを把握しましょう。呼び出しのたびに支払うからです。文字数による見積もりではなく、モデル本来のトークナイザーで数えます。トークン最適化を参照してください。
CI でプロンプトをテストする
モデルを使わずに検出できる回帰があります。出力形式の削除、セクションの重複、予算を超えたトークン数、コミットされた API キーなどです。プロンプトテストゲートは、これらをプルリクエストごとに実行します。
- run: promptflow check "prompts/**/*.md" --min-score 70 --max-tokens 1500
モデルの出力を信頼できないものとして扱う
出力は誤っていることがあり、入力に注入されたテキストに誘導されることもあります。ユーザー入力に適用するのと同じ検証なしに、シェル、SQL クエリ、HTML ページへ渡してはいけません。プロンプトセキュリティを参照してください。
コードからエンジンを呼び出す
同じチェックは、キーなしで HTTP 経由でも利用できます。簡単な結合テストや社内ツールに便利です。
curl -s https://promptflowengine.com/api/v1/analyze \
-H 'content-type: application/json' \
-d '{"prompt":"Write something about our product."}'