【ITニュース解説】Stop Asking Cursor to “Build This”, Use These Prompts Instead

AIコーディングアシスタント、特にCursorのようなツールは、現代のソフトウェア開発において非常に強力な味方となる可能性がある。しかし、多くの開発者がAIに「この機能を作ってほしい」と漠然と指示し、期待外れの、ほとんど動作しないコードを受け取ってしまう経験をしている。これは、AIをまるでプロジェクトの背景を全く知らない新人のインターンのように扱っていることに起因する。曖昧な指示、制約の欠如、具体的な例の提示がない状態では、AIはプロジェクトの固有の要件を理解できず、最終的にはコードの整合性の欠如や、意図しないアーキテクチャの導入など、多くの問題を抱えたコードを生成してしまう。

このような問題が発生する原因は、AIがプロジェクトに関する十分な文脈（コンテキスト）を持っていないことにある。「ログイン画面を作って」と指示するだけでは、AIはプロジェクトのフォルダ構造、状態管理の手法、命名規則、API呼び出しの方法、エラー処理のパターンなど、多くの重要な情報が不足している。AIはこれらの空白を、一般的で、時には古くなってしまったチュートリアルや、現在のプロジェクトのスタイルとは合わないパターンに基づいて補完しようとする。その結果生成されるコードは、一見すると「だいたい合っている」ように見えるが、実際にプロジェクトに組み込もうとすると、全くフィットしないものになってしまう。

多くの開発者がこうした漠然とした指示を続けてしまうのは、Google検索やStack Overflowでの情報検索の習慣が影響している。これらのプラットフォームでは、短い漠然としたクエリでも、しばしば求めている答えにたどり着くことができる。しかし、AIによるコード生成は検索とは根本的に異なる。AIは指示された内容に従ってコードを生成する「指示従順型」のツールであり、その指示は構造化され、具体的であるほど有用な結果を生み出す。よくある間違いとしては、一つのプロンプトで機能全体を要求したり、アーキテクチャ、使用するパッケージ、命名規則などを具体的に指定しなかったり、AIに既存のコードスタイルの例を与えなかったりすることが挙げられる。また、コード生成前にAIにそのコードの作成意図や考え方を尋ねることなく、生成された最初の出力をそのまま受け入れてしまうことも、問題のあるコードを生み出す原因となる。

このような問題を解決するためには、単一の漠然としたプロンプトではなく、「プロンプトのフレームワーク」を適用することが重要だ。AIはブリーフィングを必要とするペアプログラマーのように扱うべきである。具体的には、AIに対して以下の要素を提示することが求められる。まず「コンテキスト」として、プロジェクトの概要や使用している技術スタックを伝える。次に「制約」として、採用しているアーキテクチャパターン、命名規則、フォルダ構造などを明確にする。さらに「スコープ」として、一度に一つの小さなタスクに限定し、機能全体ではなく、その一部分に焦点を当てる。可能であれば、「例」として、既存のコードスニペットを提供し、AIにコードスタイルを合わせるよう促す。最後に「出力形式」として、単にコードを生成するだけでなく、そのコードに関する説明や、どのような仮定に基づいて生成したかなども報告するように求める。このアプローチにより、AIは単なる推測から、プロジェクトの標準に厳密に従う信頼できるコーディングパートナーへと変貌する。

このフレームワークを実践するには、段階的なアプローチが有効である。最初のステップとして「セットアップ」がある。これは、コード生成の依頼をする前に、Cursorに対してプロジェクト全体のコンテキストを最初に与えることである。Cursorの場合、プロジェクトのルートディレクトリに.cursorrulesファイルを作成するか、チャットの最初のメッセージとしてシステムレベルのプロンプトを送信することで、これを実現できる。このファイルに、例えばFlutterプロジェクトでクリーンアーキテクチャ、Riverpodによる状態管理、Dioによるネットワーク通信、Freezedによるモデル定義を使用していることや、API呼び出しは常にリポジトリクラス内で行いウィジェット内では行わない、ファイル名はスネークケース、クラス名はパスカルケースを用いる、といった具体的なルールを記述する。この一度のセットアップにより、以降のすべてのプロンプトは、プロジェクト固有のルールとコンテキストの中で解釈されるようになり、一般的なデフォルト設定に基づく推測を大幅に減らすことができる。

次のステップは「設定」で、タスクのスコープを狭く設定することだ。「ユーザー認証機能を構築して」といった広範な指示ではなく、「lib/data/repositories/user_repository.dartの既存のリポジトリパターンに従って、/api/loginへのPOSTリクエストでログインを処理するAuthRepositoryクラスを作成し、Result<User>型を返すようにする」といったように、タスクを具体的かつ限定的に定義する。タスクのスコープが狭ければ狭いほど、AIが誤った仮定に基づいてコードを生成するリスクは低減される。

