韓国半導体輸出ページに6月分を反映 - PDF取得失敗の原因特定とチャート表示検証の往復

開発mdx-playground

朝、韓国MOTIEの月次輸出PDFを取りに行ったらcurlが弾かれた。毎月1日頃に公表される統計を /memory-makers/korea-chip-exports ページに反映する月次作業の初手でつまずいたところから、この日の往復が始まった。

やったこと

  • 2026年6月分のデータ（半導体輸出 $44.82B / +199.5%）をページに反映した
  • PDF取得が失敗した原因を特定し、更新コマンド2本を整備した
    • .claude/commands/update-korea-chip-exports.md（ワークフロー全体）
    • .claude/commands/update-korea-chip-exports-pdf.md（PDF取得の詳細手順）
  • dev環境でブラウザ表示を検証し、累計ラベルのズレを1件修正した
  • 「チャートに6月分が入っていない」という自分の指摘を切り分けた（合計チャートには入っていて、品目別チャートは5月分まで）

PDF取得コマンドの整備

更新手順のドキュメントは2本に分けた。役割分担はこうなっている。

  • /update-korea-chip-exports（ワークフロー全体・こちらが正）
    • 韓国MOTIEの月次半導体輸出と台湾MOFの月次総輸出を取得し、輸出統計のSSOT（exportStats.ts）に反映する
    • /memory-makers/ の「輸出の統計」カードとSK Hynixページの「3層シグナル①」が、同じSSOTから描画される
  • /update-korea-chip-exports-pdf（PDF取得の詳細手順）
    • 毎月1日頃に公表されるMOTIE/KDIの月次輸出PDFを取得し、半導体合計・MCP/SSDの金額・DRAM/NANDの輸出単価を抽出する

ワークフロー全体のドキュメントは自分で整えて、PDF取得の詳細手順のほうはClaude Codeに実物で検証させた。PDF掲載ページの一覧と検索フォームのパラメータを実際に叩かせて、キーワード検索が機能することも確かめてある。

朝取得できなかった原因は、検証で判明した。User-Agentヘッダーなしのcurlがサーバーに弾かれていた。手順書に書いてあったコマンドをそのまま実行させて失敗を再現し、User-Agentを付けたら通ることを確認して、スラッシュコマンドに反映してもらった。

# NG: 弾かれる
curl -o report.pdf "https://.../monthly-export.pdf"

# OK: User-Agent必須
curl -A "Mozilla/5.0 ..." -o report.pdf "https://.../monthly-export.pdf"

半導体合計だけでなく、MCP/SSDの金額とDRAM/NANDの輸出単価もすべてPDFから取れることを実物で確認済み。来月からは手順書どおりに叩けば同じ失敗をしない状態になった。

dev環境での表示検証

「データはちゃんと直っているのか」を画面で確かめたくなり、QAスキル（Chrome DevTools MCP）でブラウザ確認をしてもらった。デバッグポートが空いていなかったので、MCPのautoConnect経由で繋がるかを試すところから始まり、devサーバーの起動待ちを挟んでようやくページが開いた。

ここからが難航した。devサーバーがこの日4回落ちた。既知のHMRストーム問題で、ページのリロードがタイムアウトしてエラー画面になるたびに、状態確認と再起動を挟むことになる。一度は「落ちたか」と思ったらビルド中だっただけで、待てば復旧した。逆に、表示確認の報告直後に本当に落ちていた（exit 1）こともあった。issueには「表示確認が終わったらdevサーバーを都度止める運用が安全」と再発記録を追記してもらった。今回の一連の確認はファイル編集をほとんど挟まなかったので、編集さえしなければしばらく安定して動く、という感触もつかめた。

検証自体は成果があった。6月データ（$44.82B / +199.5%）がカード・チャート・表・注記のすべてに反映されていることを確認できたのに加えて、表示確認の過程で累計ラベルのズレが1件見つかった。データは6月分まで入っているのに、累計の注記が「1〜5月」のままだった。その場で「1〜6月」に直してもらい、リロードして反映を確認した。

「チャートに入っていない」の切り分け

確認完了の報告を受けたあと、スクリーンショットを二度見した。チャートに6月のバーがないように見える。「やっぱり入ってないですよね、6月分」と突き返した。

切り分けてもらった結果はこうだった。

  • 合計チャート2本には入っている: 月次チャートの最後のバーは '26/6（$44.82B、前年比約+200%）で描画済み
  • 入っていないのは品目別チャート: DRAM・NAND・MCP・DRAMモジュール・SSDの品目別は2026年5月分が最新

つまり「データが反映されていない」のではなく、合計と品目別で最新月が1か月ズレている状態だった。同じページに更新タイミングの違うデータ系列が同居していると、片方だけ見て「入っていない」と誤読する。自分がまさにそれをやった。誤解を招かないよう品目別セクションに説明の一文を足してもらい、HMRの反映を待ってDOMで直接確認した。

余談だが、この切り分けの途中でブラウザのタブがすり替わっていて、確認対象のページを見失う一幕もあった。自分が開き直した韓国半導体ページは別タブ（タブ29）になっていて、ページ選択ツールで切り替えてから確認を再開した。QA検証は「どのタブの、どのチャートの、どの系列か」を毎回固定してから見ないと、確認したつもりのすれ違いが起きる。

セッションの最後、バックグラウンドのdevサーバータスクは停止済みなのにポート3000がHTTP 200で応え続けていた。別セッションで起動したサーバーが生きていたようで、ページはそのまま閲覧できる状態だった。

学び

  • 取得失敗はまず手順をそのまま再現させる。今回はUser-Agent欠落という単純な原因だったが、再現させなければ「サイト側の問題かも」で止まっていた。原因を特定したら手順書に焼き込む
  • 表示検証は副産物を拾う。データの正しさを見に行ったつもりが、累計ラベルのズレという別のバグを拾えた。数字だけでなく注記・ラベルまで目を通す価値がある
  • 「表示されていない」は系列単位で切り分ける。合計と品目別のように更新タイミングが違う系列が同居するページでは、どのチャートのどの系列に入っていないのかを特定してから直す
  • devサーバーは使い終わったら止める。HMRストームで1日4回落ちる環境では、表示確認のたびに起動→確認→停止のサイクルにしたほうが速い

次にやること

  • 品目別チャート（DRAM・NAND・MCP・DRAMモジュール・SSD）に2026年6月分を、品目別データの公表を待って反映する
  • 来月の更新は整備した2本のコマンドどおりに実行し、手順書に穴がないか答え合わせをする
  • 表示確認が終わったらdevサーバーを止める運用を守る（issueに再発記録済み）