「しくみ解説」を
書かせるプロンプト

# 依頼：Webアプリの「しくみ解説」資料を作ってください

## 対象
- アプリ名：{{アプリ名}}
- URL：{{公開URL}}
- ソースコードの場所：{{ローカルのパス。無ければ「調べて特定して」}}

## 読者と目的
- 読者は**非エンジニア**。プログラムは書かないが、頭は良い。大学1年生程度の予備知識を想定。
- 目的は2つ。(1)「中で何が、どの順番で、どう動いているか」を**自分の言葉で説明できる**ようになること。
  (2) その説明が、**実際の技術用語のどれに対応するのか**が分かること（＝技術の入り口として教育的であること）。
- したがって「やさしいだけ」も「専門的なだけ」も不合格。**必ず両方をセットで**書くこと。

## 最重要のルール（これを外したら作り直し）

1. **推測でものを書かない。** 資料に載せる事実・数値・挙動は、すべて実際のソースコードを読んで確認したものだけにする。
   コードを読まずに「たぶんこうなっている」と書くのは禁止。確認できなかったことは、書かないか「未確認」と明記する。
2. **数値は実物から取る。** 上限、待ち時間、キャッシュの秒数、点数の重みなどは、コードに書かれている値をそのまま使う。丸めない。
3. **AIの有無を正確に。** そのアプリがLLM/AIを呼んでいるか、コードを検索して確かめる。
   呼んでいないなら「呼んでいない」とはっきり書く。雰囲気で「AIが賢く判断します」と書かない。
4. **やさしい言葉と技術用語を1対1で並べる。** 専門用語・カタカナ語・略語は、初出時に必ず平たい言い換えを添える。
   ただし**言い換えて終わりにせず、正式な技術用語も必ず併記**する（読者が後で検索できるように）。
5. **正確さが命の部分は言い換えない。** ファイルのパス、関数名、コマンド、エラーメッセージ、プロパティ名は原文のまま。
   その隣に「これは何をするものか」を平易な1行で添える。

## 進め方

### 手順1　コードを読む
- ソース一式を実際に開いて読む（設定ファイル、API、画面、ライブラリ、テスト、デプロイ設定まで）。
- 特に確認すること：外部サービスへの接続先／認証のやり方／データの正本はどこか／キャッシュ／
  入力検証／エラー処理／同時実行の制御／自動テストの中身／AIの利用有無。

### 手順2　構成案を先に提示して、GOをもらう
- 章立てと「担当者」の分解案（何人・誰）を短く提示し、**承認を得てから**資料化に入る。
- 勝手に作り始めない。

### 手順3　資料を作る（構成は下記のとおり）

## 資料の構成（A4縦・1シート＝1ページ固定）

| ページ | 内容 |
|---|---|
| 1 | 表紙＋「この資料の読み方」 |
| 2 | これは何をするアプリか（できあがるもの／使う人の流れ） |
| 3 | 全体像を1枚の図で（SVGで手描き。AIを使う担当と使わない担当を色分け） |
| 4 | 用語ミニ辞典（15〜18語。**この先の説明はこの語彙だけで書く**） |
| 5〜 | **出演者カタログ：1担当につき必ず1ページ**（下記フォーマット厳守） |
| 以降 | 1回の流れを時間軸で追う／AIを使う所と使わない所／間違いを防ぐ工夫／データはどこに／
　　　　どこで動き外からどう使えるか／品質を保つ仕組み／弱いところと次の一手／
　　　　付録：呼び名と実ファイルの対応表／最後に―3つだけ持ち帰るなら |

- アプリを**{{N}}人（目安12〜16人）の担当者が並んだ工場のライン**と見立てて分解する。
- 「担当者」は説明のための呼び名。**実際の関数名・ファイル名との対応を付録の表で必ず示す**。

## 出演者カタログ 1枚の型（これが資料の心臓部）

各ページを、次の6ブロックで構成する。

(1) 見出し：丸数字＋担当者名／右にバッジ（AIを使う・使わない／読む・書く）／下に「関数名 ／ ファイルパス」

(2) 要約：この担当が何者かを2〜3文。灰色の帯で目立たせる。

