開発mdx-playground

夏に3泊4日で台湾に行くことが決まった。せっかく行くなら現地での「なぜここに残っているのか」を解像度高く見たい。そこで /taiwan というシリーズ枠を mdx-playground 上に切り、行く前に調べた内容を分割記事として積み上げていくことにした。一日でインデックス＋8ページの骨組みを建て、フォントを揃え、地図を入れ、最後に「事典的すぎて知的好奇心を刺激しない」問題まで踏み込んで全ページを書き直した。

まず骨組みを建てる

memory-makers シリーズで使っているカードコンポーネントのパターンが気に入っていたので、それを台湾シリーズにも転用する方針で Claude Code に指示した。一つの記事に詰め込むと膨大になって誰も読めないので、インデックスから各テーマに分岐する形にしたい。

  • インデックスページ /taiwan
  • サブページ 8 枚（歴史概観 / 日本統治 / 戦後民主化 / 民族 / 言語 / 地理と主要都市 / 観光ガイド / 旅程 / 読書メモ）

サブページは一旦タイトルとリード文だけの空ページにして、まず動線を通すところから始めた。vue-pages スキルを読み込ませて、breadcrumbs ラベルもこのタイミングで仕込んでもらう。

フライトをカレンダーに登録してもらう

旅程の前提として、往復フライトの時間を確定させたかった。航空会社のサイトを見て便名だけメモしておき、出発・到着時刻と所要時間は調べてもらった。

ここまで出たら、そのまま gogcli スキルで自分の Google カレンダーに登録までやってもらった。出発地と到着地のタイムゾーンを ISO8601 のオフセットで別々に渡せば、1イベントで現地時刻が正しく入る。カレンダー内部は Asia/Tokyo に正規化されて表示されるので、復路便の出発も「JST 表記＝現地時刻 TPE」が見える形で揃った。ここを後から手で直さなくて済んだ。

観光ガイドページに地図を入れる

3泊4日の自由時間で歩ける範囲は限られる。ホテルが決まっていない段階でも、台北市内＋近郊で「ここまでなら現実的に足を運べる」というスポットを地図でまず可視化したかった。

最初に Wikimedia の画像 URL を 640px- で並べたら全件 HTTP 400 で落ちた。Wikimedia は事前生成された特定サイズの thumb しか配信しない仕様で、API が返す 330px- がカード幅にも合うサイズだった。全画像を 330px に揃え直したら 200 で通った。

地図は Leaflet を入れるか迷ったが、memory-makers の FactoryLocationMap.vue で使っている SVG + 簡易投影方式を流用した。ピン番号を打って右側に凡例を出す形で、依存を増やさずに済む。

<!-- 観光ガイドページの地図セクション（抜粋） -->
<svg viewBox="0 0 600 500" class="taipei-map">
  <g v-for="(spot, i) in spots" :key="spot.id">
    <circle :cx="project(spot.lng).x" :cy="project(spot.lat).y" r="8" />
    <text :x="project(spot.lng).x" :y="project(spot.lat).y + 4">{{ i + 1 }}</text>
  </g>
</svg>

「全体的にフォントがちっちゃい」

ここで一度ブラウザに切り替えて確認してもらったら、ユーザーから「全体的にフォントがちっちゃい」と指摘が入った。並べてみると、ブログ記事本文は p が 1rem（17px 近辺）なのに対し、台湾ページは p 0.92rem / table 0.85rem で組んでいた。読み比べると一目でわかる差で、ここを揃えていないと「シリーズ全体が安っぽく見える」という当然の帰結が出ていた。

apps/web/app/assets/css/taiwan-article.css を新規で切って、全ページに class="taiwan-article" を付与＋ <style src="..."> で読み込む構成にした。9 ファイルへの適用は並列の Edit で一気に流した。

ただ初回の修正では scoped style と specificity が同点で、共通 CSS が読み込まれているのにフォントサイズが上書きされなかった。共通 CSS の全セレクタに body プレフィックスを足して詳細度を上げたら、ようやく本文 p が 17px で出るようになった。

/* taiwan-article.css 抜粋 */
body .taiwan-article p { font-size: 1.0625rem; line-height: 1.85; }
body .taiwan-article h2 { font-size: 1.5rem; }
body .taiwan-article table { font-size: 1rem; }

