エージェント パイプラインと Antigravity を使用してレガシー モダナイゼーションを大規模に自動化する

1. モダナイゼーションの取り組みの方向性を定める

大規模なレガシー モダナイゼーションの自動化 この包括的な Codelab は、アーキテクチャの詳細な解説記事である Antigravity とマルチエージェント オーケストレーションでモダナイゼーションを自動化する方法から直接派生した、実践的なラボです。具体的なデモンストレーションには従来の Node.js フレームワークの切り替えを使用しますが、ここで説明するコア設計パターン、ディレクトリ構造、エージェント型オーケストレーション プロセスは言語に依存せず、大規模なレガシー モダナイゼーション プロジェクトに普遍的に適用できます。

単一ファイル内の行を自動補完するだけの標準的なコーディング アシスタントとは異なり、Google Antigravity のエージェントファースト機能を活用して、専門的な AI サブエージェントの自律型チームをオーケストレートする方法を学びます。これらのエージェントは、リフレクション ループを使用して、レガシー コードベースのリバース エンジニアリング、厳格なテストスイートの作成、最新のアーキテクチャのスキャフォールディング、コンパイラ エラーの自己修正を独立して行うことができます。その間、ハイレベルなアーキテクトとして絶対的な制御を維持できます。

学習内容

  • ワークフローのマッピング: 決定論的な設定タスクと複雑なヒューリスティック リファクタリングの課題を正しく分類して分離する方法。
  • スキル アーキテクチャ: プログレッシブ ディスクロージャーと YAML ルーティング メタデータを使用して、拡張可能なエージェント スキルパックを構築する方法。
  • オーケストレーション設計パターン: ルーター、プランと実行、リフレクションの設計パターンを連鎖させて、大規模なリファクタリングを推進する方法。
  • 厳格な入力/出力コントラクト: 多段階のリバース エンジニアリングとターゲット スキャフォールディング パイプライン全体で、明確な入力/スキル/出力境界を適用する方法。
  • パリティ検証: Antigravity のブラウザ サブエージェントを活用して、Chrome ウェブブラウザ内で並列パリティ テストを実行する方法。

作成するアプリの概要

完全に自動化されたグリーンフィールド リファクタリング パイプラインをオーケストレートします。このパイプラインは、象徴的で時代遅れのレガシー Express と Mongoose CRUD モノリス（「madhums デモ」）を取得し、MongoDB、厳格な Zod 検証、アクセス可能な ShadCN UI コンポーネントによってサポートされる厳密に型指定された Next.js App Router アプリケーションにゼロから自律的に再構築します。

必要なもの

  • Google Antigravity IDE がローカルにインストールされました（antigravity.google で入手可能）。
    • ローカルにインストールされた Node.js（v18 以降） 。
  • 自動 UI 検証用の Chrome ブラウザ 。
  • オープンソースの modernizing-expressjs デモンストレーション モノレポのクローン。

2. モダナイゼーション環境を設定する

自律型エージェントが古いレガシー コードベースで動作する前に、クリーンで安定性の高いモノレポ環境を確立する必要があります。AI アシスタントにクリーンなベースラインを提供することで、10 年前のパッケージの脆弱性やコンパイラの不一致に対処するためにトークンを無駄にするのではなく、高品質の最新コードの生成に完全に集中できます。

レガシー Express と最新の Next.js アーキテクチャのマッピング

コンポーネント

レガシー スタック

最新の置き換え

理由

アーキテクチャ

Express モノリス

Next.js App Router

最適化されたレンダリングと React Server Components（RSC）のパフォーマンスを実現するために、ロジックをサーバー コンポーネントに分離します。

データロジック

Mongoose（ODM）

MongoDB + Zod

暗黙的な ORM フックを、明示的で型安全な Zod スキーマと生のドライバ パフォーマンスに置き換えます。

言語

CommonJS / JavaScript

TypeScript（ESM）

