こんにちは。エンジニアリンググループ QA （Quality Assurance） チームの津向です。 2月に入り、暖かくなってきたのでBBQをしたのですが、ピンポイントで降雪になり、雪の中で肉を焼くという稀な経験をしてきました。 後日、元プロテニス（現スポーツキャスター）の方が国内不在と知りました。
そんなわけでQAチームブログリレー2日目になります。
- はじめに
- 1. エージェントの２層構造
- 2. 標準化を担う生成エージェント
- 3. デバッグエージェントの独立化
- 4. 2種類のレビューエージェント
- 5. AI+ツールでレビュー
- おわりに
- We're Hiring!
はじめに
以前からPlaywrightへの移行は検討されていましたが、工数や学習コストを考えるとなかなか進められずにいました。 そんな中、QA EngもClaude Codeが使い放題になったことを機に、mablからの移行を開始しました。
開始当初は専用のClaude Agentは作成せず、そのまま移行作業を行なっていました。 次々に生成されるコードを眺めて「このClaudeすごいよ、さすがClaude Chatのお兄さん！」と生温かく見守っていたのですが、次々に課題が出てきました。
- コード規約が途中からスルーされていく
- 既存資産を再利用せずに1から作る
- 移行元のアサーションがスキップされる
- 大量に作成されるのでレビューが大変
- AIにレビュー任せても、本当にレビューできているのか不確実
- 人によって、手順が異なるので成果物も微妙に異なる
など様々でした。
そこでPlaywright移行に特化したClaude Agentを作成することで解決を図りました。 今回はこのClaude Agent（以降はエージェントと記載）についての記事になります。
上記の様々な課題は下記方針に基づくエージェントの作成により、課題を解決できました。
- 2層構造：全体の流れを制御する「オーケストレーター」と、各工程担当である「専門エージェント」の分離
- ダブルチェック検証：技術品質と仕様完全性を別々のエージェントで検証
- AI+ツール検証：AIの文脈判断とツールの機械的チェックを組み合わせた検証
1. エージェントの２層構造
単一の巨大なエージェントですべてをこなそうとすると、ルールが徹底されない、見落とし発生する、メンテナンス性が悪い、などデメリットが多く発生します。そのため、工程で役割を分けることで、デメリットを解消し精度を高めています。
- オーケストレーター層：全体の進捗管理と、次にどの方針で進むべきかの判断に特化。
- 専門エージェント層：コード生成、デバッグ、品質レビュー、仕様レビューといった特定のタスクの実行に特化。
専門エージェントの役割分担
オーケストレーターの指揮下で働く、4つの専門エージェントの役割は次の通りです。
| エージェント名 | 担当フェーズ | 主な役割 |
|---|---|---|
| playwright-code-generator | 生成 | mablの原本や仕様書を読み込み、Page Objectモデルに基づいたコードを作成。 |
| playwright-debug-fix-engine | デバッグ | テスト失敗時に起動。ブラウザのライブ操作と証拠収集を行い、論理的に修正。 |
| playwright-code-quality-reviewer | 品質検証 | コードがプロジェクト規約や技術的なベストプラクティスに沿っているかを査読。 |
| playwright-spec-reviewer | 仕様検証 | 生成されたコードが、原本の要求事項を100%満たしているか「実装漏れ」を検証。 |
表で説明した各エージェントは、実際には次のようなディレクトリ構造で管理しています。
.
├── orchestrators/ # 【全体制御】全体管理用オーケストレーター
│ └── mabl-migration-orchestrator.md
├── code-generation/ # 【生成・修正】コード生成とデバッグ
│ ├── playwright-code-generator.md
│ └── playwright-debug-fix-engine.md
├── code-review/ # 【レビュー】2種類のレビュー
│ ├── playwright-code-quality-reviewer.md
│ └── playwright-spec-reviewer.md
├── knowledge/ # 【共通辞書】共通で使用するナレッジベース
│ └── playwright_knowledge_base.md
└── tool/ # 【補助ツール】静的解析用の自作スクリプト
└── playwright-reviewer-v3.js
逐次処理による「AIのコンテキスト過負荷」防止
本システムにおいて、複数のテストケースを扱う際に「逐次処理」を徹底しています。 全ファイルのコードを一度に生成して最後にまとめて実行するのではなく、1ファイルごとに作業を完結させ、成功してから次のファイルに移るというサイクルを回します。これにより、AIのコンテキスト過負荷を防ぎ、精度の高い移行を実現しています。
2. 標準化を担う生成エージェント
役割分担の中でも、生成を担うplaywright-code-generatorは、全体の標準化と効率化の役割を担っています。
ナレッジベースによる標準化
生成の詳細なルールはエージェント内に記載せず、外部のナレッジベースplaywright_knowledge_base.mdに分離し、エージェントの容量を圧縮しています。また、このナレッジベースは、レビューエージェントplaywright-code-quality-reviewerでも共通して参照しています。生成側と検証側が同じ基準を持つことで、手戻りの少ない効率的な開発サイクルを実現しました。
共通パーツの再利用
ログイン処理やヘッダー操作など、各テストで使い回す共通パーツを自動で認識し、Page Objectモデルとして適切に再利用します。これにより、類似コードの乱立を防ぎ、長期的にメンテナンスしやすいテストの作成が可能になりました。
生成エージェントによる標準化によって、品質とスピードを両立できるだけでなく、誰が実行しても一貫性のある自動テストを作成できるようになりました。
3. デバッグエージェントの独立化
テスト失敗時の原因究明する playwright-debug-fix-engine は、AIの推測に頼った「なんとなくの修正」を排除し、客観的な証拠を最優先する設計です。
生成エージェントと分けた理由
生成するエージェントと同じセッションでデバッグすると、AIが自分で書いたコードや過去のやり取りに引きずられるバイアスが生じます。
独立したエージェントとして呼び出すことで、新しいセッションで調査を開始でき、事前の状況に左右されず、現在のコードと実行結果だけを客観的に診断することが可能になります。
Playwright MCPによるライブ診断
AIがブラウザを直接操作する MCP (Model Context Protocol)を活用し、エラー時の状態をリアルタイムで診断します。
- 構造解析: アクセシビリティツリーから、壊れにくいセレクタを再選定します。
- 視覚的確認: スクリーンショットやHTMLで、要素の被りや配置のズレを捉えます。
- 切り分け: ネットワークログ等から、プログラムのミスか通信エラーかを区別します。
「堂々巡りの修正」をさせない
AIが3回試行しても解決できない課題に対し、それ以上の修正をストップしています。
代わりに、それまでの試行過程と収集した証拠をまとめ、Gemini等の外部LLMに相談しやすい形にし、人間にバトンタッチします。
エージェントで無理な修正をしないことで、堂々巡りの修正を防いでいます。
4. 2種類のレビューエージェント
レビュー工程では、1つのエージェントに全てを任せるのではなく、観点を「技術」と「仕様」に完全に分離しました。
| レビュー種類 | 担当エージェント | 主な検証ポイント |
|---|---|---|
| 技術品質レビュー | playwright-code-quality-reviewer | POM設計、セレクタ戦略、認証管理、CI/CD統合、規約準拠。 |
| 仕様完全性レビュー | playwright-spec-reviewer | 原本との突き合わせ、実装漏れ検出、定量的評価。 |
役割を分けた理由
エージェントを分けた理由は、AIに役割を絞らせて見落としを防ぐためです。
- 情報の整理: 1つのAIに大量の規約と複雑な仕様を同時に読み込ませると、情報が混ざり、未実装の機能を実装済みと思い込むようなミスが起きやすくなります。
- チェックの精度向上: コードの綺麗さと仕様の網羅性を別々の視点でチェックすることで、細かな実装漏れも見つけ出せるようになります。
責務を分離することで、各工程のチェック精度を高めています。
5. AI+ツールでレビュー
AIエージェントは文脈判断に優れますが、一方で単純な形式チェックを見落とすことがあります。
そこで、AIレビューに加えて、独自の静的解析ツール playwright-reviewer-v3.js を実行するハイブリッド体制にしました。
- AI：POMの責務分離や、アサーションの論理的な配置をレビュー。
- ツール：23項目のアンチパターン（waitForTimeout の使用、await 忘れ等）を機械的に検出。
この2段構えにより、AIの見落としを防ぎ、品質を担保しています。
おわりに
本システムの活用により、Playwrightの経験有無に関わらず、チーム全員が移行タスクの即戦力になれました。
今は移行メインですが、今後は新規テスト作成や継続的な品質を担保する仕組みとしても活用していく予定です。
We're Hiring!
そんなわけで自動化や効率化が大好きな方、AIが大好きな方、なぜか不具合に好かれる方など様々なQAエンジニアを募集しています。一緒にQA活動しましょう！