(3) この担当の位置と、流れるもの：等幅の文字で描いた**流れの図を1本**。
　　「誰から」「何が」「どこへ」が一目で分かること。分岐（成功時／失敗時）も書く。

    あなたのブラウザ ──[依頼：住所＋本文]──▶ 貸倉庫の入口 《ここで身分の札を貼る》
            └──[依頼＋札]──▶ ① 玄関番 ──[通過]──▶ 次の担当 ──▶ 外部サービス
                                  └──[401＋日本語の断り]──▶ 画面に赤字

(4) 仕様の4行表：「受け取るもの」「出すもの」「AI」「失敗した時どこで止まるか」

(5) 手順の3列表：**この資料の要**。列は必ずこの3つ。

    | いつ動くか | 誰が・何を・なぜ（やさしく言うと） | 技術のことば（入り口） |
    | きっかけを「時点」で書く | 5W1Hを埋める。特に**なぜ**を1文入れる | 左と同じことを指す正式な用語＋1〜2行 |

    - 行数は5〜6行。左右は必ず同じ事柄を指すこと（別の話を書かない）。
    - 技術用語は、その担当のコードに**実際に現れている概念**だけを選ぶ。無理に難語を足さない。

(6) たとえるなら：日常のたとえ話を1〜2文。点線枠。比喩は必ず**構造が一致するもの**にする。

## 文体

- 短く、平らな文。一文に詰め込まない。
- 中身は薄めない。難しい考えでも、言葉だけをやさしくする。**子ども扱い・上から目線はしない。**
- 「なぜそうなるか」の理屈を必ず残す。
- 数字と固有名詞は正確に。
- 各章の終わりに「ここから読み取れること」を1つ置き、事実から解釈への橋を架ける。

## 作り方（技術面）

1. **単一のHTMLファイル**として書く。@page { size: A4; margin: 0 } ＋
   .sheet { width:210mm; height:296.8mm; padding:16mm 17mm 14mm; overflow:hidden; page-break-after:always }
   で**1シート＝1ページを固定**する。フォントは "Yu Gothic UI","Yu Gothic","Meiryo"、本文10.2pt／行間1.75。
   図はすべて**インラインSVG**で手描き（外部画像・外部CDNは使わない）。

2. **ページあたりの詰まり具合を必ず実測する。** overflow:hidden なので、はみ出すと**黙って切れる**。
   ブラウザで開き、次のJavaScriptで全シートの余白を測り、**負のページが無くなるまで文章を削る**。

       Array.from(document.querySelectorAll('.sheet')).map((s,i)=>{
         let b=0; const r=s.getBoundingClientRect();
         s.childNodes.forEach(n=>{ if(n.nodeType===1 && !n.classList.contains('foot'))
           b=Math.max(b, n.getBoundingClientRect().bottom - r.top); });
         return {page:i+1, slack: Math.round((r.height-55)-b)};   // 55px はフッター領域
       }).filter(x=>x.slack<10)

   SVG内の文字が枠外に出ていないかも getBBox() で確認する。等幅の流れ図は
   scrollWidth と clientWidth を比べて横はみ出しを確認する。

3. **Web公開版を作る。** 画面用のCSSを足して、.sheet の高さ固定と overflow:hidden を解除し、
   1枚ずつのカードとして縦に流す。上部に戻るリンクの帯を置く。@media print では元のA4固定に戻す。

4. **PDFが必要な場合**は Chrome のヘッドレス印刷で出す。

       chrome --headless --disable-gpu --no-pdf-header-footer \
         --run-all-compositor-stages-before-draw --virtual-time-budget=8000 \
         --print-to-pdf="<出力先>.pdf" "file:///<HTMLの絶対パス>"

5. 生成後、**ページ数を確認**し、HTML（とPDF）を残す。

## 納品

- 保存先：{{保存先フォルダ}} と、アプリのリポジトリ内 docs/。
- Web公開する場合は、ガイダンス一覧ページからリンクを張り、一覧の説明文も更新する。
- 最後に、チャット上で次の3点を報告すること。
  (a) ページ構成の一覧
  (b) **読みどころ3点**（面白かった設計上の判断を、ページ番号付きで）
  (c) 調べても分からなかった点・確認が必要な点があれば正直に

## やってはいけないこと

- コードを読まずに一般論で埋める
- 「担当者」の粒度を勝手に変えて1人1ページを崩す
- 技術用語を出しっぱなしにする／逆に、やさしい言葉だけで済ませる
- 弱点や割り切りを書かずに、良いところだけ並べる
- 図を画像生成に頼る（構造がずれるのでSVGで手描きする）