コンパイル時の安全性を確保し、最新のモジュール標準に移行します。

フロントエンド

Pug/EJS（サーバービュー）

ShadCN UI + Tailwind

厳格なテンプレートから、コンポーザブルでアクセス可能でユーティリティファーストなデザイン システムに移行します。

認証

Passport.js

NextAuth

Edge と最新のプロバイダの組み込みサポートにより、セッション管理をモダナイズします。

安全

手動ミドルウェア

Zod（厳格な検証）

スタック全体でデータ検証の「信頼できる唯一の情報源」を実装します。

モダナイゼーション ハブを初期化する

最初の決定論的なアクションは、分離されたモノレポ構造をクローンすることです。これにより、読み取り専用のレガシー コードが新しいグリーンフィールド ターゲット リポジトリから分離され、元のアプリケーションが誤って変更されることがなくなります。

Antigravity ターミナルを開き、次の設定コマンドを実行します。

git clone https://github.com/GoogleCloudPlatform/devrel-demos.git
cd devrel-demos/other/modernizing-expressjs

クローン作成したら、Antigravity IDE エクスプローラで modernizing-expressjs フォルダを直接開きます。次のような分離されたレイアウトが表示されます。

/modernizing-expressjs/
├── .agents/            # Skills metadata and checklists
│   └── skills/
├── docs/               # Target directory for reverse-engineered markdown artifacts
├── legacy-app/         # Read-only root of the legacy Express monolith
├── modern-app/         # Greenfield target repository for the Next.js rewrite
├── GEMINI.md           # Project-wide agent constitution
└── README.md           # Companion documentation

モノレポ環境を決定論的に準備して分離する方法を示す簡単な動画をご覧ください。

3. AI エージェントのスキルパックとパターンを設計する

堅牢なエージェント スキルを作成することは、標準的なチャット プロンプトを作成することとは根本的に異なります。スキルパックを作成する場合、基盤となる LLM が自律的に実行するモジュール式のソフトウェアを設計します。エージェントがハルシネーションを起こしたり、「コンテキストウィンドウ税」が発生したりしないように、オープンソースのグリーンフィールド オーケストレーション スキルパックを、簡潔さとプログレッシブ ディスクロージャーという 2 つの譲れない原則に基づいて拡張可能な作成テンプレートとして導入します。

YAML メタデータ ルーティングを使用したプログレッシブ ディスクロージャー

すべてのターゲット ルールを 1 つのモノリシック システム プロンプトにダンプするのではなく、ディレクトリ全体に指示を分散します。すべてのスキル ディレクトリには、YAML ルーティング フロントマター ブロックでラップされた SKILL.md エントリポイントが含まれています。

.agents/skills/orchestrating-greenfield-migration/SKILL.md を開き、ルーター メタデータを確認します。

---
name: orchestrating-greenfield-migration
description: >
  Manages the end-to-end modernization of legacy Express
  monoliths into Next.js architectures. Orchestrates subagents
  for auditing, scaffolding, and verification. Use when starting
  or managing a greenfield rewrite project.
---

プランと実行のパターンをハードコードする

自律型エージェントがドリフトしたり、興味深いレガシー ミドルウェアに気を取られたり、承認されていないデータベースの切り替えを試みたりしないように、指示にプランと実行 のパターンを直接ハードコードして、標準的なオープンエンドの計画をオーバーライドします。

メイン オーケストレーターに埋め込まれたリテラル Markdown チェックリストを確認します。

### Phase 1: The AI audit (reverse engineering)
Dispatch subagents to produce specifications while identifying project-specific test scenarios.

*   [ ] Init `docs/verification/Verification_Plan.md` to create baseline template.
*   [ ] Run `auditing-data-models` -> Append Data Integrity Stress-Tests.
*   [ ] Run `auditing-api-contracts` -> Append API Parity & Edge Case Probes.
*   [ ] Run `auditing-business-logic` -> Append Logic & Authorization Stress-Tests.
*   [ ] Run `auditing-ui-archeology` -> Append Interaction & Layout Targets.

