蔵書DBの技術書を自分用に全編リライトする——Miller ColumnコンテンツとQ&A図解化

蔵書DB（Turso）に取り込んだ本を「検索して引く」だけでなく、「自分向けに書き直して読む」段階に進めた日。設計を扱った技術書の全編リライトコンテンツと、Q&A形式の投資実務書のまとめ直しコンテンツを、計画→Codexレビュー→別セッション実装の流れで2本立て続けに作った。

発端: DBの中のコードは画像だった

きっかけは「あの設計の本、取り込んだんでしたっけ？」という確認だった。Turso DBを調べてもらうと102チャンクで登録済み。ならばと、出版社が配布している公式サンプルコードのZIPをダウンロードして展開・整理してもらった。

ここで想定外の事実がわかる。DB内の本文チャンクを開くと、コードリストの部分には「リスト1.1 …」のような説明文と <img> タグだけが残っていた。OCRがコードブロックを図画像（PNG）として切り出していたため、DBに入っているコードは検索もコピーもできない。つまり今回ダウンロードしたサンプルコードが、コードの唯一の「正」のソースになる。リライト計画にはむしろ好都合だった。

ちなみにZIPの展開時、コピー先が src/data/code にずれて配置されるミスもあったが、リポジトリルートの data/code に移動させて整理を完了した。蔵書まわりは「取り込んで終わり」ではなく、こうした素材の置き場所の整備が地味に効いてくる。

リライトコンテンツの計画——既存パターンに乗せる

「中身を一個一個、自分向けに全部リライトしてほしい」というのが目的。表示形式は迷わなかった。mdx-playgroundには既にUIデザイン原則をMiller Columnレイアウト（左: 章、中央: トピック、右: 詳細）で見せるパターンがある。設計本の内容はGood/Bad対比が軸なので、この形にそのまま乗る。

そこで、Chrome DevToolsで既存ページの構造を確認させたうえで、mdx-playground向けの計画書を書いてもらい、Codexレビューにかけた。指摘4点（データモデルの出典表現、Shiki依存、検証手順、リライト方針）を反映して「致命的な指摘なし」まで通す。計画書は memo/2026-06-11/coding-principles-plan.md に保存した。

ここで一つ判断をした。計画セッションと実装セッションを分ける。計画づくりでコンテキストを使い切ったセッションに実装まで背負わせず、計画書をディスクに固定してから、mdx-playground側の新しいセッションで「計画書を読んで実行して」と一行だけ渡す。長いパイプラインはフェーズで区切るほうが安定する。

実装: 13章62トピックを並列生成

実装セッションでは、まず骨組み（型定義・レジストリ・ページ2枚・prerenderルート）を作らせ、サンプルとして1章だけ生成して表示を確認した。Miller Columns、✕ Bad / ✓ Good の対比、Shikiのハイライト、note補足、参考文献表記。骨組みの段階で計画どおり描画されているのをスクリーンショットで見てから、残り12章の生成エージェントを並列で走らせた。

ここからは完了通知を待つ時間になる。「ch6完了（6トピック・7対比セット、題材は経費精算・消費税区分・源泉徴収・与信ランクなど会計ドメイン、型チェックpass）」「ch2・ch11完了（累計3/13章）」「ch3完了（4/13章）」……数分おきに通知が届き、進捗カウンタが13に向かって増えていく。コード例は書籍の転載ではなく、自分のドメインであるPythonの会計題材に全部置き換えさせている。リライトというより「自分の業務の文脈で原則を語り直させる」作業で、これが書籍コンテンツを手元に置く意味だと思っている。

全13章が揃ったところで検証フェーズ。章レジストリ経由で全章データを読み込む整合性テストを走らせ、構文・型の破綻がないことを確認する。途中、別ファイルで18件のテスト失敗が出てヒヤッとしたが、自分の変更とは無関係の既存失敗だと切り分けられた。ブラウザではハイドレーションエラーなし、左カラムでの章切り替えも問題なし。28ファイル・6001行追加でコミットした。13章62トピックの学習コンテンツが、計画書を渡してから半日かからず立ち上がった。

