開発eurekapu-nuxt4

朝、計画書からCodexに殴られに行った

決算書の教科書ページを新規に立ち上げる日だった。

いきなり手を動かすのではなく、まず memo/2026-05-13/textbook-pages-plan.md に計画書を書き起こした。章構成、ルート設計、クイズデータとの紐付け、フェーズ分け（X-0/X-1/X-2）まで一通り並べてから、Codexに投げた。

「このプランをレビューして。瑣末な点へのクソリプはしないで。致命的な点だけ指摘して」

返ってきた指摘でレジストリの粒度を直し、再レビュー。今度は型定義の整合性を突かれた。3往復目でようやくCodexが致命傷を指摘しなくなった。手を動かす前にレビューを3周回したおかげで、後の実装中に「設計から考え直し」の戻りが発生しなかった。

Phase X-0: 984問のクイズデータをPythonで切り出す

基盤を固めるフェーズから始めた。

既存のクイズデータが984問あって、これを章別・節別に並べ替えてレジストリ化する必要があった。Pythonスクリプトを書いてもらい、quizRegistry.ts と textbookChapters.ts を生成。型定義を先に切ってからデータを流し込む順序にしたので、後段の章ページが型エラーで止まることがなかった。

Phase X-1: CH1パイロットを書いてユーザーに見せた

いきなり7章全部を書かせず、CH1だけパイロット実装してレビューに出した。

ここで「この導線でいいか」「クイズの埋め込み方はこの粒度でいいか」を確認してもらってから次に進む。先にパイロットを通すと、後でまとめて書き直す手戻りが消える。

Phase X-2: 並列サブエージェントで6章を一気に書く

CH2〜CH7を、サブエージェント4本＋2本の並列構成で走らせた。

サブエージェントには章別の素材と型定義だけ渡して、あとは独立に書かせる。並列で動かすと、メインのターンが手詰まりにならず、こちらは別の作業（SVG統合の検討など）と同時に進められた。

「書籍のテキストをDBから引いてきて」で立ち止まる

途中でユーザーから指示が入った。

「TursoDBに入れた書籍の編集済みテキストを、教科書ページに参照させてほしい」

ここで一度手を止めた。決算書解説の参考書をOCR→編集してDBに格納してあるが、それを教科書ページ本文に取り込むと、翻案にあたるリスクがある。引用の範囲を超えるし、翻案権の侵害を構成しうる。

「やります」ではなく「ちょっと相談させてください」と返した。落としどころとして、章節の見出しレベルの『論点骨組み』だけを抽出して、構成のガイドに使う方針に切り替えた。本文は自分の言葉で書き直し、書籍のテキストそのものは画面に出さない。著作権の地雷を踏まず、書籍の論点構造の有用性だけを使う形に着地した。

SVG図をhighlight指定で組み込む

クイズで使っていたSVG図を、教科書ページに再利用する実装。

ただ貼るだけでなく、教科書本文の流れに合わせて図の特定要素を強調表示できるよう、highlight プロパティを足した。本文で「ここがB/Sの右側」と書いたタイミングで、SVG内の右側ブロックだけがマゼンタになる。文字での説明と図の指差しが一致するので、読者の視線が散らからない。

別セッションで決算書解説の参考書統合プロジェクトのPhase 0/1

並行して別セッションでは、決算書解説の参考書の構成を下敷きにした業種別解説プロジェクトを進めていた。

Phase 0で企業選定、Phase 1でEDINETからの財務データ取得まで。途中、EDINETDB_API_KEYが invalid で弾かれてストップ。ユーザーから新キーを受け取ったが、.env への書き込みは harness の禁止ルールで弾かれた。

ここで横着せず、Pythonの os.environ 経由でセッション内だけにキーを持たせて取得処理を回した。.env を書き換えない代わりに、セッションが切れたら鍵も消える状態にしてある。鍵が .env に残らないので、git に紛れ込む事故も起きない。

Phase 2: 業種別16 SVG図のパイロット → 並列で17個追加

パイロットで業種別のSVG図を16個書き、レイアウトと配色の方針が固まった段階で、残り17個を4並列のサブエージェントに分担させた。

並列で走らせると、当然のように品質のばらつきが出る。特にフォントサイズの統一が崩れた。SVGガイドラインでは見出しと本文と注釈で決められたサイズがあるのに、サブエージェントが書いたSVGには font-size="15px" や font-size="14px" が混じっていた。

ここで力技に走らず、grep で違反箇所をスキャン。

font-size="15px"  # ガイド違反
font-size="14px"  # ガイド違反

該当ファイルを並べて、Editツールで一括置換。1ファイルずつ目視で直す手順だったら半日溶けていた。検出と置換を別工程にしたおかげで、20分で全SVGがガイドに準拠した。

ChapterNavの目次を h3 まで対応

目次の階層を h2 までで止めていたが、章が長くなると h3 がないと現在地が掴めない。

色やアイコンで階層を表すと情報量が増えすぎるので、フォントサイズとインデントだけで階層を表現する方針にした。h2 と h3 で字下げ量を変え、フォントサイズで主従を出す。装飾を増やさず、文字の差だけで階層が伝わる形に落ち着いた。

矢印キー（← →）で章間を移動

最後に、TextbookPageに矢印キーのショートカットを追加した。

教科書を読んでいるとき、マウスでChapterNavのリンクを毎回クリックするのは指が止まる。← で前章、→ で次章に飛べるようにすると、読書のリズムが切れない。入力フィールドにフォーカスがあるときは無効化する条件分岐も入れて、ショートカットが暴発しない形にした。

今日の手応え

  • 計画書 → Codex 3往復 → 着手の順序を踏むと、実装中の戻りが消えた
  • 書籍の文章をDBから直接引く方針は、止まって相談したおかげで翻案リスクを回避できた
  • 並列サブエージェントで量産したSVGの品質ブレは、grepで違反パターンを拾えば後追いで揃えられる
  • .env を書き換えなくても、os.environ でセッション内だけにキーを持たせる回避路がある

明日やること

  • 教科書ページのCH1〜CH7を一通り通読し、章間の文体の揺れを拾う
  • 業種別SVG図33個を1枚のインデックスページにまとめて、業種選択UIを作る
  • highlight機能の動作を、矢印キー移動と組み合わせて検証する
  • 翻案リスクで保留した「書籍テキスト参照」を、引用範囲（短いセクション見出しのみ）で再設計できないか検討