ワークフローをインライン スキル参照を含む明示的なチェックリストとしてフォーマットすることで、エージェントはこの正確なロードマップをタスクプランにコピーし、「実行専用」モードにロックします。このモードでは、必要に応じてボックスを体系的にチェックし、高度に専門化されたサブエージェントを呼び出します。

4. フェーズ 1 - レガシー モノリスのリバース エンジニアリング（監査）

メイン オーケストレーション シーケンスをトリガーする準備ができました。最初の主要なフェーズでは、ビジネスルール、データ スキーマ、API ペイロードをレガシー モノリスから抽出し、クリーンな Markdown アーティファクトとして保存します。これにより、10 年分の命令型技術的負債が残ります。

自律型リファクタリング シーケンスをトリガーする

Antigravity エージェント マネージャーのチャットパネルで、次のカスタム スラッシュ コマンドを入力して Enter キーを押します。

/orchestrating-greenfield-migration

ターミナル コンソールを確認します。メイン エージェントがシステム プロンプトを読み取り、リクエストをオーケストレーターのメタデータと照合し、5 フェーズのチェックリストを出力して、専門の「監査」サブエージェントのディスパッチを並行して開始します。

入力/スキル/出力指示コントラクト

フェーズ 1 では、エージェントは次の指示コントラクトにバインドされた厳格なリバース エンジニアリング パイプラインを実行します。

使用される入力: legacy-app/ 内にある読み取り専用のレガシー ソースコード ファイル。

呼び出されるスキル:

スキル

説明

auditing-api-contracts

レガシー ルートをトレースして、正確な JSON レスポンス エンベロープを文書化します。

auditing-data-models

Mongoose スキーマを分解して、関係、必須フィールド、デフォルトを抽出します。

auditing-business-logic

暗黙的な副作用、Passport 認証フロー、ミドルウェア ルールを文書化します。

auditing-ui-archeology

レガシー Pug テンプレートをスキャンして、ハイレベルな「UI インテント」（ナビバー、フォーム）をマッピングします。

生成されるアーティファクト: 高度に構造化された Markdown 仕様が docs/ フォルダに直接生成されます

アーティファクト

説明

docs/API_Contracts.md

このドキュメントでは、レガシー Express アプリケーションのリバース エンジニアリングされた API サーフェス領域について詳しく説明します。このカタログを使用して、モダナイズされた Next.js アプリケーションでルートを再構築する際に厳格なパリティを確保します。

docs/Business_Logic_Rules.md

このドキュメントには、認証（AuthN）、認可（AuthZ）、グローバル ミドルウェア、セッション管理、副作用に関するレガシー Express アプリケーションの検証済み動作、構成、厳格なルールが記録されます。

docs/Data_Models.md

このドキュメントでは、legacy-app/app/models/ のレガシー Mongoose スキーマを包括的に分析し、ネイティブ MongoDB と Zod を使用した型安全な最新のデータアクセス レイヤのブループリントを提供します。

docs/UI_Inventory.md

このドキュメントでは、legacy-app のレガシー Pug ベースのユーザー インターフェースの詳細な分析を行い、modern-app の最新のコンポーネント駆動型 Next.js フロントエンド アーキテクチャのブループリントを示します。

自律型リバース エンジニアリング監査の動作を示すライブターミナルのキャプチャをご覧ください。

5. フェーズ 2 と 3 - TDD ハーネスとグリーンフィールド バックエンド スキャフォールディング

レガシー アプリケーションの監査と文書化が完了すると、メイン オーケストレーターは最新のターゲット バックエンドのスキャフォールディングに進みます。このフェーズでは、ツールキットで最も強力なエージェント型設計パターンである、厳格なテスト駆動開発（TDD）によって駆動されるクローズド ループのリフレクション （自己反省）を紹介します。

リフレクション ループを使用して自己修復コードを駆動する

