AIに破綻しないコードを書かせる
「Chrome拡張機能 初期設計プロンプト」

いきなりコードを書かせず、アーキテクチャと型を固めさせるための第1ステップ指示書

なぜ「いきなりコードを出力させる」と失敗するのか

AI（LLM）に対して「〜なChrome拡張機能を作って」と単に指示を出すと、1つのファイルにすべての処理を詰め込んだ長大なコードをいきなり生成しようとする。

初期動作はしても、機能追加やデバッグを行う段階になると、コードの肥大化によってAI自身が過去の文脈や全体構造を把握できなくなり、修正不可能なバグを引き起こす。

この問題を回避するためには、「実装コードを書かせる前に、モジュール構造・型定義・PROJECT_MAPの設計のみをまず最初に出力させる」手順の強制が不可欠である。

プロンプトに組み込まれた4つの設計ルール

本プロンプトでは、AIに対して以下の4つのアーキテクチャルールを厳格に指定している。

  • 1
    単一責任の原則に基づくモジュール分割
    画面描画（/components/）、通信処理（api.js）、ロジック（utils.js）のようにファイルを機能単位で分割定義させる[cite: 5]。
  • 2
    JSDocによる型定義の事前明示（types.js）
    データ構造をプログラムの最初に固定定義させ、AIが出力するデータキー（プロパティ名）の揺れや命名のブレを防ぐ[cite: 5]。
  • 3
    多言語化（i18n）前提の辞書キー管理
    内部データに「進行中」等の言語依存文字列を持たせず、statusInProgress 等の言語非依存キーで保持させる規則を強制する[cite: 5]。
  • 4
    PROJECT_MAP.md 草案の作成指示
    システムの全体図（アーキテクチャマップ）を初期出力段階で作成させ、開発継続時の文脈維持用テキストを自動生成させる[cite: 5]。

プロンプト記述サンプル

以下は、新規にChrome拡張機能（Manifest V3）を作成する際、AIへ投じるプロンプトの全文である。[例: ...] の記述部分を作成したいツールの仕様に書き換えて利用する。

あなたには熟練したChrome拡張機能（Manifest V3）エンジニアとして、新しい拡張機能の初期設計およびコード生成を担当してもらいます。

コードの肥大化を防ぎ、今後の追加開発をスムーズに行うため、以下の設計ルールとステップに厳格に従って出力してください。

### 【作成したい拡張機能の概要】
* **拡張機能名**: [例: AI Chat Bookmark Engine]
* **主な機能**: [例: 各AIチャットの重要な発言をワンクリックで保存し、カテゴリ別に整理する]
* **主な構成要素**: [例: SidePanel, Background Service Worker, GAS（バックエンド）]
* **使用技術**: HTML, CSS, JavaScript (ES Modules), JSDoc, Manifest V3

### 【アーキテクチャ・設計ルール】
1. **単一責任の原則に基づくモジュール分割**:
   * 機能・役割ごとにファイルを細かく分割してください。
   * UI描画・DOM操作は `/components/` ディレクトリ以下に独立したモジュールとして作成してください（例: `elements.js`, `drawer.js` など）。
   * 通信処理（`api.js`）や判定・計算ロジック（`utils.js`）は独立したモジュールにしてください。
2. **JSDocによる型定義の明示化**:
   * プロジェクト内で扱う主要データ構造を定義する `types.js` を最初に定義し、各ファイルでJSDocによる型アノテーションを記述してください。
3. **多言語化（i18n）の前提設計**:
   * 初期段階から `chrome.i18n` を用いた多言語化（`_locales/en`, `_locales/ja`）を前提としてください。
   * **[重要]** データベースに保存・通信する内部データ（ステータス、カテゴリ等）は、言語に依存する文字列（例："進行中"）ではなく、**言語非依存のキー（例: `statusInProgress`）** で管理し、UI描画時に `chrome.i18n.getMessage()` で翻訳する設計を徹底してください。
4. **管理用マップの作成**:
   * 全体構造やデータフローを把握するための `PROJECT_MAP.md` の定義を必ず含めてください。

### 【ステップ1：出力内容】
まずは以下の3点を出力してください。実際のコード実装（HTML/JSの全記述）は次のステップで行うため、ここでは全体設計に集中してください。

1. **想定ディレクトリ構成**（ファイル一覧とその役割。多言語リソース `_locales` も含めること）
2. **`types.js` のJSDoc型定義**（内部データがキーベースで設計されていることを明記）
3. **`PROJECT_MAP.md` の草案**（全体概要、構成要素、データフロー、データ構造）

内容を確認・調整した上で、次のステップで具体的なソースコードの作成を依頼します。

技術的効果とメカニズム

  • コード途切れ（トークン上限）の回避：
    「設計出力（ステップ1）」と「ソース実装（ステップ2）」を意図的に切り離すことで、文字数制限（LLMの出力トークン上限）によるコード出力の途切れを防ぐ[cite: 5]。
  • データスキーマの固定によるバグ抑制：
    ステップ1で `types.js` による型定義をAI自身に出力させることで、ステップ2での実装コード生成時にキー名の誤りや未定義参照が発生する確率を大幅に低減する[cite: 5]。
  • メンテナンス性の確保：
    コンポーネントごとのファイル分割をルール化することで、一部のUI変更や処理修正を行った際に、他のモジュールへ影響が波及する「破壊的変更」を論理的に排除する[cite: 5]。