1章

これは何をするアプリか

「テーマ」と「いつからいつまで」を入れると、アプリがウェブを調べ、その期間のニュースから演習問題を8問つくって画面に出す――それだけのアプリです。目的は暗記のテストではありません。ニュースを仕事の判断につながる形で覚え直すことです。

できあがるもの（1回ぶんの中身は毎回この形に固定）

使う人の流れ

1. テーマを書く（最大400字）。例：「日本企業から見たウクライナ情勢とエネルギー安全保障」。
2. 開始日と終了日を選ぶ。最初から「30日前〜今日」が入っている。難易度は日経TEST水準で固定。
3. 使うAIを選ぶ。Sonnet 5（既定）か Opus 5。
4. ボタンを押すと、9つの工程が1つずつ進む。今どこにいるか、各工程が何秒かかったかが画面に出る。
5. 途中で失敗したら、その工程だけやり直せる。前の工程の成果は消えない。
6. 完成すると、下に問題集が現れる。空欄を押すと答えが出る。設問の (a) を押すと本文の該当箇所へ飛ぶ。
7. 過去の生成は履歴に残り、開き直せる。作業中のものは、画面を開き直すと自動で続きから進む。

2章

全体像を1枚の図で

紺色の枠＝AIを呼ばない担当／橙色の枠＝AIを呼ぶ担当。点線の枠は「どこで動いているか」の区切り。

3章

用語ミニ辞典（この先で使う言葉）

この先の説明は、なるべくこの17語だけで書いています。分からなくなったらこのページに戻ってください。

テーマ・期間・使うAIを受け取り、明らかにおかしい入力だけをその場で止めて、サーバーに「作ってください」と1回だけ頼む担当。ボタンを押した後の進行は、すぐ②に引き継ぎます。

あなた ──[テーマ・開始日・終了日・モデル]──▶ ① 受付カウンター（画面の中）
   《3文字未満 ／ 開始日が終了日より後 → ここで赤字。サーバーへは送らない》
     └──[POST /api/jobs に JSON で1回]──▶ ③ 入力の門番
              └──[202番＋依頼票]──▶ ② 進行役へバトンタッチ

このアプリで一番変わっている担当。9つの工程を1つずつ進めるのは、サーバーではなくあなたのブラウザです。依頼票を握って「次へ進めて」を9回叩き、待ちの間は2.5秒ごとに様子を見に行きます。

② 進行役 ──[POST /api/jobs/{id}/advance]──▶ ⑤ 現場監督 ──▶ 1工程だけ実行
    ▲                                                    │
    └────────────[更新後の状態]──────────────┘
  《返事が「走行中」のまま → 2,500ミリ秒待って GET で見に行く》
  《完成 or 要再試行 になるまで繰り返す。要再試行なら赤帯＋再試行ボタン》

サーバー側で最初に動く担当。①と同じ検査をもう一度やり、通ったら依頼票を1枚作って番号を振ります。ここから先、9工程の成果はすべてこの1行にぶら下がります。

① 受付カウンター ──[JSON]──▶ ③ 門番
   《テーマ3〜400字 ／ 日付の形 ／ 開始日≦終了日 ／ モデル名は一覧の2つだけ》
     ├─[違反]──▶ 400番＋日本語の理由 ──▶ 画面に赤字
     └─[合格]──▶ 依頼票を1枚（番号・待ち・工程は「調査計画」・0工程目）
                        └──[202番＋依頼票]──▶ ② 進行役へ

データの置き場所への出入口を1か所にまとめ、表がまだ無ければその場で作る担当。9工程ぶんの途中経過を預かる棚を、誰も気づかないうちに用意しています。

どの担当も ──[getDb()]──▶ ④ 管理人 ──▶ Cloudflare D1（表3つ＋索引6つ）
   《小部屋が立ち上がって最初の1回だけ ensureSchema を実行》
   《model 列が無い古い倉庫 → PRAGMA で列を数え、その場で1列だけ足す》
     └─[道具箱に棚が入っていない]──▶「保存用データベースに接続できませんでした。」

「次へ進めて」という電話を受け、その1回で必ず1工程だけ動かす担当。始める前に鍵を取り、終わったら結果を台帳に書き、作業札を次の工程に貼り替えます。

