監督者の言語

– 良いプロンプトはどのように設計するのか？

1. はじめに

Claude Codeの講義を制作する中で、説明のためにさまざまなソースコードを生成し、変更し、テストしました。AI以前の時代には、実習用のコードを作るためにかなりの時間をかけて考え、修正する作業が日常的でした。一方、今では数語のプロンプトによって、数分で望んだコード、動作するコード、テストケースを一度にすべて通過するコードを作れるようになりました。そのたびに、コードを作る人から、作られたコードを検証する人になったのだと感じるようになりました。
そして、AIとの協業において重要なのは、生成されたコードをさまざまな観点から検証することです。また、最初にコードを生成するために何を考慮し、どのようにプロンプトを作るのがよいのかという普遍的な課題について、改めて考えるようになりました。
掲示板の例を構成する際、次のようなプロンプトを入力しました。

“게시글에 댓글 기능을 추가해줘.”

結果は数分で出ました。Commentエンティティが作成され、Service、Controller、JPAベースのRepositoryまで構成され、Reactで構成した画面にはコメント一覧も表示されました。しかし、結果画面とソースを見ながら、何気なく進めたプロンプトに対してさまざまな疑問が湧いてきました。
「コメントへの返信コメントは可能なのか？」
「削除はソフト削除、それともハード削除なのか？」
「作成者だけが削除できるようになっているのか？ 管理者は？」
「ページングはどのようになっているのか？」
このようにさまざまな疑問が生じましたが、AIは作業を進める中でそのどれ一つとして尋ねませんでした。よく考えてみると、私のプロンプトは要件ではなく、ヒント程度の指示だったために、このような結果になったのです。このような類似した経験を重ねる中で、「精密なプロンプト」とは実際に何を意味するのか、どのような要素に分けて整理できるのか、どのように再現可能な手順にできるのかを考えるようになりました。

2. プロンプトを要件仕様にする

曖昧な要件は曖昧なシステムを作ります。要件工学では、要件の品質を明確性（clarity）、完全性（completeness）、検証可能性（verifiability）、一貫性（consistency）の基準で評価します。この4つの基準はプロンプトにもそのまま適用できます。プロンプトそのものが、すでにAIに伝える私たちの要件なのです。

ただし、違いがあるとすれば速度です。不完全な要件を人に伝えると、人は聞き返します。「返信コメントも必要ですか？」「削除はどの方式にしますか？」といった質問が自然に交わされます。この過程こそが、要件を洗練するプロセスです。しかし、AIは聞き返しません。その代わり、最ももっともらしいデフォルト値を自ら補い、すぐに結果を作り出します。聞き返さないということは、要件の隙間を隠すことと同じ意味になります。

AIが曖昧なプロンプトで作り出した結果を見てから聞き返す手順を最小限にするには、この聞き返しの手順をプロンプト作成の段階に前倒しする必要があります。同僚の開発者との対話で埋めていた空白をAIに委ねる場合は、依頼する時点であらかじめ埋めておかなければなりません。これが、プロンプトを単なる指示文ではなく、要件仕様として扱うべき理由です。

3. 精密なプロンプトのための4つの要素

精密なプロンプトのために考慮すべき事項を4つに整理してみました。それぞれは独立したものではなく、互いに補完し合います。

• 成果物の範囲
  最初に決めるべきことは、何を作り、何を作らないのかを明確に区別することです。「コメント機能」という指示には、返信コメント、いいね、通報、並べ替えオプション、通知連携まで、いくらでもさまざまな意味を含めることができます。範囲を定めなければ、AIが自ら範囲を決めます。そして、その範囲はたいてい最も一般的な実装例に従います。これはそのプロジェクトの文脈とは無関係に決められた範囲であり、実際の要件と異なる可能性が高くなります。
  範囲を明示することは、機能を減らすことではありません。今回のプロンプトで実装する範囲と、次のプロンプトで扱う範囲を分けることです。このような区別があってこそ、成果物に対するレビューも明確になります。

