qa-project-bootstrap

新しい QA エンジニアに README を渡して「自分で何とかして」と任せると、試行錯誤で悪い習慣を身につけるのに 2 週間かかります。また、監査されていない既存のテストスイートには、不安定なテストやカバレッジの不足が隠れており、そうした問題は本番環境で初めて表面化します。このスキルは、最初のテストをマージするまでの時間を短縮し、30 日間の立ち上がり計画、5 つの観点からのテストアーキテクチャ監査、フレームワークの解説ドキュメントという 3 つの具体的な成果物を作成します。すべてのセクションが、同じ指標を目指しています。実際のテストをメインブランチにマージし、CI で素早く成功させることです。

開始前： プロジェクトのルートに .agents/qa-project-context.md があるか確認してください。ファイルがあれば、オンボーディングに関する技術的な背景情報が記載されており、調査に必要な質問のほとんどに答えられます。ない場合は、まずこのファイルを作成してください。

すぐに参照するセクション

このスキルは、3 つの異なる目的に対応しています。自分に当てはまるものを特定し、該当セクションに進んで、残りは読み飛ばしてください。

状況	参照先	成果物
既存のチームに新しいメンバーを迎える	最初の 30 日間のチェックリスト → メンタリングのパターン	担当者と日付を含む 30 日間の立ち上がり計画
オンボーディング資料やドキュメントのない既存のテストスイートを引き継いだ	テストアーキテクチャ監査（team_maturity に応じて範囲を調整）	5 つの観点からまとめた 1～2 ページの調査結果ドキュメント
テストを書く人向けのリファレンスドキュメントが必要	フレームワーク解説テンプレート	プロジェクト固有の walkthrough.md

通常のオンボーディングでは 3 つすべてが必要ですが、簡単な健全性チェックなら監査だけで十分です。

---

調査の質問

オンボーディングの対象者

1. 新しい QA エンジニアですか、それともテストに参加する開発者ですか？ QA エンジニアには、テスト戦略の背景情報とコードベースの把握が必要です。テストに参加する開発者には、フレームワークのパターンや規約に関する知識が必要です。立ち上がりの道筋は大きく異なります。

2. テストフレームワークの経験レベルはどの程度ですか？ Playwright／Cypress／pytest を初めて使いますか？ 経験はあるものの、このコードベースは初めてですか？ 上級者で、規約だけを知りたいですか？ これによって、フレームワーク解説をどの程度含めるかが決まります。

3. QA を単独で担当しますか、それとも既存の QA チームに加わりますか？ QA を単独で担当する場合は、規約をゼロから確立する必要があります。チームに加わる場合は、既存のパターンを学び、確立された慣習に沿って貢献します。

プロジェクトの状態

4. 既存のテストフレームワークはありますか？ ある場合は、健全な状態かどうかを確認してください。ない場合は、まずフレームワークを選定してください（test-strategy スキルを参照）。

5. プロジェクトに .agents/qa-project-context.md はありますか？ ない場合は、これを作成することを優先度の高いオンボーディングタスクにしてください。新しいメンバーが学んだことを文書化する必要が生じ、チーム全体の役に立つためです。

6. ローカル環境のセットアップ手順は文書化されていますか？ 新しいメンバーは初日中に、スタック全体を起動してテストを実行できますか？ セットアップに 2 時間以上かかる場合は、オンボーディングの前に手順を改善する必要があります。

アクセスとツール

7. 必要なアカウントと権限はすべて設定されていますか？ リポジトリへのアクセス、CI ダッシュボード、ステージング環境、テストデータ用アカウント、バグトラッカー、コミュニケーションチャネルを確認してください。初日にアクセスできないと、時間を無駄にするだけでなく、ストレスの原因にもなります。

---

基本原則

1. 最初のテストをマージするまでの時間を成功指標にする

オンボーディングの成功を測るうえで、最も重要な指標は、新しいメンバーが実際のテストをメインブランチにマージするまでにかかる時間です。チュートリアルの練習でも、ローカルだけで動かす実験でもありません。CI で実行され、実際の製品の動作を検証するテストです。目標は、最初の 2 週間以内です。