② 進行役 ──[POST /api/jobs/{id}/advance]──▶ ⑤ 現場監督
   ├─依頼票が無い → 404 ／ 完成済み → そのまま返す ／ 要再試行 → 409
   ├─[⑥に鍵を頼む]──取れない──▶ 409「別の処理が進行中です。」
   └─取れた──▶ ⑦ 割り振り係 ──▶ 1工程を実行（ここで秒数を計る）
         ├─成功──▶ ⑮ 台帳へ記録・次の工程へ ──[更新後の状態]──▶ ②
         └─失敗──▶ ⑮ 失敗も記録 ──▶ 422＋日本語の理由

同じ工程が同時に2回走らないようにする担当。鍵の渡し方が独特で、「台帳の1行を条件付きで書き換えて、本当に1行変わった人だけが通れる」という方式をとっています。

⑤ 現場監督 ──[鍵をください]──▶ ⑥ 鍵預かり係
  UPDATE … SET status='running'
   WHERE id=? AND current_step=? AND status IN ('queued','waiting')
    ├─変わった行が 1 → 鍵を渡す（何回目の挑戦かも数えて渡す）
    └─変わった行が 0 → 誰かが先に取った。鍵は渡さない ──▶ 409
  《別口：走行中のまま4分（240,000ミリ秒）動かない行 → 要再試行に落として救出》

依頼票に書かれた「今の工程名」を見て、誰を呼ぶかを決めるだけの担当。このファイル1枚を読めば、アプリが何を、何の順でやるかが全部分かります。

⑤ ──[依頼票（今の工程名つき）]──▶ ⑦ 割り振り係
  1 research_plan → ⑧ 調査計画      6 questions_1 → ⑪ 問1〜4
  2 research_1    → ⑨ 情報収集 1/3   7 questions_2 → ⑪ 問5〜8
  3 research_2    → ⑨ 情報収集 2/3   8 questions_3 → 数を数えるだけ（AIなし）
  4 research_3    → ⑨ 情報収集 3/3   9 finalize    → ⑭ 最終検品（AIなし）
  5 blueprint     → ⑩ 設計図
     └──[新しい途中経過と成果物]──▶ ⑤ へ返す（保存するのは⑮）

AIを使う最初の担当。いきなり調べ始めず、テーマを重ならない3つの調査単位に割るための計画だけを作らせます。設問は作らせません。

⑦ ──[テーマ・期間]──▶ ⑧ 調査計画係 ──▶ Claude（Sonnet 5 か Opus 5）
  《返してほしい形を先に渡す：thesis（見立て）＋ batches（label・query・focus）》
  《上限 2,000トークン ／ 考える深さ low ／ ウェブ検索は渡さない》
    ├─調査単位ちょうど3件、各focus 2件以上 → 合格 ──▶ ⑮ 台帳へ
    └─件数が違う → ⑬ 直し係が理由を添えて1回だけ作り直させる

実際にウェブを検索する唯一の担当。3つの調査単位を、それぞれ別の工程として3回動きます。3回そろったら、出典をURLで名寄せして1本に束ねます。

⑦ ──[調査単位1つ]──▶ ⑨ 情報収集係 ──▶ Claude ──[検索 最大3回]──▶ ウェブ
  《初回は検索を強制。まだ続きがある（pause_turn）なら会話を継いで最大2周》
    └─[900〜1,500字の証拠＋出典（最大8件・2件未満は失敗）]──▶ ⑮ 台帳へ
  3回そろった後 ── URLで重複を落とし S01… と採番（最大20件・5件未満は失敗）

設問を書く前に、本文・押さえる構造・用語集・年表という「土台」だけを作らせる担当。ここで本文に空欄と下線の目印を埋め込み、その並び順まで機械が検査します。

⑦ ──[調査結果＋出典]──▶ ⑩ 設計図係 ──▶ Claude（正本27,787字を同封）
  《固定：構造4件・本文1つ（700〜900字）・用語8件・年表6件。上限9,000トークン》
  《本文の目印 [[BLANK:A|正答]] [[UNDERLINE:a|文]] … 登場順は必ず A→a→B→b》
    ├─件数と並び順が一致 → 合格 ──▶ ⑮ 台帳へ
    └─ずれ → ⑬ 直し係が1回だけ作り直させる

8問を4問ずつ2回に分けて作らせる担当。どの番号がどの形式かは人があらかじめ決めてあり、AIが書くのは中身だけ。正解は必ず1番目に置かせます。