最新のコードの作成は簡単ですが、完全にコンパイルして厳格な検証制約に合格するには、クローズド ループ評価が必要です。オーケストレーターは、テスト出力をサブエージェントのコンテキスト ウィンドウに直接パイプすることで、これを自律的に処理します。

  1. フェーズ 2（TDD の設定）: オーケストレーターは generating-api-tests サブエージェントを呼び出します。このサブエージェントは docs/API_Contracts.md を読み取り、必要な HTTP ステータス コードと JSON ペイロードをアサートする包括的な Vitest 統合テストスイートを作成します。TDD で想定されるように、これらのテストは最初は失敗します。
  2. フェーズ 3（バックエンド スキャフォールディング）: スキャフォールディング サブエージェントは、最新の Next.js ルート ハンドラと厳格な Zod 検証スキーマの作成を開始します。
  3. 自己修正ループ: 決定論的な Vitest ハーネスが新しいコードを評価して失敗を返した場合（たとえば、想定される 422 検証エラーが 500 を返した場合）、エージェントはクラッシュしません。目的のエラー出力を反映し、ターゲット ルート ハンドラを再度開き、Zod スキーマ ペイロード構造を修正して、テストを再度実行します。終了コード 0 に達するまで自律的に反復処理されます。

入力/スキル/出力指示コントラクト

使用される入力: リバース エンジニアリングされた仕様アーティファクト（docs/API_Contracts.md、docs/Data_Models.md）。

呼び出されるスキル:

スキル

説明

generating-api-tests

失敗する Vitest 統合スイートを生成します。

scaffolding-nextjs-foundation

ベースの Next.js App Router レイアウトを初期化します。

scaffolding-test-foundation

ローカルの Vitest テストランナー環境を構成します。

scaffolding-data-layer

古い Mongoose モデルを MongoDB + Zod スキーマに変換します。

scaffolding-api-routes

Express ルートを Next.js ルート ハンドラとモジュール式のルートガードに再構築します。

生成される出力: 最初の失敗した Vitest スイート、完全に型指定された Zod スキーマ、機能する Next.js ルート ハンドラ、クリーンで合格するテストスイートの実行。

TDD テストハーネスの自動生成を確認します。

ターゲット バックエンドをスキャフォールディングする自己修正リフレクション ループのリアルタイム実行を確認します。

6. フェーズ 4 - 最新のフロントエンド（UI コンポーネント）をスキャフォールディングする

バックエンド検証レイヤが完全に強化され、統合テストに合格すると、メイン オーケストレーターはコンテキストを切り替えて、視覚的なプレゼンテーションをモダナイズします。命令型のサーバーサイド レンダリング テンプレートは破棄され、アクセスしやすくユーティリティファーストなコンポーネント デザイン システムが採用されます。

UI インテントをコンポーザブル ビューに変換する

フロントエンド サブエージェントは、行単位の CSS 変換を試みるのではなく、抽出された「UI インテント」インベントリを読み取り、構造要素を高忠実度の最新の同等物に直接マッピングします。

入力/スキル/出力指示コントラクト

使用される入力: リバース エンジニアリングされたフロントエンド インベントリ アーティファクト (docs/UI_Inventory.md)。

呼び出されるスキル:

スキル

説明

scaffolding-ui-components

UI_Component_Inventory.md アーティファクトを最新の ShadCN + Tailwind コンポーネントと完全にスキャフォールディングされた Next.js ページに変換します。

生成される出力: アクセシビリティの高い ShadCN UI コンポーネントと Tailwind CSS ユーティリティ レイアウトを使用して構築された、プロダクション レディな Next.js フロントエンド ページ。

モダナイズされたフロントエンド ビューレイヤの自律的な生成を確認します。

7. フェーズ 5 - 検証と敵対的監査

リファクタリング パイプラインは、厳格な品質チェックで終了します。メイン オーケストレーターは、静的コード分析からアクティブなランタイム環境テストに移行し、新しいターゲット アプリケーションを積極的に破壊して、レガシー ベースラインとの絶対的な機能パリティを証明しようとします。

