Playwright移行を自律化。Claude Codeで実現するマルチエージェント設計

【QAチーム ブログリレー5日目】の記事です。

こんにちは。エンジニアリンググループ QAチームの須賀です。 最近エムスリーに復帰しました。 私は2月1日に入社してからQAエンジニアも使い放題のClaude Codeを用いてmabl（ノーコードのE2Eテストツール）の自動テストをPlaywrightにリプレースしています。 AIエージェントを用いた開発は未経験だったため、最初は期待するコードをなかなか生成できず試行錯誤の連続でした。しかし、最近では人の介入なしで期待するコードが生成できることも増えてきました。 試行錯誤の結果、AIエージェントの活用において重要だったのは、実は『人間同士が円滑に仕事をするためのマネジメント方法』を適用することだと気づきました。

本記事では、次の参考書籍の知見をベースにしつつ、実際のリプレース業務において試行錯誤して私が構築した、6つのサブエージェントを活用したワークフロー設計の実例を紹介します。

参考書籍

gihyo.jp

設計の全体像 — .claudeディレクトリとCLAUDE.md

Claude Codeでは、リポジトリのルートに置くCLAUDE.mdファイルと.claude/ディレクトリでAIエージェントの振る舞いをカスタマイズできます。

AIエージェントに期待する成果物を生成させるには、AIエージェントの行動を細かく定義したり、成果物を別のツールやエージェントでチェックしたり、コンテキスト量を減らしたりする必要があります。

そこで、私は、.claudeディレクトリとCLAUDE.mdの設計を次のようにしました。

要素	役割・定義	詳細
CLAUDE.md	インデックス（目次）	AIエージェントが目的の情報に辿り着くためのガイド。詳細情報は別ドキュメントに委ねる。
commands	抽象的なワークフロー	作業の種類に応じた工程と利用エージェントを定義。現在はE2Eテストのリプレース作業のみ。
agents	サブエージェントの定義	エージェントの役割・目的、および特定の工程における具体的なワークフローを管理。
skills	具体的な手順・ナレッジ	ルール、Tips、実作業レベルの手順など、各エージェントが参照すべき情報を集約。
hook(settings.json)	自動チェック（静的解析）	コーディング規約等の即座なチェック。サブエージェントの負担軽減と手戻り防止。

1つのスラッシュコマンドを実行する親エージェントが6つのサブエージェントをオーケストレーションし、各エージェントが必要に応じてスキルを参照する形になっています。

なお、各ファイルはClaude Codeに設計方針などを指示して作成してもらいました。

commands：自律的なワークフローの定義

E2Eテストのリプレース作業について、計画から実装完了までのワークフローを定義しました。 いつ誰が何をするかといった「作業の進め方やルール」「AIエージェントに作業を任せる範囲」を決めることで、AIエージェントが迷わずに安定して作業できるようになります。

ワークフローの流れとcommandsに関する意図や工夫点などをいくつかご紹介します。

ワークフローの流れ

ワークフローの大まかな流れは次の通りです。

1. ワークフローに沿ったタスクリストを作成
2. mabl CLIを用いてmablのテストケースをPlaywrightのファイルにエクスポート
   • このファイルをテスト仕様書作成やテストコード実装フェーズで参照する
3. テスト仕様書（テストコードのスケルトン）を作成
   1. spec-writer-agentによるスケルトンの作成（または、修正）
   2. spec-reviewer-agentによるレビュー → spec-writer-agentによる修正のループ
      • 指摘がなくなるか、5回実施するまで繰り返す
   3. 人によるスケルトンのレビュー
      • 指摘がある場合は3-aに戻る
4. テストコードの実装
   1. test-writer-agentによるテストコードの実装（または、修正）
      • コード編集のたびにhooksでESLint自動実行 → Lint違反はAIが即座に自己修正
   2. test-runner-agentによるテスト実行 → test-writer-agentによる修正のループ
      • テスト実行が成功するか、AIが自力で解決できない問題が発生するか、10回実施するまで繰り返す
   3. code-reviewer-agentによるコードレビュー → test-writer-agentによる修正 → test-runner-agentによるテスト実行のループ
      • 指摘がなくなるか、5回実施するまで繰り返す
   4. 人によるコードレビュー
      • 指摘がある場合、4-aに戻る
5. 作業中に発生した課題の振り返り

---

図で表すと、次のようになります。

E2Eテストリプレースのワークフロー

ワークフローに沿ったタスクリストの作成・更新

最初に上記ワークフローに沿ったタスクリストを作成し、各工程が終わった後にAIエージェントにタスクリストを更新させます。 タスクリストを更新する際は、作業の開始・終了時刻だけでなく、作業時に発生した問題点も記載します。

タスクリストは次のような効果が期待できます。

• コンテキスト量の上限を超えてコンテキストの圧縮が行われてもタスクの進捗を追跡できるようにする
• 最後に課題を振り返りやすくなる
  • タスクリストを残さない場合、人が修正を依頼した内容しか振り返り対象にできません。一方、タスクリストを残すと、AIだけで作業は完結したが時間がかかってしまった課題なども振り返り対象にできることが多いです