⑦ ──[設計図＋調査結果]──▶ ⑪ 設問の作成係（1回目=問1〜4／2回目=問5〜8）
  Q01 空欄補充      Q02 下線（深掘り）   Q03 共通キーワード  Q04 資料読解［新形式］
  Q05 職業への接続［新形式］ Q06 空欄補充  Q07 下線（深掘り）  Q08 論述80字
  《正答は必ず options[0]・correctIndex=0。並べ替えは⑫の仕事》
  《誤答ごとの説明は作らせない（空配列で固定）。解説は140〜220字》
    └─[4問ぶんのJSON]──▶ ⑫の検査 ──▶ ⑮ 台帳へ

このアプリでいちばん意外な担当。正解が①ばかりに偏らないよう並べ替え、正答が下線部の言い換えで済んでいないかを見抜きます。どちらもAIではなく、足し算と文字の重なりだけでやっています。

⑪ の出力（正答は必ず1番目） ──▶ ⑫ 公平さの検査係
  《テーマの全文字のコード合計 ÷ 4 の余り = ずらし幅 → 正解位置の並びが決まる》
     例）余りが2 → ③④①②③④①… の順に、4択7問へ順番に配る
  ├─並べ替え：1番目の正答を、決められた位置へ差し込む ──▶ ⑭ へ
  └─言い換え判定：下線文と正答を3文字ずつに刻み、72%以上重なれば差し戻す
  （同じ道具を逆向きにも使う：正答と解説が重ならなければ、解説が別の話 → 差し戻す）

44行しかない小さな担当ですが、このアプリの粘り強さのほぼ全部がここにあります。形式違反は「理由を添えてもう1回だけ作り直させる」、通信の一時不良は「700ミリ秒待って1回だけ送り直す」。どちらも1回だけです。

【形式が違う時】検査に落ちる ──▶ ⑬ ──[前回のJSON＋落ちた理由]──▶ Claude
     ├─2回目が合格 → 何事もなかったように先へ（画面には出さない）
     └─2回目も不合格 → 「自動修正後も形式検証を通過できませんでした: …」
【通信が不調な時】408 / 425 / 429 / 500 / 502 / 503 / 504 / 529 か接続失敗
     └──▶ 700ミリ秒待つ ──▶ もう1回だけ送る（それでも駄目なら工程を失敗に）

9工程目。バラバラに作ってきた部品を1つの問題集に組み立て、十数項目の検査を通す担当。ここを通らなければ、保存も表示もされません。

⑦ ──[調査・設計図・設問2バッチ]──▶ ⑭ 組立 ──▶ 問題集1式（ProblemSet）
  検査：構造3〜5件／本文1つ／設問8問（4択7＋論述1）／選択肢はどれも4つ／
        正解位置が⑫の並びと完全一致／職業への接続1問以上／新形式1問以上／
        論述はキーワード2語・観点3件／出典IDが実在／用語8〜12件／年表4〜10件／
        本文の空欄2・下線2／空欄下線を問う設問は本文を必ず1つ参照
    ├─全部通る ──▶ ⑮ 台帳へ保存（札を「完成」に）
    └─1つでも駄目 ──▶「最終検証に失敗しました: …」（先頭5件だけ見せる）

工程が終わるたびに、成果・所要時間・失敗理由をまとめて1回で書き込む担当。この担当がいるから、途中で止まっても続きから再開できます。

⑤ ──[成果・所要時間]──▶ ⑮ 台帳係 ──[3つの書き込みを1回のまとまりで]──▶ D1
  ① job_steps に1行（工程名・何回目・秒数・成果のJSON）
  ② generation_jobs を更新（次の工程名・進んだ数・途中経過）
      ※ WHERE に「走行中で、工程がこのまま」を付ける＝横取りされていたら書かない
  ③ 完成時のみ problem_sets に完成品（同じ依頼なら上書き）
  失敗時 ── 失敗も1行残して札を「要再試行」に ／ 同じ工程の失敗3回で打ち止め

完成した問題集のJSONを、決まった形の画面に流し込むだけの担当。AIはHTMLを1文字も書きません。本文の目印を、押せる空欄や下線に変えるのもここです。