2. 複雑さを段階的に上げる

簡単なところから始めて、徐々に難易度を上げてください。最初のテストはスモークテスト、またはページ読み込みの検証です。2 つ目はフォームの操作、3 つ目は複数の手順を含むユーザーフローです。3 週目までには、新しいメンバーがスプリントのストーリーに対するテストを書くようにします。初日に、複雑な複数サービス間のフローへいきなり取り組ませると、不安や悪い習慣につながります。

3. 部族的な知識をドキュメント化する

ドキュメントに答えがない質問を新しいメンバーがするたびに、部族的な知識が外に漏れています。オンボーディングのプロセスでは、こうした回答を .agents/qa-project-context.md、フレームワークの解説ドキュメント、またはコードコメントに、できれば永続的な形で残すようにします。何が不足していたのかを正確に把握している新しいメンバーこそ、このドキュメントを書くのに最適な人です。

4. まずペアで、その後に一人で進める

最初の 3 つのテストは、ペアで作成します。新しいメンバーがドライバーを務め、経験豊富なチームメンバーがナビゲーターを務めます。ペア作業は、ドキュメントを読むだけよりも速く自信を育みながら、暗黙知（単にやり方だけでなく、なぜそのようにするのか）を伝えます。

5. 簡単な方法を正しい方法にする

テストを正しく書く方法が間違った方法より難しければ、テストは間違った方法で書かれるでしょう。テストユーティリティ、フィクスチャ、ページオブジェクト、データファクトリーを整備し、推奨パターンが最も手間のかからない方法になるようにします。新しいメンバーが規約に従うためにフレームワークと格闘しなければならないなら、フレームワークを改善しましょう。

チームの成熟度に合わせて調整します（.agents/qa-project-context.md で team_maturity を設定します）。

• startup — 1～10 日目に注力します。テストフレームワークを 1 つ稼働させ、重要なパスを 1 つカバーします。動作するベースラインができるまでは、プロセス上の形式的な手順は省略します。
• growing — 30 日間の計画全体を実施します。フレームワークの選定、CI との統合、カバレッジのベースライン、チーム規約の文書化を行います。
• established — 30 日間の計画に加えて、既存のテストスイートをアンチパターンの観点から監査し、ツールのアップグレードを提案し、メトリクスのベースラインを確立し、定期的な品質レビューを予定します。

---

最初の 30 日間のチェックリスト

第 1 週：環境、アクセス、オリエンテーション

1～2 日目：セットアップ

• リポジトリをクローンし、ローカルでビルドできる
• すべての環境変数を設定済み（.env.local、テスト用認証情報）
• アプリケーションがローカルで稼働している（フロントエンド＋バックエンド＋データベース）
• テストスイートがローカルで実行でき、パスする（または既知の失敗が文書化されている）
• IDE に推奨拡張機能（テストランナープラグイン、リンター、フォーマッター）を設定済み
• CI ダッシュボード、ステージング環境、バグトラッカー、チームのチャンネルへのアクセスが許可されている

3～4 日目：オリエンテーション

• .agents/qa-project-context.md を読む（存在しない場合は作成する）
• チームメンバーと一緒にテストディレクトリの構成を確認する
• テストピラミッドを理解する。ユニットテスト、統合テスト、E2E テストがそれぞれいくつあるか確認する
• CI パイプラインを確認する。PR 時に実行されるもの、夜間に実行されるもの、マージをブロックするものを把握する
• 重要なユーザーフローを上位 5 つ特定する（これらが最初のテスト対象になります）
• オブザーバーとして Three Amigos またはスプリント計画のセッションに 1 回参加する
• チームの AI アシスタントの利用方法： チームが使用しているコーディングエージェント（Claude Code、Codex、Cursor、Gemini CLI など）、そのコンテキストが保存されている場所（.agents/qa-project-context.md、CLAUDE.md、AGENTS.md）、チーム内で標準とされるプロンプトやスキル、チームが AI に明示的に委任しないタスクを特定します。4 日目の成果物として、「使用している AI アシスタント、その得意分野、絶対にさせてはいけないこと」をまとめた短いドキュメントを作成します。チームがエージェント経由で Playwright を自動化している場合は、エージェント駆動の Playwright 用に、独自の @playwright/cli（デーモンアーキテクチャ、playwright-cli コマンド、トークン効率に優れる）が提供されていることにも触れます。これは、フレームワークの解説ドキュメントで説明されている npx playwright test ランナーとは別のものです。