テスト仕様書の作成と人によるレビュー

テスト手順をAIエージェントが実装する前に、人がレビューして認識を合わせます

理由は、現状ではアプリケーションの仕様や画面遷移に関する情報が不足しており、AIエージェントがテスト手順の正しさを判断するのが難しいからです。そのため、仮に誤ったテスト手順で実装してしまうと、AIエージェントが実行エラーの原因を自力で解消できず、実装に時間がかかってしまいます。

ただし、既存のテストコードをリプレースするプロジェクトという特性もあり、最近はこの工程で人から指摘が入ることは多くありません。 将来的には、リプレースプロジェクトにおいてこの工程は不要になると考えています。

AIによる実装、テスト実行、コードレビューのループ

AIエージェントによる実装、テスト実行、レビューのループを繰り返すことで、人がコードレビューを実施する前のコードの完成度を向上させます。

ただし、テスト実行時のエラー原因はテスト手順やテストデータの不備などAIエージェントが自力で解決できない原因の場合もあります。 そのため、無限ループにならないようループを抜ける条件を定義しておきます。

作業中に発生した課題の振り返り

.claudeの各ファイルを継続的に改善するために、作業中に発生した課題を振り返ります。 ただし、AIエージェントに.claudeの各ファイルを自動で修正させていません。 なぜなら、AIエージェントによる課題分析がまだ浅く、本質的ではない改善案を提案されることが多いからです。例えば、ループを8回繰り返してしまった場合に「ループの上限を増やす」という提案をされますが、本来はループ回数を減らすための根本的な改善策を提案すべきです。

最終的には、振り返り用のスキルを改善するなどして、自動で.claudeの各ファイルが改善される仕組みを作りたいと考えています。

agents：役割の分離と責任の明確化

私が作成したエージェントは次の通りです。

エージェント名	役割・担当業務
mabl-export-agent	mablテストをPlaywright形式にエクスポートする。
spec-writer-agent	エクスポート結果を基に、テスト仕様書（スケルトン）を作成する。
spec-reviewer-agent	テスト仕様書がmablテストの内容を忠実に再現できているかレビューする。
test-writer-agent	テスト仕様書に基づき、Page Objectパターンでテストコードを実装する。
test-runner-agent	テストの実行および、発生したエラーを分析する。
code-reviewer-agent	設計の妥当性や保守性の観点から、実装されたコードをレビューする。

agentsに関する意図や工夫点などをいくつかご紹介します。

各工程でエージェントを分ける

各工程でエージェントを分ける理由は、「情報を整理」してAIエージェントに必要なコンテキスト量を減らすこと、「役割を分けて視点の違いを活かす」ことにあります。

1つのエージェントで全ての作業をするとすぐにコンテキスト量の上限を超えてしまい、指示内容を忘れるといったことが発生します。 そのため、各工程でエージェントを分けて作業に必要なコンテキスト量を減らします。

また、成果物を生成するエージェントと成果物をレビューするエージェントを分けることで、成果物の品質を保ちやすくなります。

例えば、test-writer-agentはテストコードの実行成功を重視し、コーディング規約への配慮を怠ることがあります（例えば、ハードコードされた待機時間を入れる）。 一方、code-reviewer-agentはコードの品質を守ることを重視するため、このような品質の課題を適切にチェックできます。

エージェントの作業の流れを具体的に書く

「作業の進め方」をより具体的に示すことで、エージェントの振る舞いを安定させることができます。

例えば、test-writer-agent.mdファイルに「既存のページオブジェクトのファイルがあれば再利用して」とだけ書いても、既存のものを使わず新規作成することがあります。 Claude Codeに原因を質問すると、「既存のページオブジェクトのファイルを探す手順を示していないので、探し方がセッションによって異なるからではないか」という趣旨の回答が得られました。

そのため、既存のページオブジェクトのファイルを探す手順を次のように具体的に定義する必要があります（agentsのファイルに記載するか、このような記載のあるskillを参照させます）。

• ページオブジェクトの一覧と説明が記載されたファイルを参照する
• 今回実装するテストに関連するキーワードでgrep検索する
• 類似の画面・機能をテストしているテストコードのファイルを参照し、利用しているページオブジェクトのファイルを確認する

やらないことを定義しておく

AIエージェントに任せる作業の範囲を具体化するため、やらないことも定義しておきます。

やらないことを定義しない場合、テスト実行とエラー原因の分析をするだけのエージェントなのにコードを修正してしまう、テスト仕様書のレビューで指摘しなくても良い観点を指摘してしまう、といったことが発生する場合があります。

そのため、エージェントの振る舞いを安定させるためには、やらないことも定義しておく必要があります。

前者（test-runner-agent）については、エージェント定義でwrite権限自体を外しておきます。Claude Codeのサブエージェント定義では、利用可能なツール（Read、Write、Bashなど）をエージェントごとに制限でき、「やらないこと」をルールだけでなく権限レベルで強制できます。