⑮ 台帳の完成品（JSON） ──▶ ⑯ 表示係
  [[BLANK:A|正答]]  → 押すと答えが出るボタン（もう一度押すと隠れる）
  [[UNDERLINE:a|文]] → (a) の付いた下線
  [[REF:a]]         → 設問の中の (a) ボタン ──押す──▶ 本文の該当箇所へ移動
  「解答・解説を見る」──▶ 正解に○、選んだ誤答に印、解説を開く
  年表・用語集・出典は折りたたみ ／ 解答の状態はメモリだけ（保存しない）

5章

1回の流れを、時間軸で追う

ボタンを押してから問題集が出るまで、実際に何が起きているか。「次へ進めて」の電話が9回かかる、というのがこの表の骨格です。

その1回の中で、毎回必ず起きていること

1. ②が advance を叩く → ⑥が条件付きの1行書き換えで鍵を取る（取れなければ409で引き返す）。
2. ⑦が工程名を見て担当を選ぶ。AIを呼ぶ工程なら、返す形をJSONスキーマで固定して頼む。
3. 返ってきたものを機械が検査する。落ちたら⑬が1回だけ作り直させる。通信の不調なら700ミリ秒待って1回だけ送り直す。
4. ⑮が「工程の記録1行＋依頼票の更新（＋完成時は問題集）」をまとめて1回で書く。
5. ②に更新後の状態が返る。札が「走行中」のままなら2.5秒待って見に行く。「完成」か「要再試行」になるまで繰り返す。

6章

AIを使っている所と、使っていない所

「AIアプリ」と一口に言っても、どこまでAIに任せているかは大きく違います。このアプリの線引きは、はっきりしています。

AIを呼ぶのは、16人中5人。1回の生成で7回だけ

ウェブ検索が走るのは最大9回（3工程 × 各3回まで）。使うモデルは claude-sonnet-5（既定）か claude-opus-5 で、利用者が生成のたびに選びます。両方とも同じ工程を通ります——モデルを変えても、工程の数も検査の厳しさも一切変わりません。

AIを使っていない所（＝「賢く判断している」わけではない所）

7章

間違いを防ぐ、7つの工夫

どれも派手ではありませんが、この7つが無いと「たまに壊れるアプリ」になります。

1　同じ検査を、画面とサーバーの両方でやる（①③）

画面の検査は速さのため、サーバーの検査は守りのため。窓口は直接叩けるので、画面を通らない依頼が来ても壊れないようにしてあります。片方だけでは足りません。

2　鍵は「確かめてから取る」のではなく「条件付きで書いて、結果を見る」（⑥）

「空いているか確かめる → 取る」の間には、必ず隙間があります。その隙間で他の人に取られる。だから確認と取得を1文にまとめ、「1行だけ変わった」ことをもって勝者とします。データベースが1行ずつの書き換えを保証してくれることを利用した、古典的で確実な方法です。

3　書き込みは「まとめて1回」（⑮）

工程の記録・依頼票の更新・完成品の保存を別々に3回送ると、2回目で失敗した時に「工程は進んだのに成果が無い」という矛盾が残ります。1つのまとまりにすれば、全部書かれるか、1つも書かれないかのどちらかになります。

4　直しは1回、再送も1回（⑬）

粘れば直るものは粘り、直らないものは早く諦める。上限を決めておかないと、費用と時間が青天井になります。混雑（429）や一時障害（5xx）だけ送り直し、入力ミス（400番台）は送り直さない、という切り分けもここに入っています。

5　「返ってくる形」を先に決めてから頼む（⑧⑩⑪）

AIに自由に書かせて後から読み取るのではなく、JSONの設計図を渡して、その形でしか返せなくする。書式の崩れを、そもそも起こさない作りです。それでも件数や順番までは保証されないので、6と7で確かめます。

6　同じ検査コードを、作る時と最後の両方で使う（⑩⑭⑯）

本文の目印を読み解く関数は1つしかなく、設計図の検査・最終検品・画面表示の3か所すべてが同じ関数を呼んでいます。だから「検査は通ったのに表示で崩れる」が起きません。

7　止まった仕事を、読むついでに片付ける（⑥）

走行中のまま4分動かない依頼票を、台帳を読むたびに「要再試行」へ落とします。見張り役を常駐させると、それ自体が壊れます。ふだんの動作のついでに掃除するのは、常時動くものを増やさないための工夫です。

8章

データは、どこに、どんな形で置かれているか

置き場所は1つだけ ― Cloudflare D1（表3つ）