仕上げに公開範囲の整理。「これってインデックスからどうやってアクセスできますか」と聞くと、計画書の方針どおりトップナビからはリンクしておらず、アクセスはURL直打ちのみだという。それだと自分が使いづらい。トップページがNuxtLinkカードのハードコード構成であることを確認したうえで、「とりあえず非公開のやつ、消費税のやつと同じ扱いで」と指示した。既存の消費税パターン解説と同じ v-if="isDev" のdev限定カードがトップページに追加され、dev環境でだけカードが見え、本番ビルドには出ない状態になった。書籍由来の非公開コンテンツの置き場所として、この扱いが定着してきた。

途中、devサーバーがログ上のエラーなしに3回落ちる事象があった（exit 0xFFFFFFFF）。原因は掴めていないが、issueに記録だけ残して再起動し、先に進んだ。原因究明に時間を溶かすより、再現したときに辿れる記録を残しておくほうが今日は正しい。

2本目: Q&A形式の投資実務書をまとめ直す

同じ日、蔵書のQ&A形式の投資実務書についても「Qに対する答えを1つのコンテンツとしてまとめ直してほしい」と頼んだ。既に作ってあった投資実務の統合解説コンテンツに加える形で、個別Q&Aとして読めるようにする。

ここでもまず計画書。本のQ&Aは80問あるはずだが、Q番号に欠番がないかをDBで確認させてから計画を書かせ、Codexレビューにかけた。指摘は「DBパスの表記が曖昧」の1件で、絶対パスに修正して完了。そして今回もセッションを切り替えた。計画セッションは蔵書DBの調査と計画書執筆でコンテキストが重くなっている。「セッション切り替えたいんで、切り替えたセッション先でのプロンプトを出して」と頼み、計画書のパスと前提を詰め込んだ復帰プロンプトを受け取って、新セッションに貼り付けるだけで実装が始まる体制にした。

実装セッションでは、まずDBから87チャンクを確認し、章別に底本を一時ディレクトリへダンプ。そこからサブエージェント4並列で執筆させ、最終的に全77問が揃った（欠番を除いた実数）。章レジストリ＋77問＋純粋関数を qaData.ts に結合し、SSR HTMLで77問・13章が出力されていることを数えて確認。執筆エージェントが報告してきた底本側のOCR乱れも、計画書に実装記録として残させた。

検証では小さな引っかかりが2つ。デバッグポート9222の応答が空に見えてポートの状態を確認し直す場面と、全テストスイートでog-meta-tagsテストが14件失敗する場面があった。後者は今回の変更が原因か既存の失敗かを切り分けさせ、シロと確認。デバッグ用に立てたtempプロファイルのChromeの残骸もきちんと片付けさせた。残骸の9222リスナーは後日のMCP接続を壊す前科があるので、ここは省略しない。まずは1ページの長い読み物として完成した。

カード分割と矢印キー移動

できあがった1ページを眺めて、注文を出した。「カードコンポーネントを章ごとに分けて、キーボードの矢印キーで左右に移動できるようにして」。長い1ページより、章で区切られていたほうが読む単位がはっきりする。

ページ構成は qa.vue 1枚から qa/index.vue（章カード一覧のハブ）＋ qa/[chapter].vue（章ページ）に組み替えられ、純粋関数も前後章の解決やパス生成に拡張された。←→キーで章を行き来できる。動作確認では、ログイン済みのChromeにデバッグ接続してキー送信まで実際に試させた。テストも章ナビゲーション対応に拡張して24件全パス。あわせて回答文の簡潔化と改行整理、各回答への「現在の見解」の付記も反映された。

コミットは「ステージングコミットして」の一声で、統合解説一式とQ&A機能の2つに機能単位で分けて記録された。44ファイルが1コミットに収まるあたり、1日の出力としてはかなりの量になっている。

文字の壁にSVG図解を入れる