5 日目：最初の小さな成功

• デバッグ／画面表示モードでテストを 1 つ実行し、その動作を理解する
• 既存のテストのアサーションを 1 つ変更し、想定どおり失敗することを確認してから元に戻す
• 既存のテストを 3 つ読み、各セクションが行うこと（セットアップ、アクション、アサーション）を書き添える

第 2 週：初めての実践テスト

• 作成するシンプルでリスクの低いテストを特定する（ページの読み込み、要素の表示、基本的なナビゲーション）
• 既存のページオブジェクトとフィクスチャを使ってテストを作成する（チームメンバーとペアで作業する）
• テストをローカルで実行し、安定して合格することを確認する（3 回連続で実行）
• PR を作成し、フィードバックを受けて改善する
• CI でテストが合格する
• 最初のテストをマージする

第 3 週：スプリントへの貢献

• メンターのサポートを受けながら、スプリントのストーリーに関する QA 作業を担当する
• ストーリーの受け入れ基準を網羅するテストを作成する
• 受け入れ基準でカバーされていないエッジケースを少なくとも 1 つ特定する
• Three Amigos やストーリーの詳細化に積極的に参加する（質問する）
• shift-left-testing の PR レビューチェックリストを使って、既存の PR を 1 つテスト品質の観点からレビューする

第 4 週：自立に向けたマイルストーン

• ペア作業をせずに、複数ステップの E2E テストを作成してマージする
• バグトリアージに参加し、テストの不足箇所を説明する
• 新たな学びを .agents/qa-project-context.md に反映する
• スプリントレビューまたはチームのスタンドアップで、テスト結果や調査結果を発表する
• 自己評価する：どのテストパターンに慣れていますか？どのパターンをもっと練習する必要がありますか？

---

テストアーキテクチャの監査

既存のプロジェクトに参加する際は、新しいテストを作成する前に、テストスイートの健全性を評価します。この監査には 2～4 時間かかり、現状を明確に把握できます。

監査の範囲は team_maturity（.agents/qa-project-context.md に記載）に応じて決めます。どのチームにも同じ監査を適用すると、スタートアップの時間を無駄にし、成熟したチームには不十分な対応となります。

• startup — 完全な監査は省略します。1 つの経路がカバーされており、1 つのフレームワークが実行できることを確認し、節約した時間を最初のテストのマージに充てます。
• growing — 5 つすべての観点を一度監査してベースラインを確立し、定期的なレビューは後回しにします。
• established — 5 つすべての観点を完全に監査し、スケジュールに沿った定期的な品質レビュー（例：毎月）を実施します。調査結果のドキュメントは継続的に記録します。

評価項目

記入式のワークシートを使って、次の 5 つの観点を評価します。

• カバレッジと分布 — レイヤーごとのテスト数、ピラミッドの形状、コードカバレッジとその推移。
• 信頼性 — 不安定なテストの割合、特に不安定なテスト、隔離されたテストの数と経過期間。
• CI の健全性 — 全テストスイートおよび各ステージの実行時間、並列度、合格率、再試行率。
• 技術的負債 — スキップされたテスト、waitForTimeout／force: true の使用、ハードコードされたデータ、アサーションのないテスト、非推奨の API、古くなった AI 生成テスト、古くなった機能フラグ。
• 規約 — ページオブジェクト、フィクスチャ、ファクトリー、命名、共有ユーティリティ、タグ付け。