索引は6本。job_steps には「依頼・工程・試行回数」の組で重複を許さない索引があり、同じ試行が二重に記録されないようになっています。

正本（本物）はどれか

• 途中経過の正本は generation_jobs.state_json。調査計画・3回ぶんの調査・設計図・設問2バッチが、この1つの箱に順に足されていきます。②が持っている画面の表示は、その写しにすぎません。
• 完成品は2か所にあります。generation_jobs.result_json（画面が読む方）と problem_sets.body_json（保管用）。同じ内容が入ります。画面が読むのは前者です。
• 工程の記録は、消えない履歴です。成功も失敗も1行ずつ残り、何回目の挑戦だったかまで分かります。画面の「再試行 1」「12.4秒」はここから出ています。

外に出ていくもの・外から入ってくるもの

APIキーはコードに1文字も書かれていません。動く場所から渡される設定（env.ANTHROPIC_API_KEY）を読み、無ければ手元の環境変数を見る、という順に探します。手元で動かす時は、1つ上の階層の共通 .env を読み込みます。

9章

どこで動き、外からはどう使えるのか

動いている場所

外から叩ける窓口（全6つ）

10章

品質を保つ仕組み ― あるものと、無いもの

あるもの

無いもの ― 自動テストは、事実上1本だけ

tests/ というフォルダは空です。動くテストは scripts/test-auto-repair.mjs の1本だけで、npm run test:repair で実行します。中身は次の3つを確かめるものです。

• 検査に落ちた時、直しが1回だけ走り、2回目が通れば成功として返ること
• 2回目も落ちたら、「自動修正後も…」というエラーになること
• 一時的な失敗の後、再送が1回だけ走って成功すること

package.json に test というコマンドはありません（test:repair のみ）。つまり⑬以外の担当には、自動テストが1つも無い状態です。⑫の正解位置の計算や言い換え判定、⑩の目印の並び順検査、⑮のまとめ書き込みは、いずれも入出力がはっきりしていてテストしやすいのに、まだ書かれていません。

11章

弱いところと、これから選べる道

欠陥という意味ではなく、「今はこう割り切ってある」という設計上の選択と、その代償を並べます。

作りの上での割り切り

• 工程を進めるのはブラウザ。タブを閉じると進行は止まります（②）。保存してあるので開き直せば続きから進みますが、「見ていないと終わらない」性質は残ります。
• 利用者の区別がありません。アプリ内に認証の処理が無く（9章）、履歴も全員共通です。
• 使われていない窓口が2つ残っています。/api/research と /api/generate。旧方式（13問・Opus固定）のまま生きています。
• 自動テストが実質1本だけ。tests/ は空（10章）。
• 日付は「形」しか見ていません。2026-99-99 のような実在しない日付は、③を通り抜けます。
• 4分という固定値。本当に4分を超える工程があると、動いているのに「要再試行」に落とされます（⑥）。
• 再送は700ミリ秒待って1回きり。混雑が続く時は、段階的に間を延ばす方式のほうが通ります（⑬）。
• 同じテーマなら、正解の並びも毎回同じ。再現できることを優先した結果です（⑫）。
• 正本プロンプトと実装がずれています。設問数（正本12〜15問／実装8問）、折り返し幅（860px／960px）、誤答ごとの解説（正本は必須／実装は作らせない）。ずれは意図的で、指示文に「実装側を優先」と書いてありますが、正本だけ読んだ人は戸惑います。
• 同じものの定義が2か所にあります。表の設計（db/index.ts と drizzle/）と、13問の旧仕様を通す分岐（⑭）。

もし次に手を入れるなら（優先度順の一案）

付録

この資料の言葉と、実際のファイルの対応

実物を開いて確かめたい時のための対応表です。すべて C:\Users\aky_m\Scripts\current-affairs-mvp\ の下にあります。

決め打ちされている数値の一覧（すべてコードから取った実値）

最後に

3つだけ持ち帰るなら

※ この資料は、2026年8月11日時点の current-affairs-mvp のプログラムを実際に読んで作成しました。
※ 「担当者」という言い方はこの資料の説明のための呼び名で、プログラム内にその名前が付いているわけではありません。対応は付録の表のとおりです。
※ 数値（上限、待ち時間、字数、しきい値）はすべて実際のコードから取った値です。プログラムを直せば、これらの数値も変わります。
※ サインインの壁の挙動だけは、コードではなく公開URLの応答から確認したものです。