「何年から何年だけじゃなくて、何年間か」

歴史概観ページを開いてもらったら、次の指摘が来た。「1895〜1945 って書いてあるけど、それが何年間なのか書いておいてくれませんか。わかりづらいんで。」

確かに、年号だけを並べても期間としての重みが伝わらない。タイムライン表・章タイトル・リード文の3箇所に「(50年間)」のような注を入れた。地味だが、読み手の頭に「明治末から太平洋戦争終結まで丸ごと一世代分」という時間幅が乗るかどうかで体感が変わる。

「地理と主要都市」に台湾全島マップ

「地理と主要都市」のページを開いたら、ユーザーから「さすがにこれ地図で入れてほしい」と返ってきた。市名と座標だけ表で並べていたので当然の指摘で、ここも観光ガイドと同じ SVG 方式で台湾全島の輪郭＋主要都市ピンを描いた。輪郭データは memory-makers のものを流用できた。

「どのページも知的好奇心を刺激してくれない気がする」

ここが一番痛い指摘だった。全ページの肉付けを並列のサブエージェントで一気に終わらせて「仕上がりました」と提出したら、ユーザーから「なんだろう、どのページもあまり知的好奇心を刺激してくれない気がするんですけど、これ原因って何なんですかね」と返ってきた。

原因は明白で、Wikipedia の要約を平面的に積み上げただけになっていた。各ページが「what」しか書いておらず、「なぜそうなったか」「他とどう違うのか」「読み手の頭に違和感を残す論点」が一切なかった。司馬遼太郎の『街道をゆく 台湾紀行』を読みながら現地を歩くための補助記事のはずなのに、これでは読み手の脳内に何の問いも残らない。

修正パターンとして「問い起点」を採用した。

  • 章の冒頭に「なぜ?」「どうして?」の 問いを立てる
  • そのあとに 驚き（直感に反する事実、他国との対比）を置く
  • 写真＋キャプションで実物を見せる
  • そのあとで初めて事典的事実を入れる

まず history-overview だけをこのパターンで書き直して見せたら、「非常に良いと思います。前よりは良くなったと思います。他のページもこんな感じにしてもらえませんか」という反応だった。「very good」ではなく「前よりは良くなった」というラインで止めてくれているのが正直で、これを基準にして残り 7 ページに横展開した。

| ページ           | 立てた問い数 | 写真枚数 |
| ---------------- | -----------: | -------: |
| japanese-rule    |            5 |        4 |
| postwar-democracy|            5 |        3 |
| peoples          |            4 |        3 |
| languages        |            4 |        2 |
| geography        |            3 |        4 |
| itinerary        |            3 |        2 |
| reading-notes    |            -（章立て目次のみ）|        - |

サブエージェント 7 並列で投げて、完了通知が来た順から壊れ内部リンクとスタイル整合を確認して回った。geography は既に作った全島マップを壊さないよう、reading-notes は読みながら自分で書き加える前提の章立て目次を残すよう、個別に指示を足した。

今日の学び

  • シリーズ枠を最初に建てるとリズムが出る: インデックス＋空ページ 8 枚を先に並べると、各ページの「これは他とどう違う章か」が嫌でも問われる。一つの巨大記事にしていたら、この問いは出てこなかった。
  • 「事典的に what を並べる」は AI が一番得意で、一番つまらない出力: 並列サブエージェントで一気に肉付けすると、見た目は揃うがどのページも同じトーンになり、読み手の頭に問いが残らない。「問い起点＋驚き＋写真」の型を1ページで先に確立してから横展開する手順が正解だった。
  • 「前よりは良くなった」評価の重さ: 「very good」と言われるよりも「前よりは良くなった」のほうが、いま自分が踏んでいる段の高さを正しく教えてくれる。司馬を読みながら現地で参照したくなる記事まで、まだ何段か登る余地が残っている。

明日以降に持ち越し

  • reading-notes に司馬『街道をゆく 台湾紀行』を読みながら章別メモを足していく
  • 旅程ページに、ホテルが決まり次第「拠点からの30分圏」セクションを追加する
  • 観光ガイドの地図ピンに「営業時間」「定休日」のホバーラベルを足す