既存リポジトリでAI駆動開発を始める順序──まず「変数を減らす」

既存リポジトリでAI駆動開発を始める順序──まず「変数を減らす」

大規模なコード移行をAIで完遂した事例が公開され、「100万行を2週間」といった数字が話題になりました。ただ、あの手法をそのまま自社の既存プロダクトに当てはめても、たいていうまくいきません。理由ははっきりしています。

移行という作業がAIに向いていたのは、次の4条件が最初から揃っていたからです。

1. 並列である — ファイル単位で独立に進む
2. 仕様が完全に存在する — 旧コードそのものが仕様書
3. 審判が最初からある — 既存のテストスイート
4. キューが自分で伸びる — コンパイルエラーが次のタスクになる

そして、あなたが抱えている既存プロダクトの機能開発は、この4つが1つも成立していません。

つまり、既存リポにAI駆動開発を入れるという仕事の実体は「AIにコードを書かせること」ではありません。

移行が最初から持っていた4条件を、自分のプロダクトに人工的に作りにいくこと。 それが基本であり、着手順序でもあります。

原則1｜まず変数を「減らす」

AI駆動開発の難易度を最も下げるのは、テクニックではなく 「既存資産のうち何を触らないか」を最初に決めることです。

数年動いている業務システムには、たいてい次のものが揃っています。

• 実運用に耐えているデータモデル（テーブル・リレーション）
• 業務要件や制度を反映したビジネスロジック（計算・判定・状態遷移）
• それを外部に出すAPI

これらは「古い資産」ではありません。検証済みの仕様そのものです。冒頭の移行事例で強みだった「旧コードが完全な仕様書である」という条件が、既存プロダクトにはもとから存在している、と読み替えられます。

だから最初の意思決定はこうなります。

バックエンドは変えない。変えるのはフロントだけ。 不足するAPIだけを、突合の結果として確定した分だけ拡張する。

多くのプロジェクトが、ここで「せっかくだからバックエンドも整理しよう」と欲張って崩れます。使い回せるものを最大限使い回すのは、コスト削減の話ではなくリスク削減の話です。

原則2｜残った変数を「分離する」

そのうえで、AI駆動開発が失敗する典型は、能力不足ではなく同時に動かす変数が多すぎることです。多くの現場で、次の4つが同時に走り出します。

✗ 4つを同時に動かす
   ① AI駆動開発（新しい開発手法そのもの）
   ② ドキュメント整備
   ③ データモデル変更
   ④ フロントUI/UX刷新
   → 不具合が出たとき、原因を切り分けられない

通常の開発でも、このうち1つを変えるだけで難易度は跳ね上がります。4つ重なると、手法が悪いのか、仕様が曖昧なのか、マイグレーションが壊れたのか、画面の実装ミスなのかが分かりません。AIは大量に生成するので、切り分け不能な変更が短時間で積み上がります。

分離の原則は2つです。

(a) フロントとデータモデルを同時に変えない。 データモデル変更はマイグレーションを伴います。そこにフロント大改修が重なると、不具合の切り分けが指数的に難しくなる。片方を固定します。

(b) 「手法の検証」と「価値の実装」を同時に評価しない。 最初のフェーズの成果物は機能ではなく、開発ループが回るという事実です。ここで作ったコードは捨ててもかまいません。

そして、順に動かします。

① AI駆動開発が回るかを検証
      ↓
② UI/UX刷新（機能は変えない）
      ↓
③ 1機能だけPoCで追加
      ↓
④ 確立した型で横展開

パイロットは次のどちらか一方に絞ります（両方は追わない）。

Phase 0｜「AIに読ませる前提知識」を既存コードから抽出する

変数を決めたら、次はコンテキストです。既存プロダクトの最大の資産は動いているコードなので、ここを機械的に抽出物へ変換します。

ドキュメントは3種類に色分けして管理します。

3番目は必ずスクリプトで作ってください。 AIに読ませて推測させると、それらしいが間違った依存関係が出ます。依存関係は「並列で何体走らせられるか」を決める情報なので、ここが不正確だと並列化そのものが破綻します。