5 つすべての観点をカバーする、コピーして記入できるワークシートについては、references/audit-worksheets.md を参照してください。

監査結果

調査結果を次のように分類し、1～2 ページの簡潔なドキュメントにまとめます。

• 強み： 既存のテストスイートがうまくできている点（維持し、参考にする）
• 不足： カバレッジが欠けている領域、テストが不十分な重要経路
• リスク： 不安定なテスト、古くなった隔離、低下傾向にあるカバレッジ
• すぐにできる改善： 1～2 スプリントで実現できる改善（不安定なテストの修正、欠けているハッピーパスのカバレッジ追加）
• 戦略的な取り組み： 継続的な投資が必要な改善（テストアーキテクチャのリファクタリング、統合テストレイヤーの追加）

---

フレームワークの概要テンプレート

このドキュメントをプロジェクト用に作成してください。テストを書く人にとっての主要なリファレンスです。次の6つのセクションで構成されています。

1. アーキテクチャの概要 — フレームワーク、言語、設定ファイルの場所、注釈付きディレクトリツリー。
2. テストの実行方法 — 実行コマンド一式（全テスト、単一ファイル、grep、ヘッドあり、デバッグ、UI モード、ブラウザーごと、レポート）。
3. 新しいテストの書き方（手順） — 場所の確認／再利用／記述／実行／PR の6つの手順と、Arrange-Act-Assert のテストテンプレート。
4. 失敗のデバッグ方法 — ローカルと CI の失敗時の手順、およびよくある失敗パターンの解説。
5. よくあるパターンと規約 — 認証フィクスチャ、データファクトリー、アサーションの具体性、セレクターの優先順位に関するプロジェクト固有の例。
6. ヘルプの参照先 — パターン、失敗、製品の動作、ドキュメントに関する質問の問い合わせ先をまとめた表。

すべてのコードブロック、ディレクトリツリー、コピーして調整するコマンド一覧を含む完全なテンプレートについては、references/framework-walkthrough.md を参照してください。

---

コードベースの案内ガイド

新しいメンバーと60～90分のセッションを行い、次の領域を案内してください。

テストディレクトリ構成の案内

実際のディレクトリツリーを見ながら、次の点を説明してください。

• テストがこのように整理されている理由（種類別ではなく、機能別）
• 各製品領域のページオブジェクトの場所
• 共有ユーティリティの場所とその役割
• テストデータとフィクスチャの定義場所
• CI 設定の場所

共有ユーティリティ一覧

ユーティリティ	場所	目的	例
認証フィクスチャ	fixtures/auth.fixture.ts	認証済みセッションを提供します	{ adminPage, userPage }
データファクトリー	helpers/factories.ts	API 経由でテストデータを作成します	createTestUser({ role: 'editor' })
API クライアント	helpers/api-client.ts	セットアップ／後処理用の直接 API 呼び出し	apiClient.delete('/users/' + id)
アクセシビリティヘルパー	helpers/a11y.ts	axe-core のラッパー	checkAccessibility(page, testInfo)
アサーション	helpers/assertions.ts	カスタムマッチャー	toHaveToast('Saved')

ページオブジェクトの案内

既存のページオブジェクトを示し、次の点を説明してください。

• 基底ページクラスとその契約（抽象プロパティ path、waitForReady）
• コンポーネントオブジェクトとページオブジェクトの組み合わせ方
• 命名規則（ファイル名はルートに対応します。例：/checkout の場合は checkout.page.ts）
• 新しいページオブジェクトの追加方法（既存の最もシンプルなものをコピーして変更するパターン）

CI パイプラインの案内

CI 設定を開き、次の点を順に確認してください。

• パイプラインの起動条件（push、PR、スケジュール）
• 実行されるステージとその順序
• テスト成果物（レポート、トレース、スクリーンショット）の保存先
• CI で失敗したテストの見つけ方と結果の解釈方法
• 失敗したジョブの再実行方法

---

メンタリングのパターン

最初の3つのテストをペアで進める

