Codexにリッチなフロントエンドを任せるプロンプト設計

「このページを綺麗にして」だけでは、Codexは何を守り、何を変え、どこまで確認すべきか判断できません。結果として、よくあるカード、無関係なグラデーション、本文を隠すアニメーションへ寄ることがあります。

必要なのは、完成画面の形を細かく命令することではありません。判断の基準と検証可能な完了条件を渡すことです。

先に結論：最小プロンプトは五行でよい

最初から長大な仕様書を渡す必要はありません。対象、目的、守るもの、触ってよい範囲、確認条件を先に置き、Codexにリポジトリを読ませます。

既存の静的サイトを、対象ユーザーが最初の一歩を選べるページへ改善してください。
既存URL、本文の声、検索向けmetadata、広告・計測タグは維持してください。
世界観は「夜の観測室 × 精密な編集紙面」。紫グラデーションと汎用SaaSカードは避けます。
静的HTMLを本体にし、操作は必要な範囲だけ拡張してください。JS無効時も本文を読めるようにします。
実装後はbuild、lint、キーボード、320px、内部リンク、canonical、OG、sitemap、納品物を確認してください。

この短い版は完成条件ではなく、調査を始めるための入口です。実装を任せるときは、次の六層へ具体化します。

OpenAI公式のFrontend prompt instructionsは、既存デザインとframeworkの規約を尊重し、対象ユーザーとdomainに合わせ、主要workflowを使いやすくすることを指示しています。このページはGPT-5.5向けですが、多くのpatternは他のmodelにも適用できると明記されています（2026年9月14日確認）。GPT-5.5向けのModel guidanceも、coding agentへ再利用するもの、テスト期待値、受け入れ条件、継続するか質問するかの境界を明示するよう案内しています。これは特定モデルの成功を保証する話ではなく、長い作業を検証可能な契約へ分けるための参考です。個別Projectのブランド、アクセシビリティ目標、配信方式はProject側の指示として具体化します。

「綺麗にして」では不足する四つの理由

一つ目は、綺麗の意味が共有されていないことです。編集的な余白、密度の高い計器、親しみやすい診断画面では、同じ色やカードを使う理由がありません。

二つ目は、情報の優先順位がないことです。ヒーローを派手にしても、ユーザーが「何のサイトか」「次に何をするか」を理解できなければ失敗です。

三つ目は、変更してはいけない範囲がないことです。既存サイトなら、検索で機能しているtitleやH1、広告タグ、URL、本文の声まで置き換わる危険があります。

四つ目は、完成の定義がないことです。画面が表示された時点で終わるのか、build、キーボード、モバイル、配信物まで確認するのかで作業量が変わります。

プロンプトを六つの層に分ける

長い指示を一枚の文章にせず、次の層へ分けます。

1. 目的と対象ユーザー

「誰が」「どの状況で」「何を判断できるようになるか」を書きます。

対象は、記事サイトから体験型サイトへ進みたい個人制作者。
最初の30秒で、制作経験がProject、Lab、Simulator、Notesの体系として
整理されていることを理解できる状態にする。

この層があると、Codexは装飾より導線を優先できます。

2. 世界観と言語化した対比

色名だけでなく、判断に使える対比を書きます。

夜の観測室 × 精密な編集紙面。
cinematicだがflashyではない。
futuristicだがcyberpunkの定型にしない。
richだがclutteredにしない。

「何であるか」と「何ではないか」を対にすると、ありがちなAIサイトへ寄る範囲を狭められます。

3. 情報構造

セクション名だけでなく、それぞれの役割を書きます。たとえばProject Orbitは最も印象的な場所ですが、目的は線を動かすことではなく、Project間の関係を理解させることです。

ルート、コンテンツモデル、主要導線、静的領域とIslandの境界まで示せると、トップページだけ豪華な状態を避けられます。

4. モーションの目的

「アニメーションを追加」ではなく、許可する用途と禁止する用途を分けます。

• 許可: 状態変化、要素間の関係、選択結果、フォーカス移動の補助。
• 抑制: スクロール上書き、常時動く本文、大きな追従光、全要素の同じfade-in。
• 必須: reduced motion、pointer coarse、tab hidden、listener解除。

Codexが実装を選べる余地を残しつつ、体験を壊す方向は明確に閉じます。

5. 検証条件

解像度の一覧だけで終わらせず、何を確認するかを書きます。

320 / 390 / 768 / 1280pxで横スクロールがない。
キーボードだけでOrbitの全ノードを選べる。
JavaScriptなしでも主要情報が読める。
distの主要URLを直接開ける。
内部リンク、canonical、OG、sitemapを生成物で確認する。

テストコマンドが既にあるなら、その名前も渡します。未知のコマンドを推測させず、package.jsonやREADMEを読ませる指示も有効です。

6. 完了条件

「実装して」で止めず、変更、確認、差分、配信物、記録を一つの完了条件にします。

• 主要ルートが完成している。
• ダミー文章が残っていない。
• lint、typecheck、test、buildが成功する。
• E2Eとa11yの実行条件を整理する。
• upload運用があるなら同期して一致を確認する。
• READMEと判断ログを更新する。
• 既存変更を混ぜずにcommitする。

参照デザインは「コピー元」ではなく「観測項目」にする

スクリーンショットやURLを渡すときは、「このサイトのように」だけでなく、見る場所を指定します。

• 見出しと本文の幅の差。
• セクションごとの密度変化。
• ナビゲーションが内容を隠さない高さ。
• ボタンより本文が強く見える順序。
• 動き始める条件と止まる条件。

固有のロゴ、文章、イラスト、ブランド形状をコピーさせないことも明記します。参照の目的は、好みを伝えることではなく、判断語彙を増やすことです。

