プロンプトで実装品質の大半が決まる

AI 駆動開発を始めたエンジニアからよく聞くのが、「同じ Claude Code や Cursor を使っているのに、人によって出力の質が全然違う」という相談です。原因の多くはツールの設定でも、モデルの性能でもありません。AI に渡す指示、つまりプロンプトの設計に差があります。

結論から書きます。AI 駆動開発における実装の品質は、コードを書く前のプロンプトでほぼ決まります。AI は与えられた文脈と制約の範囲で、もっとも妥当に見える解を出すだけです。目的が曖昧なら曖昧なコードが、守るべき制約を伝えなければ既存の作法を無視したコードが返ってきます。これは AI の能力不足ではなく、指示の不足です。

ここで言うプロンプト設計は、世間で語られる「魔法の呪文」を探すこととは違います。語尾を工夫したり、丁寧な敬語を使ったりしても品質はほとんど変わりません。本当に効くのは、目的・文脈・制約・完成条件という、人間のエンジニアに仕事を頼むときと同じ情報を、過不足なく構造的に渡すことです。AI 駆動開発そのものの全体像は AI 駆動開発とは何か で整理しているので、前提として目を通しておくと本記事の位置づけが掴みやすくなります。

この記事では、FIXIT が実際のクライアントワークと社内開発で使っているプロンプト設計の型を、Claude Code と Cursor の実務パターンに落とし込んで共有します。

良い実装指示の構造 — 目的・制約・受け入れ条件・参照

良い実装プロンプトには、共通する 4 つの要素があります。順に説明します。

ひとつめは目的です。何を作るのかではなく、なぜそれが必要で、誰がどう使うのかまで含めて伝えます。「ログイン画面を作って」ではなく「既存ユーザーが再訪時に素早く認証できるよう、メールとパスワードでのログイン画面を追加したい」と書くだけで、AI はエラー表示や入力補助の必要性を自分で推測できるようになります。

ふたつめは制約です。使ってよいライブラリ、従うべきアーキテクチャ、書いてはいけないパターンを明示します。制約がないと、AI はそのコードベースで一般的でない書き方を平気で持ち込みます。

みっつめは受け入れ条件です。これが揃っているプロンプトと欠けているプロンプトでは、出力の安定度がはっきり変わります。どのテストが通れば完成なのか、何を壊してはいけないのかを、作業を始める前に言語化しておきます。受け入れ条件は AI にとってのゴール定義であり、人間にとってはレビューのチェックリストにもなります。

よっつめは参照です。AI が真似すべき既存のコードや、関連するファイル、仕様書を指し示します。AI 駆動開発では、ゼロから書かせるより「この書き方に揃えて」と参照を与えるほうが、コードベースの一貫性が保てます。

この 4 要素を一文ずつ並べるだけで、プロンプトの骨格になります。たとえば次のような形です。

目的: 既存の決済フローに、クーポンコード入力欄を追加したい。割引はサーバー側で検証する。
参照: src/features/checkout/PaymentForm.tsx の構成と、既存の useCoupon フックに揃える。
制約: バリデーションは既存の zod スキーマに追記する。新しい状態管理ライブラリは入れない。
受け入れ条件: 無効なコードでエラー表示が出ること。既存の決済テストが全て通ること。

長文の散文で説明するより、この 4 つのラベルで整理したほうが、自分の思考も整理され、AI の精度も上がります。ただし、各行を機械的に羅列するのではなく、複雑なタスクでは目的の背景を地の文で補うと、より意図が伝わります。

文脈を渡す設計 — CLAUDE.md・spec・コードベース参照

プロンプトに毎回すべての前提を書くのは現実的ではありません。プロジェクト共通の文脈は、別のレイヤーで AI に渡しておくのが基本です。

中心になるのが CLAUDE.md です。技術スタック、ディレクトリ構成、命名規則、レビューの観点といった「このプロジェクトでは当たり前」の情報をここに集約しておけば、毎回のプロンプトでは個別タスクの差分だけを書けば済みます。CLAUDE.md の書き方そのものには勘所があり、CLAUDE.md ベストプラクティス で具体的な構成例をまとめています。プロンプト設計を磨く前に、まず共通文脈の置き場所を整えることをおすすめします。