経験豊富なチームメンバーが、新しいメンバーの最初の3つのテストに付き添います。

1. テスト1：ナビゲーター／ドライバー。 経験豊富なメンバーがアプローチを説明し、重要な判断を行います。新しいメンバーは入力し、各手順で「なぜ？」と質問します。目標：ワークフローを理解すること。
2. テスト2：共同作業。 2人が同じ程度に貢献します。新しいメンバーがより多くの判断を行い、経験豊富なメンバーが不足を補います。目標：自信をつけること。
3. テスト3：見守り。 新しいメンバーがすべて主導します。経験豊富なメンバーは見守り、質問されたとき、または問題につながるアプローチの場合にのみフィードバックします。目標：自立すること。

最初の2週間はすべての PR をレビューする

最初の2週間は、新しいメンバーからのすべての PR を丁寧に、サポートする姿勢でレビューします。「LGTM」だけで済ませず、次の点について具体的にフィードバックしてください。

• パターンの遵守（ページオブジェクトを正しく使っていますか？）
• セレクターの方針（安定したロケーターを使っていますか？）
• アサーションの品質（アサーションは十分に具体的ですか？）
• テストの分離（共有状態によるリスクはありませんか？）
• 命名（テスト名は動作を説明していますか？）

2週間後は、通常のレビューの深さに戻します。

テストバディ制度

新しいチームメンバーがためらわずにどんな質問でもできる、特定の担当者をテストバディとして割り当てます。テストバディは次のことを行います。

• 最初の1週間は毎日様子を確認します（「何につまずいていますか？」）
• 予定を組まなくても、随時質問に対応します
• 教育的なコメント（「なぜそうするのか」の説明）を添えて、すべてのPRをレビューします
• 新しいメンバーにチームの規範や暗黙のルールを紹介します

段階的な責任範囲の拡大

Week 1-2:  Write tests for existing, well-understood features (smoke, basic flows)
Week 3-4:  Write tests for current sprint stories (with pairing available)
Week 5-6:  Write tests independently, review others' PRs
Week 7-8:  Contribute to test architecture (new fixtures, utilities, page objects)
Month 3+:  Lead test planning for a feature area, mentor the next new person

---

避けるべきアンチパターン

放任型のオンボーディング

新しいメンバーにリポジトリへのアクセス権を与え、READMEを案内しただけで、自力で理解することを期待するやり方です。これでは何週間もの時間が無駄になり、試行錯誤を通じて悪い習慣が身につき、早期離職につながります。ペア作業を取り入れた体系的なオンボーディングは、最初のスプリントで十分に元が取れます。

チュートリアルだけのオンボーディング

実際のコードベースに触れる前に、フレームワークのチュートリアルや簡単な練習課題に2週間を費やすやり方です。チュートリアルで学べるのは構文であり、プロジェクトの規約、ドメイン知識、チームのワークフローは学べません。チュートリアルは最小限（最大1〜2時間）にとどめ、すぐに実際のテストに取り組みましょう。

ドキュメントがなく、暗黙知だけに頼る

あらゆる質問への答えが「Sarahに聞いてください」なら、チームのバス係数は1であり、オンボーディングは完全にSarahの都合に左右されます。規約は.agents/qa-project-context.mdとフレームワークのガイドに記録しましょう。口頭で説明するほど重要なことなら、書き留める価値もあります。

完璧主義による停滞

新しいメンバーの最初のテストに完璧さを求めるやり方です。最初のテストは、基本的な規約に従った実用的なものであれば十分です。コードの品質はPRのレビューを重ねるごとに向上します。スタイルの細かな指摘や高度なパターンを理由に最初のPRをブロックすると、自信を損ない、最初の成功体験を遅らせます。

オンボーディング体験を振り返らない

オンボーディングを受けた本人にフィードバックを求めないやり方です。本人はプロセスを実際に経験しており、何が不足していたか、分かりにくかったか、時間の無駄だったかを正確に知っています。2週目と4週目の終わりに15分間のフィードバックセッションを実施しましょう。そのフィードバックを次のメンバーのオンボーディング改善に活かします。