後者（spec-reviewer-agent）については、リプレースプロジェクトのためテスト観点の網羅性はレビュー対象外とする、というように記載します。

skills：再利用可能な知見の集約

複数エージェントで利用する知見や、情報量の多い知見などはスキルとして切り出しました。 スキルは作業に必要な時だけ全ての情報を参照するため、各作業で「必要な情報を整理する」ことでAIエージェントのコンテキスト量を減らせます。

作成したskillsは次の通りです。

項目名	定義・内容
Given-When-Then記法ガイド	テスト仕様書とテストコードで共通して使用する記述形式の標準。
Page Object重複チェック	Page Objectを新規作成する前に、既存のPage Objectが存在しないかを確認する手順。
Playwrightベストプラクティス	テストコードの安定性を高めるためのコーディング規約。
特殊コンポーネント実装ガイド	select2など、特殊なUIコンポーネントの操作方法。
エラー分析フロー	テスト失敗時に「画面遷移→ロケーター」の順で体系的に原因を分析する手順。
ワークフロー改善提案レポート	タスク完了後に実施する、振り返りレポートの生成手順。

本記事では個人的にユニークだと思うSkillについてのみ簡単に触れておきます。

エラー分析フローについて

Claude CodeはE2Eテストを実行してエラーが発生した時に、実画面のDOMや実行時の動画を参照せずに推測で誤ったコードを修正する、ネットワークのせいにしてタイムアウト時間を伸ばすことが頻発しました。 そのため、エラー分析フローを追加し、次のような手順で原因を分析するように定義しています。

1. エラー箇所の基本情報を収集する
   • エラー箇所（ファイル名・行番号）、エラーメッセージ全文、エラー発生時のURL、スクリーンショット、トレースファイルを集める
2. エラー発生時に期待している画面に遷移しているかどうかを確認する
   • エラー発生時のURLと期待するURLを比較し、スクリーンショットでも画面内容を確認
3. 期待している画面に遷移していた場合、ロケーターに問題があると仮定して分析
   • ロケーターの正しさをエクスポートしたファイルやエラー発生時のログなどを参照して確認する
   • ロケーターが正しい場合は、タイミング・動的要素の問題（表示待ち、Ajax完了待ち、アニメーション、要素の重なりなど）を分析
4. 期待している画面に遷移していなかった場合、テスト手順に問題があると仮定して分析
   • ログイン状態の喪失、クリック失敗、バリデーションエラー、権限不足など

おまけ：Claude Codeに私のリポジトリを採点してもらった

過去に次のようなプロンプトで何度かClaude Codeに採点をしてもらいました。 いくつか参考になる指摘も含まれている印象なので、皆さんも活用してみてください。

このリポジトリのCLAUDE.md, .claudeフォルダの内容などを確認し、Claude Codeの活用方法に関して100点満点で採点してください。

総合スコア: 92点 / 100点

評価項目	配点	得点	備考
CLAUDE.md の設計	20	18	段階的開示が徹底、やや情報量が多い
サブエージェント定義	20	19	6エージェントの役割分離・連携設計が秀逸
スキル定義	20	17	再利用設計は優秀、読み込み指示に改善余地
スラッシュコマンド / ワークフロー	20	19	自律実行+承認ゲートの設計が高度
Hooks設定	10	8	ESLint自動実行あり、Prettier未対応
ドキュメント体系 / コンテキスト管理	10	11	永続/一時の分離、自己改善サイクルでボーナス

※ ドキュメント体系は10点満点ですが、ボーナスで11点をつけてもらいました

おわりに

Claude Codeを使ってみて感じたのは、AIエージェントをうまく活用するための工夫は、「人が円滑に仕事をするための工夫」とあまり変わらないということです。

具体的には、次の4点を意識することが重要だと気づきました。

• 進め方やルールを決める： 作業手順や成果物の品質を定義して、誰が作業しても安定した成果を出せるようにする
  • （commandsでのワークフローの定義など）
• 情報を整理する： 作業のノイズを減らし、目の前のタスクに集中できる状況を作る
  • （agents の細分化、skills へのナレッジ集約など）
• 役割を分けて視点の違いを活かす： 作業担当者が持つ心理を理解し、必要に応じて第三者によるレビューなどを実施する
  • （実装担当とレビュー担当の agents 分離など）
• 任せる範囲をはっきりさせる： 自分で判断していいこと、他の人に確認が必要なことの境界を伝えて可能な限り自律的に行動してもらう
  • （agents の権限設定や「やらないこと」の定義など）

このように考えると、これまで現場で円滑に仕事をするために試行錯誤してきた人は、AIエージェントも上手く使いこなせるのではないかと思います。

AIエージェントを特別な技術だと思わずに、ぜひ一度触ってみてください。

We are Hiring!

エムスリーでは、Claude Codeを使い倒したいQAエンジニアを絶賛募集しています！ 少しでも興味をお持ちでしたら、ぜひカジュアル面談などでお話しましょう！

jobs.m3.com