Agentic Engineering と Autonomous Engineering を使い、400万行のレガシーシステムへ3週間で50万行を追加した方法を紹介します。
これは新規プロジェクトではない
今年初め、5人のチームが Qoder を使って7日間で QoderWork をリリースした事例を公開しました。従来なら20人のエンジニアが数週間かける仕事です。
その事例はゼロから1を作るプロジェクトでした。クリーンなコードベース、自分たちのルールとアーキテクチャがあり、AI は過去の負債がない白紙の上へコードを書きました。
この記事は正反対の事例です。今回 AI が向き合ったのは白紙ではなく、複数年、複数リポジトリ、数百万行にわたる本番システムでした。
アップグレード対象は Qoder 自身です。Qoder は実際に稼働する複雑なシステムです。フロントエンドは VS Code IDE 拡張、バックエンドは Agent のオーケストレーション、ナレッジエンジン、複数モデルの呼び出しを処理する Go サービスです。フロントエンドとバックエンドは別のリポジトリにあり、合計約400万行です。過去数年のアーキテクチャ判断がコード全体に分散し、モジュール間の暗黙的な依存関係は完全には文書化されていません。大規模な変更は連鎖反応を引き起こします。
このシステムへ、Qoder V1.0 となる Quest の全面刷新、50万行の新機能モジュールを追加する必要がありました。
- 再設計された独立 Quest ビュー：タスクを割り当てるように AI を指揮する、全面的に刷新された操作モデル
- 完全に刷新された Editor：コーディング体験の体系的なアップグレード
- ナレッジエンジン：コードを知識へ変換し、会話から Memory を抽出し、使うほど賢くなる Agent
- 複数ワークスペース、複数タスクの並列処理：プロジェクト横断の協調と複数タスクの並行デリバリー
- Experts モードの協調とカスタム Expert：並列分業と柔軟な設定
まず基盤を作る：AI に400万行を本当に読ませる
AI をレガシーシステムへ導入するときの最初の障害は、AI の知能が足りないことではなく、そのシステムで過去に何が起きたのかを AI が知らないことです。
LLM のコンテキストウィンドウには上限があり、400万行をすべて詰め込むことはできません。仮に可能でも、どの行が重要なアーキテクチャ規約で、どれが納期のために作られた歴史的な妥協で、リファクタリングできそうなインターフェースに実は多数の呼び出し元が依存しているか、AI は判断できません。
レガシーシステムを知らない AI が書く新しいコードは、異物のようになります。スタイルが一貫せず、インターフェースに互換性がなく、文書化されていないルールを静かに破り、統合時に問題が爆発します。
そこで、コードを1行も書く前に AI の認知インフラを構築しました。全3層です。最初の2層は Qoder の製品機能で、Repo Wiki がマクロなアーキテクチャを示し、コードナレッジグラフが正確な呼び出し関係を示します。3層目はエンジニアリング規律で追加しました。主要な変更の Spec と意思決定の記録をリポジトリへ保存し、AI が現在の状態だけでなく、なぜその状態になったのかも追跡できるようにします。Qoder で Qoder を開発することで、3層すべてを完全に構築できました。
第1層：Repo Wiki（Qoder 組み込み）
コードから自動生成され、コード変更とともに更新されるリポジトリレベルの文書です。プロジェクト全体のアーキテクチャ、モジュール境界、中核データフロー、モジュール横断の参照グラフを網羅します。400万行に分散する構造関係を、最初から最後まで読める1つのプロジェクト文書へ統合します。コードは個々のファイルの役割を示せますが、システム全体の構成は示せません。Repo Wiki がその全体像を補います。
Repo Wiki は AI のためのプロジェクト地図です。新しい AI Agent は、ファイルを1つずつ調べて構造を再構築する必要がありません。地図を読めば、モジュールの分割、依存関係の流れ、重要な経路をすぐに把握できます。
第2層：コードナレッジグラフ（Qoder 組み込み）
静的解析と AI による理解を組み合わせ、コードベース全体を構造化してモデル化します。モジュール依存関係、インターフェース契約、データフロー、主要データ構造の読み書き経路を含みます。単純なコールグラフではなく、検索可能なナレッジベースです。
新しいコードを生成するとき、AI は「現在このインターフェースを呼んでいるのは誰か」「このデータ構造はどこで変更されるか」「新しい Quest ビューがこのコンポーネントを再利用すると、既存のどの機能へ影響するか」をリアルタイムに照会できます。
Repo Wiki はプロジェクトの大まかな形を示し、ナレッジグラフは各インターフェースの正確な呼び出し状況を調べさせます。粗い視点と細かい視点を Qoder が提供します。
第3層：過去の Spec アーカイブ（エンジニアリング実践）
最初の2層は現在のシステムの姿を AI に示します。しかし、なぜ現在のアーキテクチャへ進化したかという層が不足します。特定のインターフェースを廃止した理由、一見冗長な互換処理がどの本番障害に対応したものかといった判断の経緯は、当事者の記憶だけに残りがちです。その人が離れると経緯も失われ、次のリファクタリングでコードから意図を逆算し、同じ問題を繰り返します。
この層は製品機能だけでは提供できず、エンジニアリング規律で蓄積する必要があります。主要な変更の Spec と意思決定の文章をリポジトリへ保存します。AI がバグを修正したり機能を追加したりするとき、現在のコードだけでなく、なぜこの形になったのかまで調べられます。リポジトリは現在のコードのスナップショットから、検索可能なエンジニアリングアーカイブへ変わります。
2層の製品機能と1層のエンジニアリング実践が基盤です。いずれかを省くと、AI は砂上の楼閣を築くことになります。
Ultra Spec：コードを書く前に仕様を最後まで書く
基盤を整えた後も、すぐにコードを書き始めませんでした。QoderWork の短期開発でも最初に行ったのは「コードではなく Spec を書く」ことでした。レガシーシステムでは、この原則をさらに厳格に適用します。AI がコード生成を始めると、方向を修正するコストが急増するからです。この段階を Ultra Spec と呼びます。
通常の Spec は機能の概要を説明します。Ultra Spec は、その機能のあらゆる側面を、AI が直接実装できる精度で記述し、手戻りを引き起こす問題を事前に明らかにします。固定の項目として、機能目標、I/O 契約、業務ルール、エッジケース、セキュリティ境界、テスト計画を含みます。すべて機械可読である必要があります。I/O は文章ではなく JSON Schema で記述し、すべての業務ルールを具体的な入力と出力へ対応させ、セキュリティ境界を「必ず行う」「先に確認する」「禁止」の3段階へ分けます。
レガシーシステムでは、各項目に「レガシーの視点」も必要です。機能目標には影響を受ける既存モジュールを記載します。I/O 契約は既存インターフェースに合わせ、前方互換性を明示します。業務ルールにはレガシーシステムの暗黙的な規約を記載し、AI に推測させません。エッジケースは過去の不正データを含めます。セキュリティ境界には変更禁止領域を記載します。テスト計画には既存機能の回帰テストを含めます。この視点がなければ、AI の成果物は異物になります。
ナレッジエンジンの Spec は、「会話から Memory を抽出する」という1文ではありません。抽出対象の会話、抽出のタイミング、Memory の保存・検索構造、既存コードインデックスとのインターフェース契約、Memory Store が大きくなりすぎた場合の縮退戦略、異なるワークスペース間の Memory 分離ルールを正確に定義します。すべての行に具体的な I/O があり、「状況による」は認めません。
Spec の完成は終点ではありません。その後、複数 Agent による相互レビューへ進みます。異なる観点のサブ Agent が同じ Spec を独立して監査します。アーキテクト Agent はモジュール境界とインターフェース設計を確認し、セキュリティ Agent は権限の穴とデータ漏えいを探し、パフォーマンス Agent は低速クエリと高頻度呼び出しのボトルネックを予測し、ナレッジグラフを利用するレガシーシステム Agent は既存コードとの互換性を確認します。その後、独立した検証 Agent が指摘された問題を逆算し、ハルシネーションによる誤検出を除外します。SLO 定義と不可逆操作に関わる部分を中心に、最後は人間が承認します。
Ultra Spec に使う時間には大きなレバレッジがあります。ここで1日使えば、後工程のデバッグと手戻りを数日減らせます。
Experts モード：Spec を並列エンジニアリングへ変える
Ultra Spec はモジュールの要件を、依存関係が明確な構造化計画へ分解します。しかしデリバリーまでにはまだ不足があります。ナレッジエンジンや複数ワークスペースの並列処理は、フロントエンド IDE 拡張、Go バックエンド、Agent オーケストレーション、モデル呼び出しチェーンにまたがり、変更量は数千〜数万行です。1つの Agent がエンドツーエンドで処理すると、Ultra Spec が特定した並列分岐が再び直列化されます。長いコンテキストでは注意が薄まり、前半で決めた規約が後半で静かに逸脱します。以前の Qoder では、Agent が終盤に開始時の内容を忘れることがありました。
Experts モードはこの問題を解決します。Team Lead と複数の専門 Agent で構成されます。Team Lead はコードを書かず、Ultra Spec のタスクリストを読み、依存関係を特定し、DAG の順序でバックエンド、フロントエンド、テスト、レビュー、調査の専門 Agent へ作業を割り当てます。各 Agent は独立したコンテキストで動くため、互いの情報を押し出しません。「複数の Agent ウィンドウを同時に開く」だけの場合と異なり、協調機能があります。Ultra Spec が特定した DAG を直接実行計画へ変換し、フロントエンドとバックエンドを同時に進めます。暗号方式の選択や、互換戦略を縮退させるか明示的に失敗させるかなど、実行中に曖昧な選択肢が生じた場合、Team Lead は AI に黙って推測させず、人間の判断を得てから割り当てます。
すべての専門 Agent に同じ最上位モデルを強制しません。調査や初期設定などの軽量な役割は、安価で高速なモデルを使います。アーキテクチャ上重要なレビューや複雑なリファクタリングには、フラッグシップモデルを使います。重要経路の知能水準を下げず、すべてにフラッグシップモデルを使う場合の2分の1から5分の1のコストに抑えられます。3週間で数百から数千のサブタスクを実行しました。すべてに最も高価なモデルを使えば予算を超え、すべてに最も安いモデルを使えば重要箇所の品質を守れません。異種モデルのスケジューリングが、この予算曲線に適合します。
Experts モードはチームが学んだことも保持します。各専門 Agent は Expert Skill（特定モジュールのテスト環境の起動方法、特定インターフェースの過去の注意点など）を蓄積します。チームレベルでは Team Skill（タスクの種類ごとに最適な割り当てパターンなど）を蓄積します。同様の作業が次に来たとき、この経験をそのまま利用できます。
Ultra Review：AI が書いたコードの細部を明らかにする
新しいボトルネックがすぐに現れました。AI のコード生成速度が、人間のレビュー速度を大きく上回ることです。
Qoder は、ナレッジエンジン、複数ワークスペースの並列処理、Experts モードの協調など、多数の Quest を同時に進めます。各モジュールが1日に数千行を生成する可能性があります。レビューが直列のままでは、パイプライン全体のボトルネックとなり、AI の速度向上が相殺されます。
そこで Ultra Review を導入し、コードレビューを単一スレッドから複数 Agent の並列処理へ変えました。
すべての PR を複数 Agent が並行してレビューします。コード内の異なる位置から、異なる経路とコンテキストの読み込み順で確認を始めます。これは LLM のコンテキストウィンドウの偏りを抑えるためです。1つの Agent が上から下まで読むと、後半で注意が薄れ、問題を見逃しやすくなります。並列レビュー後に検証と重複排除を行い、ハルシネーションによる誤検出を除外し、複数 Agent が指摘した同じ問題を統合します。
レビューは、正確性、セキュリティ、性能、アーキテクチャの一貫性、保守性に集中します。このプロジェクトでは特にアーキテクチャの一貫性が重要です。50万行の新規コードがレガシーシステムのアーキテクチャスタイルから逸脱すると、技術的負債は急増します。AI が生成したすべてのコードについて、命名が既存規約に一致するか、階層構造が既存モジュールと一致するか、既存の抽象化レイヤーを飛び越えて内部を直接操作していないかを確認します。
Ultra Review には1つのルールがあります。ロジックの誤りを追い、スタイルは無視します。スタイルは linter と formatter に任せ、AI のレビュー資源は本当に重要な部分へ集中させます。
Computer Use 検証：AI に目と手を与える
コードを書き、レビューを通過した後も、機能が実際に動作するか検証する必要があります。
従来の自動テストには構造的な問題があります。テストスクリプトの作成自体に多くの作業が必要で、通常は正常系だけを対象にし、エッジケースは別途作成し、保守コストはコード量に比例して増えます。
Computer Use はこの前提を変えます。
Qoder はローカル開発環境を直接操作します。スクリーンショットを取得し、座標を特定し、キーボードとマウスを操作して、人間のように作業します。テストスクリプトを書く必要はありません。検証したい動作を説明すれば、AI が次を実行します。
- IDE を起動してコードの状態を確認
- プロジェクトを実行し、サービスの起動を待機
- ブラウザーまたは IDE の画面を開き、業務フロー全体を実行
- Spec で定義された期待結果と照合
- 空の入力、権限境界、同時実行、レガシーデータ互換性などのエッジケースを確認
Nightly Auto-Heal：人間が眠っている間に機械を働かせる
ここで方法論の形が変わります。これまでは人間をループ内に置き、AI と協働していました。これが Agentic Engineering です。Nightly Auto-Heal は人間をループから外し、発見、修正、検証のサイクルを機械だけで実行します。ここから Autonomous Engineering が始まります。
検証、手動テスト、CI 失敗、本番ログのアラートから生じた Issue は、すべて1つの処理キューへ入ります。
チームが作業を終えると、Nightly Auto-Heal が自動的に起動します。
3週間後
3週間。新規コード50万行。99%を AI が生成しました。
独立 Quest ビュー、ナレッジエンジン、複数ワークスペースの並列処理、Experts モードの協調がすべて Qoder V1.0 に入り、ユーザーへ提供されました。
しかし、この記事で本当に伝えたいのは数字ではありません。
数字の背後では、2つの方法論がエンドツーエンドで連携しています。人間の監督の下で AI が高品質に協働する Agentic Engineering と、人間が作業を終えた後も機械がループを継続する Autonomous Engineering です。
レガシーな巨大システムと新規プロジェクトの違いは、認知負荷です。新規プロジェクトでは AI が自由に生成できます。レガシーシステムでは、AI がこのシステムで何が起き、何が合意され、どこに触れてはいけないかを先に学ぶ必要があります。
この方法論の5層は、それぞれ異なる機能を担います。
| 層 | ツール | 機能 |
|---|---|---|
| 基盤 | Repo Wiki + コードナレッジグラフ + 過去の Spec | 400万行のレガシーコードについて、現在の状態と進化の両方を AI に理解させる |
| レバレッジ | Ultra Spec + 複数 Agent の相互レビュー | コードを書く前に手戻りの原因となる問題を明らかにする |
| 実行 | Experts モード（Team Lead + 専門 Agent + エンジニアリングナレッジエンジン） | Spec の依存関係グラフを並列のエンジニアリングデリバリーへ変える |
| ガードレール | Ultra Review（複数 Agent による並列処理） | AI の生成速度に追随し、コードの細部にある問題を検出する |
| フライホイール | Computer Use 検証 + Nightly Auto-Heal | 発見、修正、検証のループを自律サイクルとして閉じる |