人間がコードを書くのをやめてみた
「実装もレビューも、全部AIにやらせよう。人間はコードを1行も書かない」
そう決めて走り出したのが、2月の中旬でした。対象は、長く運用してきた自社プロダクトのフロントエンド2つ。Laravel + Vueで作られた管理コンソールと、Nuxt2で動くユーザー向けWebアプリ。これを、まるごとNext.jsに置き換える。ページ数にして、およそ300。
普通に考えれば、少人数チームで数ヶ月で終わる規模ではありません。だからこそ、AIに賭けてみたかった。
先に結論を言ってしまうと、4ヶ月弱で実装はほぼ完了し、いまはQAに渡す直前まで来ています。人間だけなら、この期間では絶対に終わらなかった。
……ただ、ここに辿り着くまでの道のりは、お世辞にもスマートとは言えませんでした。何度も惨敗し、トークンを溶かし、たくさんの苦難はありました。
この記事は、これからAIで既存アプリの移行やリプレイスに挑もうとしている人に向けて、その「どこで転んで、どう這い上がったか」を、きれいごと抜きで書き残すものです。コードの細かい話は出てきません。語りたいのは、AIと一緒に大規模な移行を成立させるための「立ち回り」 の方です。
この記事の前提
- 移行元：
コンソール（Laravel + Vue）／ユーザー向けWebアプリ（Nuxt2）の2リポジトリ - 移行先：Next.js / 規模：約300ページ
- 期間：2月中旬〜（4ヶ月弱、実装ほぼ完了でQA直前）
- 体制：少人数チーム（2〜4人）
- 役割分担：実装もレビューもすべてAI。人間はルール・スキル整備とプロンプト実行、動作確認のみ
- 主なツール：Claude Code（中心）／ Chrome DevTools（MCP）／ Codex（トークン不足の補助に一部だけ）
そして、この移行には絶対に譲れない条件がありました。
仕様も機能も、変えてはいけない。
見た目のテーマやスキンの微調整は許す。でも挙動は変えるな、レイアウトも極力いじるな——つまり「作り直し」ではなく「等価な置き換え」です。この記事では、既存の挙動をどれだけ忠実に再現できたかを「再現率」と呼びます。そしてこの再現率との戦いが、4ヶ月すべてを貫くストーリーになりました。
なぜNuxtではなくNextを選んだのか
最初の分岐点は、移行先の選定でした。Nuxtのままモダン化する手もあったのに、なぜわざわざNextへ?
理由は身も蓋もありません。AIが一番得意な土俵を選んだからです。
Next.jsはエコシステムが厚く、世に出ている情報量が圧倒的に多い。ということは、AIの学習データも豊富で、出力精度が高くなる。完全AI駆動でいくと決めた以上、「人間にとっての最適解」ではなく「AIにとっての最適解」で技術を選ぶべきだ——そう考えました。
これが、ひとつ目の学びです。
完全AI駆動では、「AIが得意かどうか」がそのまま立派な技術選定基準になる。
そして、AIに走ってもらうためのレールとして、技術選定（キャッシュ・データフェッチ・フォーム・型検証・認証……）とコーディングルールを片っ端からMarkdownに落としました。各ルールには必須ルール・アンチパターン・具体例・チェックリストを必ずセットで。これが、後にAIと交わす「共通言語」になります。
このとき採用したアーキテクチャ（FSDインスパイアの5層構成、App Router、Server Component中心）の設計方針 は、別記事で詳しく書きました。「AIが迷わないレール」を具体的にどう敷いたか気になる方はどうぞ。
👉 Nuxt2 → Next.js 移行で採用した「FSDインスパイア」アーキテクチャ設計
また、データフェッチのパターンに関してはこちらの別記事で書いています。
……ここまでは、順調でした。問題は、いざ実装させてみてからです。
第一幕：再現率30%、惨敗
意気揚々と、Claudeに「既存ページのパス」「策定したルール」「移行条件」を渡し、仕様抽出からタスク分解、実装までを一気にやらせてみました。
出てきたものはかなり残念な結果でした。
- ヘッダーが、ない
- 機能が、揃っていない
- 元には存在しない機能が、なぜか増えている
- 配置もレイアウトも、ぐちゃぐちゃ
体感の再現率は、30% 、、、控えめに言って惨敗です。
既存画面
実装された画面
何が悪かったのか。答えはシンプルでした。ソースコードを渡すだけでは、AIは「正しい完成形」を知りようがなかったのです。コードは設計図ではあっても、「画面がどう見えて、どう動くべきか」という最終形そのものではありません。AIは想像で埋めるしかなく、その想像はことごとく外れました。
第二幕：AIに「画面を見せたら」化けた
転機は、ある気づきでした。
人間がこの移行をするなら、まず既存の画面を開いて、目で見るよな?
ならAIにも見せればいい。そこで仕様抽出の工程を専用のAgentに切り出し、こんな命令を組み込みました。
Chrome DevToolsで既存画面を必ず参照してから、仕様を書き起こせ。
加えて、画面構成・使用API・必要な型・コンポーネント・データフローまでを構造化して吐き出させるようにしました。
結果は劇的でした。実際に動いている画面をAIが「見た」ことで、UIの差分がごっそり消えたのです。再現率はおよそ50%まで跳ね上がりました。
ソースから挙動を「想像」させるな。動いている画面を「見せろ」。
これだけで再現率は別物になる。
とはいえ、まだ半分。今度は別の粗が見えてきました。コンポーネント設計が非効率で、本来は共通部品にすべきものが、ページごとに独自実装されてしまう。AIは目の前の1ページしか見ていないので、全体最適ができないんですね。
そこで、既存のsharedパーツ（共通UIやヘッダー・ナビなどの大きなブロック）を棚卸しして一覧化し、「これは共通部品を使え」とAIに教え込みました。
ちなみに——この「ページの棚卸し」自体が、地味に最大級の難所でした。Vue Router側はSPA化が進んでいて、機械的にページ一覧を抜き出せない。最終的にはLaravelのBladeのルーターまで遡り、最後は人間が手作業で確認・修正する羽目に。移行対象を正確に数えることさえ、ひとつのプロジェクトでした。
幕間：トークンが溶けていく
順調に見えた矢先、見過ごせない問題が顔を出します。トークンの消費が、想定をはるかに超えて激しい。
最初は「大規模だから仕方ない」と思っていました。でも要因を分解すると、犯人ははっきりしていました。
仕様抽出が甘い → 実装が仕様とズレる → 差分を調べて直すために、また大量にAIを使う → トークン急増
この負のループが、あちこちで回り続けていたのです。
対策は、直感に反するものでした。「節約のためにAIの利用を減らす」のではなく、最初の仕様抽出を、もっと分厚くする。具体的には、仕様抽出Agentにこう命じました。
- 画面内で可能なすべての操作を網羅せよ（ボタン後の挙動、ダイアログの中身、起こりうる全インタラクション）
- エラーハンドリングのパターンを全種類書き出せ（API・バリデーション・権限……、UI表示やリカバリ手順まで)
すると、手戻りが激減し、結果的にトークンも収まっていきました。
AI駆動でトークンが膨らむとき、犯人はたいてい「使いすぎ」ではなく 「精度不足による手戻り」 。
ケチるべきは利用回数ではなく、やり直しの回数。精度への投資が、最大の節約になる。
第三幕：300ページへ、どう横展開するか
1ページの精度が見えてきたら、次は「これを300回、安定して回す」フェーズです。sharedパーツを一気に作り、ルールとAgentを盛り込んだテンプレートリポジトリを構築しました。
ここで一度、痛い目を見ます。「ルールは多いほど安心だろう」と全部を一枚のルールファイルに詰め込んだら、コンテキストが膨れすぎて、逆に精度が落ち、トークンも無駄に増えたのです。
学んだのは、ルールは「量」ではなく「届け方」だということ。そこで階層的に分離しました。
| 配置 | 役割 |
|---|---|
| トップレベル | 大前提・絶対に破ってはいけないルール |
| リポジトリルール | 大まかな規約 |
| スキル | 各ライブラリの使い方・アーキテクチャ |
| Agent | 仕様抽出・実装計画・コードレビュー |
ねらいは、必要なときに、必要なルールだけがAIの視界に入る状態を作ること。人間に分厚いマニュアルを丸暗記させないのと同じです。
CLAUDE.md・Skills・Rules・Agent・MCP……それぞれを「どう書き分けるか」 は、別記事で利用頻度順に整理しました。この移行プロジェクトでの実例も交えて解説しているので、具体的な実装手段が気になる方はあわせてどうぞ。
レビューも仕組み化しました。観点別に5体のレビューAgentを用意し、1コマンドで同時発火 → 完了後に Critical / High / Medium / Low でランク付けしたサマリーを出す。ただ、当初は5体がそれぞれ勝手にソースを読みに行く設計で、またトークンが膨張。これは「最初に1回だけソースを読み、その内容を5体に配る」方式へ変えて解決しました。AIのチーム編成にも、人間の組織論と同じコツが効くんですね。
第四幕：「正解」が、どこにもない
実装が軌道に乗り、ページが量産されていく。順風満帆——のはずが、終盤、背筋が冷たくなる問いにぶつかります。
AIが作ったこれ、本当に元と同じ挙動なのか?
QAしたいけど、そもそも 「正解」がどこにも書かれていない。
旧アプリの細かな仕様は、古いコードの中にしか存在しません。テスターが毎回ソースを遡るなんて不可能だし、「動いてるように見える」だけでは、バリデーションやエラー時の微妙なズレを見抜けない。正解の不在は、移行プロジェクトの静かな爆弾でした。
そこで、移行ページごとにQA仕様書を自動生成するスキルを作りました。目的はただ一つ。
ソースを見なくても「何が正解か」がわかる状態を作る。
やることは3ステップです。
- 新実装の仕様を書き出す — Next.js側のページから関連コンポーネント・APIハンドラ・翻訳・ミドルウェアまで辿り、画面構成・バリデーション・エラー挙動を明文化する
- 既存と突き合わせる — 移行元の対応コンポーネントと比較し、表示項目の欠落/追加/参照ズレ、サーバー側バリデーション、ステータス別のエラー挙動の差分を炙り出す
- 差分を消す — 見つかったズレを共通パターンに寄せて直す
これを全ページで回し、差分を潰していく。AIが書いたものを、AIが作った仕様書で検証する——このループが回り始めて、ようやく「QAの基準」が手に入りました。移行が終わった後も、仕様書という資産が残る。これは思わぬご褒美でした。
最終幕：一番つらかった、エラーハンドリングの大量修正
そして、最後に待っていたのが——4ヶ月で一番つらい作業でした。
「仕上げにエラーハンドリングを統一しよう」。そう軽い気持ちで手をつけた瞬間、その手前にある巨大な地雷を踏み抜きます。そもそも、実装の方針が、何ひとつ揃っていなかった。
データフェッチひとつ取っても、実装された場所（ページ / Route Handler / Server Actions）や時期によって、こんな具合でした。
あるページは独自実装。別のページは簡易ヘルパー。また別のページは初期に作った共通ヘルパー。
しかもバリデーションルールもバラバラ、エラー時の挙動もバラバラ、認証・認可の有無すらバラバラ。統一しようにも、統一されていなさすぎて、どこから手をつければいいのか分からない。
最終的には、共通APIヘルパーの利用を強制し、リクエストボディのparseエラー、レスポンスのparseエラー、APIエラー、セッション切れ——といった処理を横断的に揃えました。でもそれは、表面のエラー処理を直すだけでは終わらず、その下にある実装方針そのものを作り直すリファクタリングを伴いました。本当に、骨が折れた。
なぜ、こんなことになったのか。正直に言うと、原因は「ルールを詰め切れなかった」というより、もっと根っこにありました。
「AI駆動なんだから、細かい統一は後から一気に直せばいい」と、どこかで楽観していたから。
汎用的なスキルは整えていたので、実装の大方針が大きく外れることはない。だから「ロギングやエラーハンドリングのような細部は、最後にまとめてAIに直させればいい」と高を括っていたのです。
ところが、現実はそう甘くありませんでした。汎用スキルだけだと、ページごとに実装の流儀が少しずつズレていく。厳格なルールがあるわけではないので、その小さなズレはレビューAgentもすり抜けてしまう。気づけばプロジェクト全体で実装がバラバラになり、共通ヘルパーすら使われていない箇所が点在していました。だからこそ、ヘルパーの中身を直すだけでは済まなかったのです。
この反省が、この記事で一番伝えたい教訓に直結します。
4ヶ月を振り返って
よかったこと
圧倒的なスピード。 これに尽きます。約300ページのリプレイスを、少人数・4ヶ月弱で実装完了の一歩手前まで持ってこられた。人間だけなら、まず不可能だった工数です。AIは「賢い同僚」というより、明確に「加速装置」でした。
属人性が消えた。 仕様もルールもレビュー基準も、すべてドキュメントとAgentに落とし込んだ結果、「誰がプロンプトを回しても、同じアウトプットに近づく」状態になりました。物量勝負の移行作業と、これほど相性のいい性質はありません。
仕様が可視化された。 長年コードの奥に埋もれていた暗黙仕様が、仕様抽出やQA仕様書スキルを通じて、初めて明文化されました。移行が終わってもドキュメントとQA基準が残る。これは副産物でありながら、組織にとって大きな資産です。
もっと改善できたこと
一方で、最大の反省を一言でまとめると、こうです。
プロジェクト固有のルールとハンドリングは、序盤にスモールスコープのpilotで固め切るべきだった。
汎用的なスキルやルールは作っていました。でも、心のどこかで「細かい統一は後からAIに一気に直させればいい」と楽観していた。だから「このプロジェクトにおけるデータフェッチ・バリデーション・認証認可・エラーハンドリングの型」までは詰め切れていなかった。その結果、各ページが少しずつ違う流儀で実装され、最終幕の大規模リファクタリングという形で、ツケを一括で払う羽目になりました。
もし最初に、少数のページで「この4点の型」を完全に固め、具体的なサンプルコード付きの“プロジェクト専用スキル” として用意してから横展開していたら——あの大量修正の大半は避けられたはずです。
ここに、AI駆動開発の核心があると思っています。
AIに渡す「お手本」の具体性が、そのままアウトプットの一貫性になる。
汎用ルールだけでは足りません。プロジェクト固有の「正解例」を、いかに早く・具体的に用意できるか。それが、後の大量修正を避ける最大の予防策でした。
おわりに
完全AI駆動での大規模リプレイス。4ヶ月を経て手に残った教訓を、最後に並べておきます。
- AIが得意な土俵を選ぶこと自体が、立派な技術選定（だからNextを選んだ）
- ソースを想像させず、画面を「見せる」 だけで再現率は跳ねる
- トークンを溶かす犯人は使いすぎではなく手戻り。精度への投資が一番の節約
- ルールは量より届け方。必要なものだけをAIの視界に入れる
- 「正解」を仕様書として外部化しなければ、QAは成立しない
- そして——プロジェクト固有の型は、何よりも先に、pilotで固め切れ
AIは開発を確かに変えました。でも、魔法ではありません。この4ヶ月で一番強く感じたのは、人間の仕事が「コードを書くこと」から「AIが正しく走れるレールを敷くこと」へ、はっきりと移ったということ。
これからAIと一緒に移行・リプレイスに挑む誰かの、転ばぬ先の杖になれば嬉しいです。