三つ目の「コア実装」のステップでは、具体的なプロンプトテンプレートを活用する。これは、機能開発のための再利用可能なプロンプトの骨組みとなる。「コンテキスト：[この機能が何をするか、どこに位置するか]、制約：[従うべきアーキテクチャ、パッケージ、パターン]、タスク：[構築する単一の具体的なこと]、参照：[スタイルを合わせる既存のファイル/クラス]、出力：コードを生成し、その後、行った仮定について説明する」という形式を使用する。例えば、Flutterアプリのログインリポジトリを作成する場合、「コンテキスト：クリーンアーキテクチャを使用するFlutterアプリのログイン機能が必要だ。制約：ネットワークにはDioを、状態管理にはRiverpodを使い、例外をスローする代わりにResult<T>を返すこと。タスク：login(email, password)メソッドを持つAuthRepositoryを作成する。参照：lib/data/repositories/user_repository.dartのパターンに従うこと。出力：コードを生成し、その後、行った仮定について説明する」と指示する。これにより、AIはリポジトリパターンに従い、Result<T>ラッパーを使用し、既存の命名規則やエラー処理パターンに沿ったコードを生成するようになる。LaravelのAPIエンドポイントの場合も同様に、コントローラーを薄く保ち、ビジネスロジックをサービス層に置くといった制約を明確に指示することで、期待通りのコードが得られる。

最後のステップは「最終統合」として、AIに生成したコードのレビューを依頼することである。コードが生成された後も、そこで終わりではない。追加のプロンプトとして、「今生成したコードをレビューしてほしい。以下の点を確認する：エラー処理の抜けがないか、プロジェクトの他の部分との命名の一貫性があるか、定数や環境変数にすべきハードコードされた値がないか」と依頼する。この二度目のパスによって、AIの最初のドラフトでは見落とされがちな、ヌルチェックやトークンの有効期限切れといったエッジケースを含む問題を捕捉できる可能性が高まる。

AIコーディングアシスタントを活用する上で、開発者がよく犯す間違いを避けることは非常に重要だ。一つのプロンプトで機能全体を要求すると、コンテキストが曖昧になり、一貫性のないファイルが生成されやすくなるため、機能を小さなプロンプトに分割して依頼することが推奨される。また、既存のコードスタイルの参照を提供しないと、AIは一般的なパターンに頼ってしまい、プロジェクトのスタイルに合わないコードが生成される。.cursorrulesファイルを使わないのは、最も活用されていない機能の一つであり、これがないと毎回技術スタックを説明し直すことになり、AIがプロジェクトの文脈を理解する上で大きな違いを生む。生成されたコードをレビューせずに受け入れることも危険であり、AI生成コードは見た目は正しくても、エッジケースを見落としていることがあるため、注意が必要だ。さらに、出力形式を指定しないと、AIは理由の説明なしにコードだけを生成するため、後でコードを理解したりデバッグしたりすることが困難になる。

これらの課題を乗り越え、AIを最大限に活用するためのベストプラクティスがある。一つのプロンプトには一つのタスクのみを含め、小さくスコープされた要求ほど信頼性の高いコードが生成される。プロジェクトのアーキテクチャが進化するにつれて、.cursorrulesファイルを常に更新し、最新の状態を保つことが大切だ。既存のファイルを常に参照として提供することで、AIはスタイルと構造を正確に合わせることができる。また、複雑なロジックのコードを生成する前に、AIにそのアプローチの「理由」を尋ねることで、意図を理解しやすくなる。ResultやEitherのような型を使用してエラー処理を予測可能にし、AIがそれを一貫して複製できるようにすることが望ましい。さらに、優れたプロンプトテンプレートはチーム全体で再利用できるよう、リポジトリ内の専用フォルダに保存し、バージョン管理するべきである。

このプロンプトフレームワークは、単なる個人的なサイドプロジェクトだけでなく、実際に本番環境のソフトウェアを出荷するチームでも活用されている。SaaSアプリケーションの開発チームは、.cursorrulesファイルを利用して、多数の貢献者間でサービス層やリポジトリ層の一貫したパターンを強制している。モバイルアプリケーションのFlutterチームは、スコープを絞ったプロンプトを使って、手動でのボイラープレート作業なしにクリーンアーキテクチャに合致する機能モジュールを生成している。管理ダッシュボードのLaravelチームは、構造化されたプロンプトを用いることで、AIがドラフトの大部分を記述しても、コントローラーを薄く保ち、ロジックをテスト可能な状態に維持している。企業では、AIが生成したプルリクエストを人間のものと同様にレビューすることが増えており、AIの出力が最初から社内スタイルに従っている場合にのみ、このプロセスが効果的に機能する。

結論として、AIコーディングアシスタントから得られるコードが、単なるフラストレーションの種になるか、あるいは真に有用なものになるかは、AIモデル自体の性能よりも、プロンプトの質に大きく依存する。AIに「これを作って」と指示し、AIがすべてを理解することを期待するのではなく、プロジェクトのコンテキスト、制約、タスクのスコープ、そして既存のコードの参照を具体的に提供することが重要だ。また、AIにそのコード生成の背後にある理由を尋ね、ジュニア開発者のプルリクエストをレビューするように、生成された出力を注意深くレビューする習慣を身につけるべきである。これらの実践を一貫して行うことで、CursorのようなAIツールは、チームの真の拡張機能となる信頼できるパートナーへと進化するだろう。