成功に導くプロンプティングと言語化の習慣

はじめに

「AIエージェントを使った開発でもっと生産性が上がると思ったのに、実際にはそうでもない」「何度も同じことを説明している」「プロジェクトが大きくなるとエージェントが迷子になる」
このような課題を抱えている開発者は多いのではないでしょうか。
※以降、「AIエージェント、コーディングエージェント」を単に「エージェント」と述べる

私は開発のプロンプトでさえもエージェントに作らせていました。
CLAUDE.mdにプロンプトを書きだして実装を進めましたが、
エージェントとの対話が非効率になってしまう場面を何度も経験しました。

私はエージェントは非決定論的に動き、文章を補完するという原則を学び、
丁寧に言葉化することで、私の文脈で（ここ重要）効率と品質を向上させることができました。

本記事では、N番煎じのポートフォリオサイト個人開発の体験を題材に、
言語化の習慣を進める理由を説明します。

技術的な前提

• 領域
  • Web開発
• Agent
  • Claude Code
• ポートフォリオサイトの技術
  • フレームワーク: Next.js
  • インフラ+その他：Vercel
  • DB：なし

エージェントとの対話でユーザは自分を見失う

ポートフォリオサイト開発は簡単な部類なので、zennを見ているような人々はそれとなく作れるでしょう。
まったくやる気のない私は、ぼんやりと作りたいサイトをイメージし、
V0に打ち込むことから始めました。

個人のポートフォリオサイトを作成してください。
モダンな雰囲気で情報は最小限に絞ります。
自己紹介、SNS、ブログなどのアウトプット一覧、お問い合わせが画面に用意されます。

output↓

いい感じに骨子ができましたね。
次は細かい要求を伝えて作っていきます。
これも面倒だったのでインタラクティブに実装していこうと考え、プロンプトを用意します。
まずはCLAUDE.mdの用意から始めました。

これはV0で作成したNext.jsベースのポートフォリオサイトを管理するプロジェクトです。
Vercelにデプロイされ、mainブランチに変更がマージされると自動的にデプロイされます。
これからCLAUDE.mdに開発に必要となるプロンプトを用意します。
アーキテクチャの概要、設計指針、開発手法（TDD）を明記してください。

次に要件定義を進めます。

これからポートフォリオサイトの細部を作りこみます。
どんな機能を付けたいかユーザにヒアリングしつつ要件定義を進めてください。
最後にREADME.mdにプロジェクトの概要を書き出してください。

🤖はい、承知しました。
🤖ユーザはポートフォリオサイトの細部の作りこみを求めています。
まず一覧にまとめ...
...

最後に実装です。
最小限の単位でコンポーネントの修正をエージェントに依頼していきました。

結果、50回くらいはセッションをやり直して理想にたどり着きました。 悲しい

怠け者が学んだ3つの教訓

この経験から次の3つを学べました。

1. ユーザは常套句に惑わされる
2. 自分の言葉で期待を伝えるべし
3. 開発過程でドキュメントが陳腐化

より少ない回数で高品質に仕事を終わらせるためにも、それぞれ掘り下げてみましょう。

ユーザは常套句に惑わされる

エージェントは学習した情報を元に最も可能性が高い予測を出力します。
ということは「よくある言い回し」「常套句」が増える可能性が高いです。
正しく見えるため、気を抜くと思考停止でApproveするマシンになります。
これでは当然、自分らしい言語化はできていないので期待外れの結果となるでしょう。

期待と現実のギャップを埋めるために必要な情報が含まれていて、詳細に説明できる必要があります。
どの程度の説明が必要かは場合に寄りますが、参考までに自分の例を出してみます。
私は次の項目について言語化されていれば理想的だという感覚があります。

• エージェントのふるまいの期待
• 制約事項（絶対守ってほしい条件など）
• 開発指針
• アーキテクチャ
• ドメイン特有の情報（ユビキタス言語など）

眺めてみると、私たちが新しい職場に来た時に欲しい情報ばかりですね。
エージェントも訓練されているので、補完の精度もかなり良くなるはずです。

自分の言葉で期待を伝えるべし

自分にとって稚拙すぎたり、逆に賢すぎたりするプロンプトを考えずに再利用すると想定通りに動きません。
自分の深い理解がベースとなったドキュメントがあれば、エージェントのアウトプットを適切に評価し、ふるまいをコントロールできます。

また、可読性が高い既存ドキュメントはエージェントにとっても同様だと感じています。
つまり、エージェントを同僚とみなし、同僚がドキュメントを読むことを考えて書くとよいでしょう。

さらに、インタラクティブに伝える場合はさらなる集中力を要します。
整理された文章と違い、入力過程で作業にノイズとなる情報が入り込んで補完の精度が悪くなります。
その前提で使うとイライラしなくてよくなりそうです。

ドキュメントが高速で陳腐化

初期設計から変更されることはよくあります。
機能追加やリプレースでドキュメントを書き直しますよね。

エージェントによって実装速度は革命的に早くなっています。
当然のことながらドキュメント更新頻度も高まります。
いずれエージェントが特定の分野で人類の能力を越えている姿は想像に難くはないですが、
継続的なドキュメント更新は十分に取り組む価値があると思います。
文書の陳腐化を防ぐために、開発プロセスにドキュメント更新を組み込むのもおすすめです。

所感

今回の開発体験を通じて、
自分の言葉で可読性の高い文章の言語化を目指すことでドメインにおける品質が高まる
という実感を得ました。

プロンプトは再利用可能にすることもできます。
チームで開発していても自分の手元にとどめているだけではもったいないので、
小さく初めてチームに共有し、メンテナンスすることをお勧めします。

ただ、PoCくらいなら使い捨てでもいいと思います。ざっくりでいいので。

まとめ

エージェントを活用した開発では、あらゆる文脈を適切に伝えることが重要です。
私は言語化スキルを身に着けておくとプロンプティングに限らず「つぶしが効く」と強く信じています。

言語化し、継続的に更新することで、開発効率は大幅に向上します。
冒頭と同じような課題を抱えている方は、ぜひ自分の言葉で課題を言語化するところから始めてみてください。