はじめに
弊社ではフロントエンドのテスティングツールの社内の標準を Vitest と定めており、標準化チームより Jest to Vitest Migration Guide が公開されました。そこでは公式のマイグレーションドキュメントをベースに、Jest から Vitest に効率的に移行するための方針などが書かれています。
私はこういった「複数のプロジェクトで実行される似通ってはいるが複雑なプロセス」こそ AI の出番だと思い、自身の勉強も兼ねて AI エージェントを作ることにしました。
この記事ではエージェントを作る過程で見えてきた、エージェント開発の勘所とその前後の AI との向き合い方の変化について書きます。
Jest to Vitest Migration Guide の詳しい内容や Claude Code[^claude-code]については詳しく触れません。
この記事で使うエージェントは、与えられた目標に対し、自ら計画を立てて状況に応じて判断し、ツールなどを活用してタスクを実行する自律型の AI システムのことを指します。
今回は社内での利用が最も多い Claude Code の Slash Commands と Subagents でそのシステムを実現したものを "エージェント"と呼びます。
なぜ Jest to Vitest 移行をエージェント化しようと思ったか
Jest to Vitest 移行は、以下のような特徴を持つタスクです。
- 規模が大きい：数百から数千のテストファイルが存在し、全てを手作業で修正するには膨大な時間がかかる
- 反復作業が多い：インポート文の変更や基本的な構文の置き換えなど、パターン化できる作業が多い
- 部分的に複雑：複雑なモックやプラグインなど、プロジェクト固有の実装は個別対応が必要
人力作業の課題と Vibe Coding の限界
世の中では AI 開発において、Vibe Coding から Agentic Coding への移行が注目されています[1][2]。しかし私は依然として Vibe Coding から抜け出せずにいました。
Vibe Coding とは、その場その場で AI に指示を送り、出力を確認してまた指示を送り、対話を重ねながらコーディングやタスクを進めていくスタイルです。
一方で Agentic Coding とは、明確に定義されたタスクをエージェントが自律的に完遂するため、開発者はその結果のみを評価すれば良いという手法です。
元々しっかりと設計してから手を動かすよりも、手を動かしながら考えていく開発スタイルだった私には、Vibe Coding の開発フローが良くも悪くもマッチしていました。AI を使う開発にも慣れてきて個人としての生産性はかなり向上した感覚があります。
しかし個人の生産性をいかに向上させても、チームの生産性を上げることよりも価値は低いです。それどころか私は横断組織に所属しているため、会社全体の生産性向上に寄与しなければなりませんでした。
元々アウトプットや人に影響を与えるといったことが苦手な私は、どのように組織を跨いで影響を与えればいいのか答えが見つからないままでいました。
そのため Jest to Vitest 移行は Agentic Coding を学ぶ良い機会だと考えました。
どのような構成のエージェントを作ったか
アーキテクチャ概要
このエージェントは以下の構成になっています。
- 1つの Slash Command：エージェント全体を統括するコマンド
- 3つの Subagents：計画・実行・検証の役割を持つサブエージェント
各サブエージェントの役割
計画エージェントは全体の計画を作成する役割を持っています。前述の Jest to Vitest Migration Guide を参考にプロジェクトのコードベースを巡回し、Jest から Vitest に置き換えるための計画を作成します。最終的にこの計画を markdown の一時ファイルとして出力し、呼び出し元のコマンドへ情報を渡します。プロジェクトの特性によってどのライブラリをインストールするか、どのファイルを修正対象とするか、移行が完了したことの検証のための観点など、今後の作業の全てをここで計画します。
実行エージェントは計画を元に実行に移します。計画書にはすでにどのファイルをどのように修正するかが指示されているので、このサブエージェントはその計画に則って修正をします。
正確に言うと実行のサブエージェントは依存ライブラリを変更してインポートするものとソースコードを修正するものに分かれています。これらはコンテキストを消費しないように分かれています。
検証エージェントは実行結果を計画書の検証計画に基づいて、ソースコードが正しく修正されたかを検証します。ここでは検証のみを行い、失敗している場合はその内容をコマンドに渡します。検証の観点としては、テストが正しく実行され元々通っていたテストが引き続き通るか、インポート文が正しく変更されているか、構文エラーがないか、設定ファイルが適切に修正されているかなどをチェックします。
コマンドは、これら 3 つのサブエージェントを順番に呼び出します。計画のサブエージェントから受け取った計画書（正確には計画書のファイル名）を以降のサブエージェントに渡すことで、計画通りに作業が実行されるようにしています。
また、検証結果を元に改めて実行をするように指示し、検証が完了するまでそのループを続けるようにしています。これにより、移行の再現性を高くしています。
最後に計画書を削除して完了です。
なぜこの構造になったのか
最初は 1 つのコマンドで完結するものを作りましたが、膨大なソースコードを参照して修正する途中でコンテキストが自動圧縮（compact）されてしまい、元の指示を忘れてしまうことがありました。
そのため、計画・実行・検証というフローに分離し、各段階で必要な情報だけをコンテキストに含めることで、この問題を回避できました。特に計画を markdown ファイルとして保存し、以降のサブエージェントに渡すことで、コンテキストを効率的に管理できました。
どう作り、何が難しかったか
初期実験での失敗
エージェントは公式でも推奨されているように、手作業ではほとんど編集せず Claude Code に全て作ってもらいました。ガイドラインを読み込ませて該当のプロジェクトで Vitest 移行を完了するためのエージェントを作るように指示しました。
しかし、最初のトライでは以下のような問題がありました。
1つのコマンドに全て任せるとコンテキスト圧縮で誤動作： 1 つのコマンドで完結するものが最初に作られましたが、膨大なソースコードを参照して修正する途中でコンテキストが自動圧縮（compact）されてしまい、元の指示を忘れてしまうことがありました。
不適切な修正が行われた事例： 単純な構文の移行で失敗したテストのいくつかで、モックして無理やりテストを通したりテストケースを変更してしまうことがありました。
モック・プラグインを自動変換できないケース： 複雑なモックやプラグインなどプロジェクトの内容に依存するものは、何度エージェントを調整しても成功しませんでした。
調整のポイント
何度かプロジェクト全体をリストアしつつ実践を重ね、以下の調整しました。
計画／実行／検証への分割： 計画、実行、検証のフローで行うようにし、ある程度の品質になるまで調整しました。
計画を Markdown に保存して受け渡す： 計画を作成してコンテキストの消費を抑えることで、エージェントが元の指示を忘れないようにしました。
実行と検証の役割を明確化： 検証結果を元に再実行するループを組み込み、最大 3 回まで試行することで、移行の精度と再現性を高められました。
AI に任せすぎない範囲設定： 8 割の移行が完了すれば成功と考え、残りは人間が対応する前提で設計しました。これらの調整は試行錯誤の中で回避できるようになったものとできなかったものがありました。
どこまで自動化できたのか
このエージェントを使った移行を、テストケースの数が数百以上あるものと、数十程度の 2 つのプロジェクトで実施しました。
どちらのプロジェクトでも8割ほどの移行が完了していました。
単純なインポートの変更やガイドラインにて具体的に指示されている構文の変更などはファイル数が多くても問題なく実施されました。
修正が完了しなかった残りの 2 割は、複雑なモックやプラグインなどプロジェクトの内容に依存するもので、これらは何度エージェントを調整しても成功しなかったため、手動で修正しました。
今回のエージェント開発で得られた実践知
エージェント開発を通じて、エージェントには「計画を外部化する層」が必要だと学びました。
単一のコマンドで全てを実行しようとすると、膨大なソースコードを参照する途中でコンテキストが自動圧縮（compact）され、元の指示を忘れてしまうことがありました。
特に計画を markdown ファイルとして保存し、以降のサブエージェントに渡すことで、コンテキストを効率的に管理できました。これは Agentic Coding におけるコンテキスト設計の本質的な考え方だと理解しています。
また、どこまでを AI に任せて、どこからを人間が見るかの境界決めが大事でした。
AI 全般に言えますが、エージェントは従来の AI に比べて自律的に大きいタスクをこなしてくれる分、全てを任せてしまっていいのではと勘違いしてしまいます。しかしいくら工夫を重ねて品質を上げても、ハルシネーションを避けることは不可能です。
大事なのはエージェントに任せる作業は大きすぎないようにすることと、人間がチェックする前提で大胆に実行することです。
今回のエージェントでも 8 割の移行が完了すれば成功と考え、残りは人間が対応する前提で設計しました。この割り切りが、実用的なエージェント開発には重要です。
今後の展開と同様のエージェント化はどこに応用できそうか
エージェントはこれまで Vibe Coding でその場その場で実施されていた作業を、プロジェクトを跨いだ環境でも再現してくれます。特に Jest to Vitest のような目的がはっきりとしているが規模が膨大なタスクは、エージェントを利用することで大きく時間を削減できることがわかりました。
また、個人の作業を再利用可能なエージェントという形で残せることが、Agentic Coding の大きな価値だと実感しています。そこで最近は、普段 AI を使って行っているタスク全てでエージェントを作るようにしています。単発の実装でも、プロンプトだけで終わらせるのではなく一旦エージェントを作ってもらい、そのエージェントを使って実装をします。うまく作業を完了できない場合はエージェントを調整して再度実行します。
もちろん二度と利用されないエージェントもできますが、まずは作業のどこをエージェントにするかの勘所を掴むために試しています。
今後エージェントが増えていくことで、組織全体でナレッジを共有し、生産性を向上させていけると考えています。現状は個人での PoC ですが、今後は組織全体での展開を目指していきます。
まとめ
この記事では、Jest to Vitest Migration エージェントを作成した経験から、AI エージェント開発の勘所について紹介しました。
Vibe Coding から Agentic Coding への移行は、個人の生産性向上から、再利用可能な形でのナレッジ共有へとシフトすることを意味しています。エージェントを作ることで、これまで個人の暗黙知として埋もれていた作業プロセスが明示化され、チーム全体で共有できるようになります。
皆さんもぜひ、日々の作業の中でエージェント化できるものはないか、探してみてください。
Discussion