次に仕様 (spec) です。やや大きめの機能をまとめて実装させたい場合、いきなりコードを書かせるのではなく、先に仕様を文書として固め、それを参照させると安定します。仕様には、満たすべき振る舞い、画面遷移、データの形、エッジケースを書きます。この「先に仕様、後から実装」という進め方は AI と特に相性がよく、AI と進める仕様駆動開発 で詳しく扱っています。プロンプトに直接書ききれない複雑さは、仕様書に逃がすという発想です。

最後にコードベースの参照です。Claude Code はファイルを自分で読みに行きますが、「どこを読むべきか」を最初に示すと、無駄な探索が減り精度が上がります。Cursor では関連ファイルを明示的にコンテキストに含めることで、既存のパターンを踏襲しやすくなります。どちらも、AI に推測させる範囲を減らすほど、結果が安定するという点は共通しています。そもそも参照しやすく推測の余地が小さいコードベースをどう設計するかは AI 駆動開発のアーキテクチャ設計 — AI が書きやすい構造 で深掘りしています。

文脈を渡す設計の要点は、情報をどこに置くかの判断です。毎回変わらない前提は CLAUDE.md へ、機能単位の仕様は spec へ、そのタスク固有の事情だけをプロンプトへ。この三層に切り分けると、プロンプトは短く保ちつつ、AI に渡る情報量は十分に確保できます。

曖昧さを潰す制約の与え方とアンチパターン

AI が期待外れの出力を返すとき、その多くは指示の曖昧さに起因します。曖昧さを潰すには、禁止と既定値の二方向から制約をかけるのが有効です。

禁止は「やってはいけないこと」を明示することです。「新しい依存を追加しない」「既存の API のシグネチャを変えない」「このディレクトリには触らない」といった一文を入れるだけで、想定外の変更を未然に防げます。AI は良かれと思って広範囲を書き換えることがあるため、変更の境界を引いておくことが効きます。

既定値は「迷ったらこうする」を伝えることです。「命名は camelCase で統一」「エラーは既存の AppError でラップする」のように、判断の分岐点で AI が取るべきデフォルトを示します。これにより、細かい選択でコードベースの作法から外れるのを防げます。

ここで、よく見るアンチパターンを挙げておきます。

ひとつは一度に多くを頼みすぎることです。「認証機能を作って、ついでにテストとドキュメントとリファクタリングも」とまとめて投げると、どれも中途半端になりがちです。タスクは小さく割り、ひとつ完成させてから次へ進むほうが、結果的に速く確実です。

もうひとつは曖昧な形容詞に頼ることです。「いい感じにして」「きれいに書いて」では、何を良しとするかが AI に伝わりません。良いの基準を、参照や受け入れ条件という具体に翻訳します。

そして見落としがちなのが、過剰な制約です。すべてを縛りすぎると、AI が妥当な改善提案をできなくなり、ただの作業代行になってしまいます。守ってほしい核を制約として固め、それ以外は AI の判断に委ねる。この線引きが、AI 駆動開発の生産性を左右します。

反復とレビューを前提にしたプロンプトの回し方

プロンプトは一発で過不足のない出力を狙うものではありません。AI 駆動開発は、人間がレビューし、ずれを補正しながら収束させる反復のプロセスです。前提として、1 回で仕留めようとしないほうが、結果的に速く良いコードに辿り着きます。

反復の進め方には型があります。最初のプロンプトでは、いきなり全実装を頼まず、まず方針を出させると安全です。「どう実装するつもりか、ファイル単位の計画を先に説明して」と頼み、計画段階でずれを正します。ここで方向性を合わせておけば、実装後の大きな手戻りを防げます。

実装が返ってきたら、出力を直接書き換えるのではなく、指示を直す発想を持ちます。期待とずれた箇所があれば、何を誤解していたかを 1 点特定し、その前提だけを補って指示し直します。「ここはこう直して」と部分修正を重ねるより、「この前提が抜けていた」と根本を補正するほうが、後続の出力も安定します。

対話が長引いて迷走し始めたら、撤退の判断も必要です。同じ修正を何度も繰り返している状態は、文脈が汚れているサインです。そういうときは、整理し直したプロンプトを新しいセッションで 1 から渡したほうが速いことが多くあります。AI との対話に固執せず、リセットを恐れないことも実務上のコツです。

