AIコーディングツールの出力品質は、指示の構造で決まる。開発チームが直面する「書き直しループ」の原因は、ドメイン知識・開発文脈・意図の伝達、この三層の設計不足にあった。実装現場で蓄積した指示パターンを整理する。

AI指示設計が必要になった理由

「これ、動くけど使えない」。レビュー中のPRに、そうコメントを書いた。Claude Codeが生成したNotionのWebhook受信処理。エラーハンドリングは完璧だが、受け取るべきプロパティ名が古い仕様のままになっている。

問題は、AIに何を伝えていないかが見えにくいことだった。「Notion APIでWebhookを受け取る処理を書いて」という指示は、構文的には通る。ただ、今回必要なのは「v2移行後の`properties`構造を前提に、`title`ではなく`rich_text`配列から本文を取得する処理」。この文脈が抜けていた。

指示を三層に分けて設計し始めたのは、この経験からです。ドメイン知識、開発文脈、意図の伝達。それぞれに異なる粒度と役割がある。

ドメイン知識を指示に織り込む

最初の層は、業務やサービス固有の知識。AIはプロンプト品質を補完できても、あなたの会社の業務フローは知らない。

先月、Slackボットに「営業案件のステータス更新を通知する機能」を追加した際、最初の指示はこうだった。「ステータスが変わったら通知」。出力されたコードは、全ての変更を通知する仕様になっていた。必要なのは「`pending`から`approved`に変わった場合のみ、該当チャンネルにメンション付きで通知」という条件。

この条件は、営業フローを知らなければ書けない。どのステータスが重要で、誰に届けるべきかは、AIが推論できる範囲を超えている。ドメイン知識を指示に含めるかどうかで、出力の実用性が分かれる。

具体的には、状態遷移図・承認フロー・データの依存関係を、コメントまたはコンテキストとして渡す。Cursorであれば`.cursorrules`に業務用語の定義を記述し、Claude Codeであればプロジェクトファイルとして参照させる。これで、指示を毎回書き直す手間が減った。

開発文脈で出力を制御する

二層目は、技術的な制約と設計意図。フレームワークのバージョン、採用しているアーキテクチャ、既存コードとの整合性。これらを明示しないと、AIは一般的な実装を返す。

「ログイン処理を追加して」と指示した際、返ってきたのはJWT認証のフルスタック実装だった。今回必要なのは、既存のFirebase Authと連携し、uidをCookieに保存するだけの薄い層。この齟齬は、開発文脈が伝わっていないことが原因です。

指示を「Firebase Admin SDKでuidを検証し、express-sessionを使って`req.user`にユーザー情報を格納するミドルウェアを作成。既存の`authMiddleware.ts`に追記」と書き換えた。生成されたコードは、そのままマージできる品質になった。

CodexとClaude Codeの使い分けも、ここで決まる。既存ファイルの修正や型定義の参照が必要ならCodex、新規機能の設計や複数ファイルにまたがる変更ならClaude Code。前者はエディタ統合で文脈を自動取得し、後者は会話形式で段階的に仕様を詰められる。修正ループを減らすには、どちらが今の文脈に適しているかを判断してから指示を書く。

意図を構造化して伝える

三層目は、なぜこのコードが必要なのか、という目的。AIは「何を作るか」には答えられるが、「なぜ必要か」は推測でしか補えない。

先週、Notion DBの更新処理をリファクタリングした際、「重複チェックを追加して」とだけ指示した。返ってきたのは、全レコードを毎回取得して比較するコード。必要だったのは「同一の`external_id`を持つレコードが既に存在する場合、更新処理をスキップすることで、API呼び出し回数を削減する」仕様。

意図を含めると、出力が変わる。「API制限を回避するため」という目的が伝われば、AIはキャッシュや差分更新を提案してくる。「パフォーマンス改善のため」なら、インデックスやバッチ処理が選択肢に入る。

指示テンプレートとして、こう書いている。目的・制約・期待する動作・想定される入力例。この4要素を2〜3文で記述してから、具体的な処理内容を指示する。テンプレート化することで、指示の抜け漏れが減り、レビュー時の手戻りも少なくなった。

指示設計は開発設計の一部

AI指示設計は、ドキュメント作成でも命令文の工夫でもない。ドメイン知識を言語化し、開発文脈を整理し、意図を構造化する行為そのものが、設計の質を上げている。

指示を書く過程で「なぜこの処理が必要なのか」が明確になり、レビューで「このケースは考慮されているか」と問う視点が生まれる。AIが出力したコードが期待と違うとき、それは指示の曖昧さを教えてくれている。

この指示設計パターンは、チーム内で共有し始めています。あなたのチームではどう分解していますか。