2 つのタブテストとブラウザの起動を実行する

検証フェーズでは、Antigravity の統合されたビジュアル機能と DOM 機能を利用して、フォームを手動でクリックしなくても自律的に成功を証明します。

  1. 並列パリティ: auditing-parity サブエージェントは、ローカル ランナーにレガシー Express モノリスとモダナイズされた Next.js アプリケーションの両方を同時に起動するように指示し、同一の視覚的なプレゼンテーションとデータ レンダリングを検証します。
  2. 敵対的なセキュリティ プロービング: オーケストレーターは adversarial-verification サブエージェントを呼び出します。このサブエージェントは Antigravity ブラウザ サブエージェント を起動します。この専門エージェントは、ブラウザを直接操作し、入力への入力、フォームの送信、セキュリティ リグレッション、破損したセッション Cookie、未処理のエッジケースのプロービングを行います。
  3. 監査証跡の生成: ブラウザ サブエージェントは、セッション操作の WebP 動画キャプチャを自動的に記録し、検証可能な "作業証明" として最終的な移行レポートに直接添付します。

入力/スキル/出力指示コントラクト

使用される入力: ローカル ランタイム環境で並行して実行されるレガシー アプリケーションと最新のアプリケーション。

呼び出されるスキル:

スキル

説明

auditing-parity

ランタイムの並列検証チェックを実行します。

adversarial-verification

自動化されたブラウザ操作を使用して、ロジックの欠陥と機能のリグレッションをプローブします。

生成される出力: 記録されたブラウザ セッション動画と組み合わせた包括的な機能パリティ監査証跡。完全な成功を確認します。

自動化されたブラウザ サブエージェントがモダナイズされたアプリケーションを積極的に検証している様子を確認します。

8. 移行後の本番環境の準備と次のステップ

おめでとうございます。高度な自律型エージェント型リファクタリング パイプラインを適切にオーケストレートして、レガシー モノリスをゼロからモダナイズしました。プログレッシブ ディスクロージャー、プランと実行のチェックリスト、自己修復リフレクション ループなど、普遍的で移植性の高いスキルを習得しました。

本番環境へのデプロイの準備

Next.js アプリケーションの検証と監査が完了したら、本番環境への統合に進む準備が整いました。業界標準の次のステップの実装を検討してください。

  • 増分ルーティング: リバース プロキシ（Strangler Fig パターンなど）をデプロイして、レガシー Express アプリから最新のターゲットにトラフィックを段階的にルーティングします。
  • SEO の維持: レガシー Express ルートを Next.js 永続リダイレクト（_redirects.yaml）にマッピングして、既存のドメイン権限を維持します。
  • データ ストリーミング: 静的なデータベース シーディングから、厳格な Zod スキーマを使用してランタイムで安全に検証されるライブの本番環境データ ストリーミングに移行します。
  • オブザーバビリティ: 命令型ロギング ユーティリティを構造化された OpenTelemetry フレームワークに置き換えます。

モダナイゼーションの専門知識を深める

このパイプラインを駆動する基盤となるコードベース、カスタム スキル手順、包括的な理論的根拠の詳細については、親記事をご覧ください。

エージェント型ビルダー コミュニティに参加する

これらの普遍的なリファクタリング パターンとエージェント型パイプラインがお役に立てば幸いです。今後のオープンソース スキルパック、詳細な技術コンテンツ、今後のカンファレンスでの講演については、次のプロフェッショナル チャネルでフォローしてください。

ご意見をお聞かせください

エージェント型オーケストレーションについて最も興味があることは何ですか？

敵対的なブラウザ検証 自律型リファクタリング ループ 拡張可能なスキル アーキテクチャ マルチエージェント オーケストレーション 普遍的な言語非依存性

Google Antigravity をご利用いただきありがとうございます。