そして、反復のどの段階でも、最終的な品質保証は人間のレビューが担います。AI が書いたコードを読まずにマージするのは、AI 駆動開発ではなく、ただのリスクです。テストで自動的に守れる部分は受け入れ条件に組み込み、設計判断や意図の妥当性は人間が見る。この役割分担を前提にプロンプトを設計すると、速度と品質を両立できます。レビューを前提とした開発の進め方は AI 駆動開発とは何か でも触れています。

タスク種別ごとのプロンプトパターン集

実務では、タスクの種類ごとにプロンプトの型が見えてきます。代表的なパターンを 4 つ紹介します。いずれも、前述の目的・参照・制約・受け入れ条件の枠に沿っています。

新規機能の実装では、参照と受け入れ条件を厚くします。似た既存機能をひとつ指定し、「この構成に揃えて」と伝えたうえで、完成の判断基準を列挙します。ゼロから設計させるのではなく、既存パターンへの追従を軸にすると、コードベースの一貫性が崩れません。

バグ修正では、まず再現条件と期待挙動を正確に渡します。「直して」ではなく、「この入力でこのエラーが出る。正しくはこう動くべき」と、現状と期待のギャップを明確にします。さらに「原因を先に説明してから直して」と頼むと、対症療法ではなく根本修正に向かいやすくなります。

リファクタリングでは、振る舞いを変えないことを最優先の制約として固定します。「外部から見た挙動とテスト結果を変えずに、内部構造だけを整理する」と明示し、対象範囲を区切ります。ここで範囲を絞らないと、AI は際限なく書き換えを広げてしまいます。

テストコードの作成では、何を保証したいのかを伝えます。「正常系だけでなく、空入力・境界値・権限なしのケースを含めて」と観点を指定すると、網羅性が上がります。既存のテストファイルを参照させ、書式とアサーションのスタイルを揃えるのも効果的です。

これらのパターンは、繰り返し使うなら保存しておくと負担が減ります。Claude Code ならカスタムスラッシュコマンドとして、Cursor ならルールやスニペットとして、穴埋め式のテンプレートを用意しておけば、毎回ゼロから書かずに済み、チーム内での品質のばらつきも抑えられます。

FIXIT のプロンプト運用ノウハウ

ここまでが個人レベルでのプロンプト設計です。FIXIT が AI 駆動開発のクリエイティブスタジオとして複数のクライアントワークで実践しているのは、これをチームの運用に乗せる仕組みづくりです。

私たちが重視しているのは、プロンプトを属人化させないことです。優秀なエンジニアの頭の中にある良い指示の型を、CLAUDE.md とカスタムコマンドという形で言語化し、チーム全員が同じ品質で AI を動かせるようにします。プロンプトの巧拙が個人差で終わると、組織としての再現性が生まれません。

具体的には、プロジェクト立ち上げ時にプロンプトの基盤を整えます。共通文脈を CLAUDE.md に集約し、頻出タスクをテンプレート化し、受け入れ条件を CI で自動チェックできる形に落とします。ここを最初に整えておくと、後から参加するメンバーも初日から一定の質で AI 駆動開発に乗れます。

もうひとつの勘所は、プロンプトとレビュー基準を一体で設計することです。受け入れ条件をプロンプトに書くということは、レビューで見るべき点を先に決めるということです。私たちは、AI に渡す指示と、人間がレビューで確認する観点を同じドキュメントから派生させることで、指示・実装・レビューの間にずれが生まれない流れを作っています。

こうした運用設計まで含めた AI 駆動開発の進め方は、AI 駆動開発サービス として体系化しています。プロンプト設計を個人の工夫で終わらせず、プロダクトの品質に直結する仕組みとして実装したい場合は、ここが起点になります。

まとめ

AI 駆動開発の実装品質は、コードを書く前のプロンプトで大半が決まります。鍵になるのは、目的・参照・制約・受け入れ条件という 4 要素を構造的に渡すこと。毎回変わらない前提は CLAUDE.md と仕様書に逃がし、プロンプトにはそのタスク固有の差分だけを書く。そして一発で仕留めようとせず、計画を先に出させ、指示を直しながら反復し、最後は人間がレビューで品質を保証する。

この型はツールに依存しません。Claude Code でも Cursor でも、効くのは同じ原理です。まずは目の前のひとつのタスクで、4 要素を一行ずつ書き出すところから始めてみてください。

AI 駆動開発をチームで本格的に始めたい方は、導入の全体像をまとめた AI 駆動開発のはじめ方ガイド をご覧ください。プロンプト設計からレビュー体制までを、実務に落とすための手順が掴めます。