実装後の自己レビューをプロンプトに含める

最初の実装が最終品質になるとは限りません。Codexへ、実装後に次を自問し、問題があれば報告だけでなく修正するよう指示します。

1. 同じカードが続いていないか。
2. ヒーロー以外が既製テンプレートに戻っていないか。
3. モバイルが単なる縦積みの劣化版になっていないか。
4. motion offで情報が消えないか。
5. 不要なhydrationやlistenerが残っていないか。
6. title、heading、link、structured dataが本文と一致するか。

BUILD ORBITで使った考え方を一般化する

BUILD ORBITでは、画面の印象を決めるProject Orbitと、検索・直接アクセス・支援技術が読む本文を別の責務として扱いました。Orbitの操作が止まっても、Projectの概要、関連Pattern、AtlasへのリンクはHTMLに残ります。

この判断を別サイトへ移すときは、「目立つ演出を残すか」ではなく「演出がなくても目的を完了できるか」を先に質問します。残すべき操作は状態や関係を理解するためのもの、HTMLへ戻すべきものは本文・見出し・導線です。詳しい確認順はWebサイト公開前のSEO・アクセシビリティ検証チェックリストとBUILD ORBITのMethodに分けています。

AI codingの引き渡し条件を固定する

プロンプトは依頼文だけで閉じず、Codexが返す変更と、次の人が確認する証拠の形まで指定します。特に既存サイトの改善では、成功条件より先に「触ってはいけないもの」を明示しないと、検索向けの本文や既存の体験まで再設計されます。

対象: /guides/ と既存Noteの検索入口
守る: URL、CSS、画像、既存の声、計測・広告、production状態
変える: 読者の判断材料と、既存ルート間の役割説明だけ
証拠: changed files、diff、build、route/link/SEO check、未確認範囲
停止: 外部デプロイ、秘密情報、force push、曖昧な成果指標は実行しない

この形の目的は、AIに作業を縮めさせることではなく、判断の境界を人がレビューできる状態にすることです。PASSはローカル検証、NOT VERIFIEDは未確認の外部状態として報告し、順位・クリック・引用のような実施していない成果を完了条件へ混ぜません。公開可否の一行記録は公開前チェックリストへ、主張と根拠の対応は品質ゲートへ渡します。

長い改善は一件ずつ閉じる

「良くなるまで続けて」だけを渡すと、エージェントは対象を広げたり、同じ不足を別の文言で繰り返したりします。長い改善では、全体を一つの依頼にせず、一つの観測された課題、一つのowner、一つの変更batchを一回の単位にします。長く動くこと自体は成果ではなく、次の判断材料が増えたかで続行を決めます。

BUILD ORBITで証拠をたどる場所

このサイトでは、役割をファイルの層で分けています。Noteの検索入口を直すときも、生成HTMLを直接編集せず、次の対応をたどります。

この対応は、エージェントの要約を信用するためのものではありません。要約をsource、diff、生成物、check結果へ分解し、各主張を一つずつ照合するためのものです。BUILD ORBITで実際に「変更しない」と判断した場合も、検索成果が出たという意味にはせず、確認できる欠落がなかったことと、次に必要な証拠を記録します。

そのまま渡せる一回分の依頼

# 目的
[一つの観測された課題]を、[一つの既存route / owner]で解決する。

# 守るもの
既存URL、CSS、画像、本文の声、計測・広告、production状態。

# 変更範囲
[sourceのファイル]だけ。生成HTMLは直接編集しない。

# 受け入れ条件
[読者の判断材料または自然な次の導線]が一つ増え、既存のcheckが通る。

# 証拠
変更前後のgit diff、実行したcheck、未確認の外部状態、upload parity。

# 継続と停止
このbatchを検証してから続行する。新しい証拠がなければ、metadataの言い換えやno-op commitを作らない。

この依頼は、エージェントを無期限に走らせるための命令ではありません。目的、制約、受け入れ条件、証拠、次の判断を一回ごとに閉じることで、長い作業でも変更の責任範囲を保ちます。

Codexの完了報告をレビューする

完了報告は「実装しました」だけでなく、次の対応表で読みます。

「確認した」と書かれているだけでURLや結果がない場合は、完了ではなく追加確認として扱います。npm auditがCA証明書エラーなどで取得できないときも、0件と読み替えず「未取得」と報告するのが正しい境界です。

再利用できる最小テンプレート

# 目的
誰が、何を理解・判断できるサイトか。

# 守るもの
既存URL、本文、検索向けshell、計測・広告、ブランド。

# 世界観
3〜5個の基準語と、避ける定型。

# 情報構造
主要ルート、セクションの役割、データモデル。

# インタラクション
操作前後で増える理解、fallback、reduced motion。

# 技術制約
stack、静的出力、JS予算、依存追加の扱い。

# 検証
コマンド、breakpoint、keyboard、no-JS、配信物。

# 完了条件
実装、自己レビュー、修正、差分、commit、納品。

良いプロンプトは、すべてのピクセルを先に決める設計書ではありません。Codexが自律的に選べる範囲と、越えてはいけない境界を同時に渡すものです。その境界が検証可能なら、見た目の大胆さと実運用品質を両立しやすくなります。

よくある質問

次に静的サイトの実装境界を決めるなら、Astroで静的なインタラクティブサイトを作る構成と実装を読み、操作の品質を確認するときはAstroで静的HTMLにインタラクティブ機能を追加する設計へ進みます。

この構成を自分の依頼へ移すときは、AIサイト制作 要件定義テンプレートへ目的、守るもの、技術制約、検証、完了条件を書き出せます。