章ページを開いてスクロールしていると、指が止まった。Qの答えと解説が文字の塊で延々と続き、読む気が削がれていく。そこで頼んだ。「Aの解説にSVGの図を追加してほしい。基本的にはすべてのQごとに1個チャートがあったほうが嬉しい」。

svg-diagram スキルのルールを読ませた13のエージェントが、章ごとに分担して全77問に1枚ずつ図を描いた。フロー、対比、ツリー。グレー8段階の濃淡にマゼンタの強調という、スキルで決めてあるトーンに全部揃っている。章ごとに図の枚数が問数と一致するかを機械チェックさせ、表示も目視で確認した。開いてみると、文字の壁の合間に図が挟まり、ページを送る手が軽くなった。思わず「あー、いいですね。とてもわかりやすいですね」と声に出た。

スキル改善: 図解は手段であって目的ではない

図の出来が良かったので、ふと聞いてみた。「これ、ドキュメントコミュニケーションのスキルって使ってるんですか？」。答えは「使っていない。ただし svg-diagram スキルの中に図解メッセージング設計原則として、そのエッセンスが組み込まれている」。

ここで手を打っておくことにした。図解はドキュメント・コミュニケーションの手段であって目的ではない。svg-diagram だけを参照して図を描く場面でも、「図は手段」「1図1メッセージ」「3秒で主旨・20秒で構造が伝わるか」という論点が効いてほしい。選択肢は2つあった。svg-diagram から doc-communication を参照させる方式と、エッセンスだけを svg-diagram に統合してスキルを少し長くする方式。参照方式は読み込み忘れのリスクが残るので、エッセンス統合方式を選んだ。明示的に2つのスキルを指定しなくても、図解が入る作業なら自動的に設計原則が乗る。

実作業としては、doc-communication の図表設計リファレンスを確認させたうえで、図解に効く論点を svg-diagram に書き込み、末尾に配置の規則性と出典・両スキルの役割分担のセクションを追加。doc-communication 側にも相互参照を1行入れて整合させた。

コンテンツを作っていて図の出来に満足した、で終わらせず、その場でスキルに焼き込む。次に図を描かせるときは、何も言わなくても同じ水準が出る。

今日できたもの

どちらのコンテンツも pnpm generate は走らせていない。dev確認とユニットテストまでで止め、リリースはまた別の判断にする。

今日の学び

• 計画と実装でセッションを分けると長いパイプラインが安定する。計画書をディスクに固定し、復帰プロンプトを書かせてから切り替えるのが手数最小だった。今日は2本とも同じ型で回した
• 計画は必ずCodexレビューを通してから実装に渡す。今日の指摘は「レプリカ未同期のままだと素材が欠ける」「DBパス表記が曖昧」など、実装後に踏むと痛い種類のものばかりだった
• DBに取り込んだ書籍のコードブロックはOCRで図画像になっており、テキスト検索もコピーもできない。公式サンプルコードなど別の「正」のソースを確保する
• 書籍リライトのコード例は転載ではなく自分の業務ドメイン（会計）の題材に置き換えさせる。著作権の配慮と理解の定着が同時に取れる
• 書籍由来のコンテンツは v-if="isDev" のdev限定カードでトップに置くと、非公開のままアクセス導線を確保できる
• 解説コンテンツは1問1図を目安に図解を入れると読み進む速度が変わる。出来が良かったらその場でスキルへ昇格させ、次回以降の既定値にする
• スキル間の依存は「参照」より「エッセンス統合」。単独で呼ばれたときに原則が抜け落ちる事故を構造的に防げる

おわりに

蔵書DBは作った当初「日本語で質問すると本棚が答える」道具だった。今日からはもう一段先、「本棚の本を自分の文脈で書き直して読む」道具になった。設計の原則を自分の会計題材で読み、Q&Aを図解付きの章カードでめくる。本を裁断してスキャンした時点では想像していなかった読み方が、計画書とサブエージェントの並列で1日に2本できあがった。次は読みながら気づいたことをコンテンツ側に書き戻す導線を考えたい。