理解せずにコピー＆ペーストする

新しいメンバーが既存のテストをコピーし、ロケーターとURLを変更して完了とするやり方です。テストは動いても、なぜそうなっているのかは理解できていません。ペア作業やコードレビューでは、それぞれのパターンの「なぜ」に焦点を当てましょう。フィクスチャが特定の構成になっている理由を説明できなければ、状況が異なるときに誤用することになります。

---

検証

オンボーディング完了を宣言する前に、成果物が要件を満たしていることを確認しましょう。最初に、最も低コストの確認から行います。

1. 最初にマージされたテストが、運よく通っただけではなく安定していること。 不安定さがないことを確かめるために繰り返し実行し、その後CIがグリーンであることを確認します。
   • npx playwright test <new-test> --repeat-each=3が終了コード0で終了する（ローカルで3回連続して成功する）
   • 同じテストについて、PRのCIチェックがグリーンである
2. 監査ドキュメントが未完成のひな形ではなく、内容が揃っていること。 所見ドキュメントを開き、5つの観点（カバレッジ／分布、信頼性、CIの健全性、技術的負債、規約）がすべて記入され、所見が強み／ギャップ／リスク／すぐに取り組める改善／戦略的な取り組みに分類されていることを確認します。監査を対象外としたスタートアップ（team_maturityを参照）の場合は、その決定を記録します。
3. コンテキストファイルが解析可能で、内容が記入されていること。 .agents/qa-project-context.mdが存在し、フレームワーク、重要なパス、チーム構成、リスク領域が記載されていることを確認します。概要レベルのプレースホルダーだけでは不十分です。

完了条件

• リポジトリに少なくとも1つの動作するテストがマージされ、CIで成功し、ローカルで3回繰り返しても安定していること（--repeat-each=3 が終了コード0で終了する）。これにより、ローカルとパイプラインのセットアップがエンドツーエンドで機能することを確認します。
• テストアーキテクチャ監査ドキュメントがあり、5つの側面すべてが記入され、調査結果が分類されていること（強み、ギャップ、リスク、すぐにできる改善、戦略的な取り組み）。または、team_maturity がスタートアップの場合は、対象外とする明示的な判断がドキュメントに記録されていること。
• Week-1 Day-1/2 のセットアップ項目すべてについて担当者と目標日が記録されていること。作業を妨げる項目は、追跡可能なチケットとして登録されていること。
• .agents/qa-project-context.md が存在し、フレームワーク、重要なパス、チーム構成、リスク領域が記入されていること（プレースホルダーではないこと）。
• テストフレームワークが選定され、その理由が記録されていること（代替案を評価し、決定事項を文書化していること）。既存のフレームワークを引き継ぐ場合は、N/A と記載されていること。

参考ファイル（references/ 内）

• framework-walkthrough.md — フレームワークの詳細な説明テンプレートです。アーキテクチャの概要、実行コマンド、新しいテストの手順とテンプレート、デバッグ用プレイブック、規約、問い合わせ先が含まれます。
• audit-worksheets.md — テストアーキテクチャ監査用の記入式ワークシートです（カバレッジ、信頼性、CI の健全性、技術的負債、規約）。

関連スキル

• qa-project-context -- プロジェクトコンテキストファイルはオンボーディングの基礎です。存在しない場合は作成し、オンボーディングの一環として更新してください。
• playwright-automation -- Playwright ベースのプロジェクト向けの、フレームワーク固有のパターン、ページオブジェクトモデル、フィクスチャ、CI 統合について説明します。
• shift-left-testing -- Three Amigos、PR レビュー、完了の定義など、チームのシフトレフトの実践を新しいメンバーに紹介します。
• test-strategy -- テスト戦略全体を把握することで、テストがそのように構成されている理由について、新しいメンバーが理解を深められます。
• test-reliability -- 不安定なテストのパターンと隔離管理を理解することで、新しいメンバーが信頼性の低いテストを作成するのを防げます。