そして最上位に、AIが最初に読むファイル（CLAUDE.md / AGENTS.md）を置きます。詳しくは「AIに読ませるドキュメント体系」で扱います。

抽出を高速化する「取得スキル」を先に作る

機能ごとに毎回ゼロから調べていると整備が進みません。**対象機能に関係するテーブル群・業務ルール・アルゴリズムを自動で集めてくる仕組み（スキルやサブエージェント）**を先に作ると、以降の機能単位の整備が高速かつ均質になります。1機能ぶんを手でやってから、その手順をスキル化するのが確実です。

Phase 0.5｜AIが直せる構造にする

見落とされがちですが、投資対効果が高い工程です。

• 複数リポに分散していれば統合する（エージェントは文脈を跨げない）
• 巨大ファイル・循環依存・共有可変状態を解く
• モジュール境界を明示する

判断基準は「美しさ」ではありません。

エージェントを同時に何体走らせられるか。

並列度はモデルの能力ではなくコードベースの構造で決まります。ここを整えないまま並列化しても、コンフリクトの解決に人間が張り付くだけになります。

よくある失敗：Phase 0 と 0.5 を飛ばす

最頻の失敗は、この2つを飛ばしていきなり実装フェーズから入ることです。コンテキストが無い状態でAIに書かせると、既存の設計思想から静かに逸れたコードが大量に生まれます。1つ1つは動くので、レビューで止めるしかなくなり、そこで詰まります。

順序を守ると、こうなります。

Phase 0    コンテキスト基盤   既存コードから ER図・テーブル定義・API定義を抽出
Phase 0.5  リファクタ／統合   AIが安全に触れる境界を作る
Phase 1    要件・Mock確認     画面一覧・ユースケース・デザイン確定
Phase 2    設計              シーケンス図・画面↔APIマッピング
Phase 3    実装              Mock→生成／既存API結線＋不足分のみ拡張
Phase 4    テスト・レビュー   静的解析／テスト／受け入れ基準
Phase 5    CI/CD・運用       lint・type・test・build・deploy

最初の2週間でやること

1. 触らない領域を宣言する — データモデル・ビジネスロジック・API・フレームワークは固定
2. 正本ルールを1枚決める — どの文書が真実か、矛盾時の優先順位
3. 用語集を作る — AIと人の解釈のズレはここから発生する
4. 既存コードからER図・テーブル定義・API定義を抽出させる
5. 依存グラフをスクリプトで生成する — 並列可能な単位を知る
6. パイロット1機能を決める — UI刷新か機能追加のどちらか一方
7. その1機能の審判を作る — 詳しくは「Mockを「審判」にする」
8. 審判をわざと壊して、落ちることを確認する

コードを書くのは9番目です。それより前の8つが、AI駆動開発の実体です。

よくある質問

Q. 既存コードが汚すぎてAIが理解できません。どうしますか？ A. Phase 0.5 の対象です。ただし全体を綺麗にする必要はなく、パイロット対象の機能が触る範囲だけを整えれば進みます。「どこまで整えるか」の基準は、エージェントが並列で動ける境界ができたかどうかです。

Q. ドキュメントが古くて信用できません。 A. 古いドキュメントより、動いているコードを信用してください。ER図・テーブル定義・API定義はコードから再生成し、古い文書は正本から外します。「正本ルール」を最初に決めるのは、まさにこの判断を全員で共有するためです。

Q. バックエンドを変えないと実現できない要件があります。 A. その要件を後フェーズに切り出します。フロント刷新で型を作ってから、データモデル変更だけを単独の変数として動かすほうが、同時にやるより速く終わります。

Q. 小さなチームでもこの手順は必要ですか？ A. 規模より「AIにどれだけ任せるか」で決まります。人間が全部読める量しか生成しないなら不要です。エージェントを並列で回し始めた瞬間から、審判とコンテキストが無いと破綻します。

Q. どのくらいの期間で効果が出ますか？ A. パイロット1機能を通すのに数週間、というのが実務的な目安です。ここで得られるのは機能ではなく「型」なので、効果が出るのは2機能目からです。1機能目の生産性で判断しないでください。

最終確認日: 2026-07-25