• 既存システムとの関係
  2つ目は、この機能がすでに存在するプログラムの構造とどのようにかみ合うのかを明確にすることです。この掲示板プロジェクトにおける認証方式、投稿エンティティの構造、既存APIのレスポンス形式などの文脈がこれに当たります。AIにはプロジェクト全体をインデックス化し、関連ファイルを自ら見つけて分析する能力がありますが、そのレベルはコードがどのようにつながっているかを把握する程度です。このプログラムの設計意図まで推論することはできません。
  したがって、既存システムとの関係をプロンプトに整理することは、AIの探索範囲を広げることではなく、AIが誤った前提に基づいて結果を作り出すのを未然に防ぐことです。

• 委任の基準
  3つ目は、AIが自ら判断してよい領域と、開発者が直接指定すべき領域を区別することです。たとえば、「削除ポリシーはソフト削除とし、ページング方式は自分で判断して提案して」のように、委任する範囲を明示的に分けます。
  この区別が重要な理由は、前回の記事で述べた認知負債や意図負債に直結するからです。開発者が必ず決めるべき判断（削除ポリシーや権限範囲など、ビジネスルールに直結する決定）をAIに委任すると、その決定の根拠が残らないまま、コードにだけ残ることになります。反対に、AIが判断してもよい領域（実装スタイルや内部メソッドの分割方法など）まで開発者が一つひとつ指定すると、プロンプトの作成に多くの時間がかかります。委任の基準を分けることは、結局のところ、どこまでが監督者の決定で、どこからが実行者の裁量なのかを定めることです。

• 検証方法
  最後は、結果をどのように確認するのかを、依頼する時点であわせて決めることです。「作成者ではないユーザーが削除を試みた場合に403が返されるかを確認するテストも一緒に作って」のように依頼すれば、AIは実装と同時に検証基準も構成します。検証方法を成果物ができてから改めて考えることと、あらかじめ依頼の段階で定義しておくことでは、まったく異なる結果になります。

この4つの事項は、技術的負債、認知負債、意図負債を予防するための最初の関門といえます。範囲と委任の基準をプロンプトの提案段階で明示的に整理すれば、その記録自体が後から参照できる実装意図の痕跡になります。

4. プロンプトの再設計プロセス

曖昧なプロンプトを再設計した場合にどのような違いがあるのかを見てみると、次のようになります。

2つのプロンプトの違いは、長さにあるのではありません。委任と範囲の区別を明確にしているかどうかの違いです。コードスタイルやサービス層の詳細な構造のように、AIに任せてもよい領域はそのまま裁量に残し、削除ポリシーや権限範囲、ページサイズのようにビジネスルールに直結する部分だけを明示的に指定しました。この区別があったため、結果をレビューする時間が大幅に短縮され、再依頼することなく次の段階に進むことができました。

5. プロンプト設計チェックリスト

この経験をもとに、プロンプトを作成する前に参考にできる質問を整理してみました。

• この依頼が失敗する可能性があるのは、どのような点か？
  （結果が出た後に発見する問題を、あらかじめ予想してみます。）

• AIが自分で決めてもよい部分と、私が必ず決めなければならない部分は何か？
  （ビジネスルールに直結する部分は委任しません。）

• 新たに実装しようとしている機能が、既存の構造とどのようにかみ合うのか整理できているか？
  （認証やデータモデルなどの関係を明示します。）

• 結果をどのように検証するかを考え、依頼に含めているか？
  （検証基準を成果物とともに確認できるようにします。）

6. 最後に

良いプロンプトの核心は、明確な境界と委任の記録だと考えています。AIは最終結果の境界を代わりに定めてくれるわけではなく、どのような決定を開発者が下すべきかを自ら判断することもできません。この判断は、その依頼を行う開発者だけが担うものです。
結局のところ、監督者の言語を訓練するということは、新しい依頼に直面するたびに、成果物の境界、既存システムとの関係、委任の基準、検証方法という4つの問いを自ら振り返りながら、プロンプトを作っていく過程です。

 Jin