本文へスキップ
記事一覧

AI Workflow • 7分で読めます

捨てた移行ツールと、2 週間で 700 ページを移行したツール

Bruce | OSBR •

4 月、あるクライアントから、コーポレートサイトの 700 ページ以上を新しいデザインシステムへ移行してほしいという依頼を受けました。どのページも手書きの HTML で、長年にわたって多くの開発者が書き足してきたものです。新しいデザインは、コンポーネントをまとめた Storybook と、旧 CSS クラスと新コンポーネントの対応を記したスプレッドシートとして届きました。

最初に作った移行ツールは、5 日で使わなくなりました。この記事では、なぜそれを捨てたのか、代わりに何を作ったのか、そして最初のアイデアのどこが結局戻ってきたのかを紹介します。成果は事例紹介にまとめています。ここでは、そこに至るまでの過程をお話しします。

1 回目:どんなサイトにも使えるツール

最初に作ったのは html-migrator というコマンドラインツールです。目指したのは、どのサイトにも再利用できるものでした。旧ページ、Storybook、対応表を入れて、コマンドを 1 つ実行するだけです。

AI は準備段階を担当しました。対応表を読み、必要な列を見極め、旧クラスと Storybook のコンポーネントを照合し、対応表にないクラスにはルールを提案します。提案されたルールは人が 1 つずつ承認または却下し、実際の書き換えは AI を使わない普通のスクリプトが行いました。

設計はきれいでした。AI のトークンを一切使わずに回る 70 件のテストがあり、コードにはサイト固有の名前が 1 つもありません。ただ、実際のページには合いませんでした。

うまくいかなかった理由

スクリプトはルールに書かれたことしかできません。そしてルールとは「この旧クラスはこのコンポーネントになる」というものです。ところが旧サイトでは、クラスの使い方がばらばらでした。同じボックスでも、あるページでは余分なラッパーがあり、別のページではタグが違い、また別のページではインラインスタイルが付いていたり、クラス自体がなかったりします。旧コンポーネントを 3 つ重ねて 1 つにしたブロックもありました。

スクリプトには、2 つのブロックが「書き方が違うだけの同じもの」だと判断できません。照合できなかった部分は手つかずのまま残り、人が直すリストに回ります。このサイトでは、そのリストが作業の大半になるはずでした。

そこで、作り直すことにしました。

2 回目:AI に 1 ページずつ読ませる

Claude Code で作った 2 つ目のバージョンでは、役割分担を逆にしました。AI がスクリプト用のルールを書くのではなく、AI がすべてのページを読みます。Claude Code のスキル群と、それぞれ 1 つの役割を持つ 4 つのエージェントで構成しました。

  • アナリストは旧 HTML を読み、各ブロックが何で、何のためにあるのかを説明します。何に変えるべきかは決めません。
  • アーキテクトは各ブロックを新しいコンポーネントに対応づけ、その確信度を示します。合うものがなければ、推測せずにそう伝えます。
  • トランスフォーマーはページを書き換え、コンテンツを 1 つ残らず保持します。
  • クリティックは新旧を比べ、失われたものを探します。抜け落ちたキャプション、消えたテキスト、テンプレートから紛れ込んだダミーテキストなどです。

さらに、「移行済み」「スキップ」に加えて 3 つ目の答えとして手動を用意しました。安全に変換できないほど特殊なブロックは、見た目だけそれらしい誤った出力を作るのではなく、旧マークアップのまま残して印を付けます。

最初のアイデアの半分が戻ってきた

1 週間ほどで無駄に気づきました。1 対 1 で対応が明らかな見出しでも、4 つのエージェントをすべて通っていたのです。見出しを 1 つ変えるのに、AI の処理が 4 回です。

そこでルールエンジンを追加しました。対応が明らかなクラスについて、ファイルに書いた単純なルールで変換します。最初は安全な見出しだけを対象にし、検証済みのルールがないクラスはこれまでどおりエージェントか手動に回しました。数日のうちに、管理していた旧クラス 119 個のうち 102 個をルールでカバーできるようになりました。

つまり、最初のツールのうまくいっていた部分を作り直したことになります。違いは置き場所です。機械的なケースはスクリプトが処理し、判断が必要なものはすべて AI が担当しました。

Two attempts compared: attempt one has AI suggest rules for a script; attempt two sends obvious classes to a rules engine and everything else through analyst, architect, transformer and critic agents
1 回目は AI がスクリプトの前段を担当。2 回目は、明らかなクラスはルールへ、それ以外は 4 つのエージェントへ。

700 ページを回せるコストにする

4 月末の時点で、実際の移行を約 10 回実行したコストは 17 ドルでした。テストなら問題ありませんが、700 ページには向きません。原因は 3 つありました。

  • すべての実行で、最も高価なモデルである Opus を使っていた。
  • ファイルごとに新しいセッションを始め、同じコンテキストを毎回読み込んでいた。
  • 119 クラス中 97 クラスは 16 KB の要約で足りるのに、アーキテクトが 384 KB のコンポーネント表を丸ごと読んでいた。

デフォルトを Sonnet に切り替え、共通のコンテキストを 1 回で読み込めるようファイルをまとめて処理し、アーキテクトには先に要約を読ませるようにしました。これで 1 回あたりのコストが約 70% 下がる見込みでした。

2 週間で 700 ページ

6 月、デザインチームから対応表の完成版が届きました。すべての旧コンポーネントについて、新しいマークアップがそのまま記されたものです。これを主な情報源とし、作業の流れも 1 ページ単位に変えました。ページ全体の計画を立て、人が計画を確認し、書き換え、レビューし、プルリクエストを作成します。

あとはチームで回すだけです。6 月 9 日から 20 日までに 700 件以上の移行プルリクエストをマージし、そのうち 254 件は 1 日でした。どのプルリクエストにもプレビューリンクが付いているので、レビュアーはマージ前に新デザインでのページを確認できます。

Bar chart of migration pull requests merged per day from 9 to 20 June 2026, peaking at 254 on 19 June, 738 in total
1 日あたりにマージされた移行プルリクエスト(2026 年 6 月 9〜20 日)

4 月の自分たちに伝えたいこと

  • 汎用ツールから作らない。 このサイトを理解する前に、どんなサイトにも使えるものを作ってしまいました。再利用できる部分は、実際のページに向き合ううちに自然と出てきました。
  • 書き出せることはスクリプトに、判断が必要なことは AI に。 最初のツールはすべてスクリプト、2 つ目の最初のバージョンはすべて AI でした。うまくいったのは、その両方を組み合わせたものです。
  • AI に「わからない」と言える手段を与える。 手動という選択肢と確信度の表示は、どんなプロンプト改善よりも品質に効きました。
  • コストは早めに見る。 10 回で 17 ドルなら誤差ですが、700 ページになると設計の問題になります。

このシリーズの次回は、コードを書かない人たちが GitHub の Issue フォームから自分で移行を進めた仕組みを紹介します。

サイトの移行をお考えですか?事例紹介をご覧いただくか、お気軽にご相談ください。

AIアシスタントとチャット