qa-project-context

このスキルは、ほかのすべてのQAスキルが読み込む唯一のファイルを作成します。このファイルがないと、各スキルが「どのフレームワークですか？CIは何ですか？テストはどこにありますか？」と毎回ゼロから尋ね、一般的なアドバイスを返すことになります。このスキルは、プロジェクトのルートに `.agents/qa-project-context.md` を作成し、プロダクト、技術スタック、テストスタック、CI/CD、環境、品質目標、リスク領域、チーム、規約を記録します。テンプレートのプレースホルダーは、根拠のある値か、明示的な不明情報に置き換えてください。回答が得られないからといって、値を捏造してよいわけではありません。

後続のスキルは特定のセクションを利用します。Risk Areas は risk-based-testing と test-strategy に、Conventions → Selectors は playwright-automation と test-reliability に、 Quality Goals は qa-metrics に、Tech Stack はすべての自動化スキルに反映されます。これらのセクションを丁寧に埋めれば、ほかのライブラリ全体の品質も向上します。

検出時の質問

まず、.agents/qa-project-context.md がすでに存在するか確認してください。存在する場合は、その内容を読み、既存のセクションをコンテキストとして使用します。情報の出所と、関連する設定に変更がないかを確認してください。リポジトリ内の設定ファイルをスキャンし（「コードベースの検出」を参照）、出所とともに確認できた値を記録してから、作業に影響する不足情報や矛盾についてのみ質問してください。残りの質問は、必ずセクションごとに進め、一度にすべて尋ねないでください。

プロダクト

• プロダクト名は何ですか？また、何をするものかを一文で説明してください。
• どのような種類ですか？（SaaS、eコマース、メディア、モバイルアプリ、APIサービス、社内ツール）—重要なフローが変わります。
• 本番環境、ステージング環境、開発環境のURLは何ですか？
• 最も重要なユーザージャーニーを5～10個挙げてください。「これが壊れたら、午前2時に呼び出される」ようなものです。このリストが、ほかのすべてのスキルのテスト対象の優先順位を決めます。

技術スタック

• フロントエンドのフレームワークと言語は何ですか？バックエンドのフレームワーク、言語、APIスタイル（REST、GraphQL、tRPC、gRPC）は何ですか？
• データベース、キャッシュ層、ORMは何ですか？ホスティング、CDN、監視ツールは何ですか？
• モノレポですか？そうであれば、各アプリを個別に列挙してください（「モノレポに関する注記」を参照）。シャーディングと検出方法が異なります。

テストスタック

• 現在、E2Eテストはありますか？フレームワーク、設定ファイルの場所、テストディレクトリを確認してください。単体テスト、APIテスト、ビジュアルテスト、パフォーマンステストについても同様に確認してください。
• フレームワークが検出された場合は、その名前、設定ファイルのパス、ロックファイルまたはインストール済みパッケージから確認した解決済みバージョンを記録してください。^1.62.0 のようなマニフェストの制約は、インストール済みバージョンではなく範囲として示してください。設定ファイルが存在しても、テストを実行できるとは限りません。
• テスト基盤がまったくありませんか？それも有効な回答です。その場合は「まだ選定されていません」と記録し、デフォルトを注記してください（「基本原則3」を参照）。

CI/CD

• プラットフォームは何ですか？テストはいつ実行されますか（プッシュのたび、PRのみ、夜間、手動）？シャーディングや並列化は行われていますか？
• デプロイをブロックする条件は何ですか？また、どのアーティファクト（スクリーンショット、レポート、カバレッジ）が保存されますか？

環境

• 環境はいくつあり、それぞれのURLは何ですか？ステージング環境は本番環境とどの程度近いですか（インフラ、データの形状、サードパーティ連携）？
• 開発ではモックサービスと実際のAPIのどちらを使っていますか？—環境の同等性がテストの信頼性を左右します。

品質目標

• 現在のカバレッジ目標は何ですか？許容できるフレークの水準は？テストスイートの実行時間の予算は？追跡中または設定したい指標はありますか？
• 目標がまだありませんか？成熟度に応じた現実的な目標を提案してください（「品質目標」セクションを参照）。

リスク領域

• 本番環境で最も多くインシデントが発生するのはどの部分ですか？特に不安定な連携（決済、メール、サードパーティAPI）はどれですか？
• 変更が頻繁で、カバレッジが低いのはどこですか？すべてを「影響度 × 発生可能性」で評価してください（「リスク領域」セクションを参照）。

チーム

• QAエンジニアは何人いて、それぞれの専門分野は何ですか？開発者とQAの比率は？開発手法は何ですか（Scrum、Kanban、Shape Up）？
• QAはいつから関与しますか（仕様策定時からのシフトレフトか、開発後か）？—これによって自動化のオーナーシップモデルが決まります。

規約

• テストファイルの命名パターンは何ですか？コードと同じ場所に置きますか、それとも分離しますか？ブランチ戦略とPRの要件は何ですか？
• E2Eテストのセレクター戦略は何ですか？テストデータ戦略（ファクトリー、フィクスチャ、シード済みDB、テストごとのAPI利用）は何ですか？

中核となる原則

1. ライブラリ全体の唯一の信頼できる情報源を1つのファイルにします。 すべてのスキルは、最初に .agents/qa-project-context.md を読みます。その内容をほかのドキュメントに重複して記載すると、必ず 不整合が生じます。技術スタック、目標、リスクはここに記載し、ほかのスキルから参照するようにします。

2. 理想ではなく、実際の状態を記録します。 E2E テストがない場合は、希望を書くのではなく「まだ選定されていません」と記載します。後続のスキルは実際の状況に応じて処理を切り替えます。フレームワークが見つからなければセットアップを提案し、存在しないフレームワークを記載すると、砂上に楼閣を築くことになります。

3. 尋ねる前に検出し、検出できるものがない場合に限ってデフォルトを推奨します。 まず package.json、ロックファイル、設定ファイルを読み、見つかった内容を根拠とともに記載します。ツールの推奨は専門スキルに任せます。唯一の例外は、テスト基盤がまったくないプロジェクトです。その場合は、テストスタックにデフォルトとして Playwright（E2E）と Vitest（ユニット）を記載し、playwright-automation ／ unit-testing に引き継ぎます。これは「推奨しない」というルールに対する唯一の例外です。それ以外は、事実の記録にとどめます。

4. リスク領域には根拠が必要です。 この情報は risk-based-testing と test-strategy への入力になります。把握しているリスクを記録し、提案するリスクやスコアには仮定であることを明記します。インシデント履歴、発生可能性、ビジネスへの影響が不明な場合は、その不足を記録します。表を埋めるためだけに、リスクを3つでっち上げたり、正確そうなスコアを付けたりしないでください。

コードベースの検出

技術スタックについて尋ねる前に、以下を確認します。検出した値とそのファイルを根拠として記載します。テスト設定が見つかった場合は、フレームワークと、そのバージョンおよび実行方法が分かっているかどうかを記録します。

ファイル	示す内容
package.json	Node.js プロジェクト — フレームワークは dependencies を確認
next.config.*	Next.js
nuxt.config.*	Nuxt/Vue
angular.json	Angular
astro.config.*	Astro
react-router.config.ts	React Router 7 / Remix
requirements.txt / pyproject.toml	Python プロジェクト
go.mod	Go プロジェクト
playwright.config.*	Playwright が設定済み → テストスタックの E2E に記入
cypress.config.*	Cypress が設定済み → テストスタックの E2E に記入
vitest.config.* / jest.config.*	ユニットテストフレームワーク → テストスタックのユニットに記入
.github/workflows/	GitHub Actions CI
.gitlab-ci.yml	GitLab CI
Jenkinsfile	Jenkins
docker-compose.*	Docker ベースの環境
wrangler.*	Cloudflare Workers
vercel.json	Vercel ホスティング
bun.lock / bun.lockb	Bun ランタイム
pnpm-workspace.yaml / turbo.json / nx.json	モノレポ — モノレポに関する注記に従って対応
src-tauri/tauri.conf.json	Tauri デスクトップアプリ
.claude/	プロジェクトで Claude Code のスキル／エージェントを使用
.claude-plugin/plugin.json	プロジェクトが Claude Code プラグインを提供
AGENTS.md	Codex ／ マルチエージェントのワークフロー規約

ワークフロー：コンテキストファイルの作成

1. 既存のコンテキストを確認します。 プロジェクトのルートに .agents/qa-project-context.md があるか確認します。
2. ファイルがない場合： 必要に応じて .agents/ を作成し、セクションの構成を用意します。Product から始めて Discovery Questions を行い、回答が揃ったらファイルを作成します。
3. ファイルにプレースホルダーがある場合： ファイルを読み、完了しているセクションと未記入のセクションを一覧にします。未記入のセクションについてのみ質問し、その後更新します。完了済みのセクションは変更せずに保持します。
4. ファイルがあり、すべて記入済みの場合： 現在のコンテキストを要約し、変更点（新しいツール、チームの変更、目標の変化）を尋ね、変更箇所のみ更新します。
5. 完了後： ファイルパスを確認し、Verification（以下）を実行して、コンテキストから次に使うスキルを提案します（E2E なし → playwright-automation、テスト戦略なし → test-strategy、ユニットテストなし → unit-testing）。

SaaS と複数サイトを運営するパブリッシャー向けの、記入済みファイルの全例2件とモノレポの構成については、 references/examples.md を参照してください。短い例を1つ示します。

## Test Stack
### E2E / Integration
- **Framework:** Playwright 1.60
- **Config Location:** playwright.config.ts
- **Test Directory:** tests/e2e/
### Unit / Component
- **Framework:** None selected yet — Vitest recommended (see unit-testing)

セクションごとの記入ガイド

各セクションに適した内容を説明します。空のテンプレートは、qaskills リポジトリの .agents/qa-project-context.md にあります。

製品。 重要なユーザーフローは具体的で、テスト可能な内容にしてください。「購入者が商品を検索し、カートに追加し、Stripe で決済して、確認メールを受け取る」のように記述します。「ユーザーがアプリを使う」では不十分です。このリストをもとに、すべてのテストスキルが優先順位を決めます。5〜10 項目を目安にしてください。

技術スタック。 フロントエンド、バックエンド、データベース、ホスティングをそれぞれ記録します。テスト方法に影響する場合のみバージョンを固定します（App Router と Pages Router では大きく異なります）。サンプルにバージョンが記載されているという理由だけでコピーせず、package.json から確認してください。

テストスタック。 ツールごとに、フレームワーク名とバージョン、設定ファイルの場所、テストディレクトリを記録します。まだインフラがなくても問題ありません。「None selected yet」と記載し、推奨デフォルト（原則 3）を示してください。

モノレポ。 各フロントエンドアプリを独立した技術スタックおよびテストスタックとして記載し、共通の API／バックエンドは 1 つの項目にまとめます。E2E はアプリごとに分割します（apps/admin の変更で apps/storefront の E2E が実行されないようにします）。また、CI/CD では、どのパスフィルターがどのアプリのテストスイートを実行するかを記載します。検出の手掛かり：turbo.json／pnpm-workspace.yaml／nx.json。references/examples.md を参照してください。

CI/CD。 他のスキルが必要とする情報を記載します。デプロイをブロックする条件、フィードバックの速さ、保持される証跡を明確にしてください。

環境。 ステージング環境と本番環境の違いを記載します。たとえば、ステージング環境で異なるデータベースエンジンを使っている場合、ステージングでテストが成功しても本番環境では失敗することがあります。

品質目標。 具体的で測定可能なものに限ります。成熟度に応じて、初期目標を選んでください。

成熟度	ユニットテストのカバレッジ	E2E	不安定率	テストスイートの所要時間
初期段階のスタートアップ	ビジネスロジックの 60%	重要なフローの上位 5 件	<2%	ユニット <3 分、E2E <15 分
成長段階	80%	すべての重要なパス	<2%	ユニット <3 分、E2E <15 分
エンタープライズ	90% 以上	包括的なテスト＋パフォーマンス予算	<1%	ユニット <3 分、E2E <15 分

数値で記載してください。「Istanbul で測定した行カバレッジ 80%」「直近 30 日間の不安定率 <2%」「4 シャードで E2E 全体を 15 分未満で実行」のようにします。「高い品質を目指す」などの表現は避けてください。

リスク領域。 表を使い、列は「領域」「リスクレベル」「ビジネスへの影響」「備考」とします。影響度 × 発生可能性で評価してください。

• 重大（最初にテスト）： 影響度が高く、発生可能性も高い（既知のエッジケースがある決済フローなど）。
• 重要： 影響度は高いが、発生可能性は低い（認証 — 破損すると壊滅的だが、変更はまれ）。
• 監視： 影響度は低いが、発生可能性は高い（通知のフォーマット — 頻繁に壊れるが、重大性は低い）。
• バックログ： 影響度も発生可能性も低い（管理者設定 — 安定しており、ほとんど使われない）。

少なくとも 3 項目を記載し、「すべて壊れる」のような曖昧な表現は避けてください。

チーム。 実際の人数と開発者：QA 比率を記録します。これは自動化の所有モデルを決める基準になります。

開発者：QA 比率	所有モデル
単独／QA なし（実質的に無限大）	開発者がすべてのテストを担当します。手動の回帰テストスイートは設けず、導入障壁の低い自動化（Playwright + Vitest）と CI のゲートを活用します。QA の「役割」は戦略立案と重要パスの E2E で、開発者が担当します。
高い（8:1 以上）	開発者がテストを作成し、QA は戦略立案、重要パスの自動化、探索的テストに注力します。
均衡（4:1）	QA が E2E を担当し、開発者がユニットテストを担当します。統合テストは共同で担当します。
QA が多い（3:1 未満）	専任の自動化エンジニア、包括的な回帰テストスイート、定期的な探索的テストの実施体制を設けます。

規約。 特にセレクター戦略を記録してください。playwright-automation と test-reliability は、この情報をもとに一致するセレクターを生成します。安定性を重視する場合は、data-testid（data-testid="invoice-create-button"、ケバブケース）をデフォルトにします。チームがアクセシビリティを考慮したテスト向けに、セマンティック／ARIA セレクターを好む場合は、具体的なトークン（role="button"、role="heading"、getByRole('link', { name: ... })）とトレードオフを記録してください。ARIA ロールはアクセシビリティのアサーションも兼ね、マークアップの変更にも耐えますが、文言やロールが変わると data-testid より不安定です。そのため、曖昧さをなくすには name／level を固定してください。

アンチパターン

1. 質問を一度にすべて尋ねる

30個の質問を一気に並べると、相手を圧倒し、回答も浅くなります。セクションごとに進め、まずは Product から始めてください。

2. 最終ファイルに [brackets] を残す

ユーザーがフレームワークはないと確認した場合は、「まだ選定されていません」と記録してください。根拠となる情報がない場合は、「不明。未調査」または具体的に不足している入力を記録してください。この2つは状態が異なります。通常の Markdown リンク、タスクのチェックボックス、角括弧を使ったセレクターは有効なコンテンツです。角括弧だけでは、テンプレートのプレースホルダーとは判断できません。

3. 情報を捏造する

マニフェスト、ロックファイル、設定ファイルから技術スタックを特定し、出典を示してください。データベース、ホスティングプロバイダー、インストール済みバージョン、チーム規模、合意済みの品質目標を推測してはいけません。

4. Risk Areas を省略する

根拠となる情報がなくても、このセクションは残してください。候補となるリスクは提案として記載し、不明なスコアは不明としてください。仮定上のインシデントをプロジェクトの履歴として示してはいけません。

5. ゼロインフラのデフォルトを超えるツールを推奨する

このスキルでは現在の状態を記録します。ツールの選定は playwright-automation、unit-testing、その他の専門スキルに任せてください。ここで推奨する唯一のものは、テストインフラがまったくない場合の Playwright + Vitest のデフォルトです（Principle 3）。

検証

作成したファイルを読み、各セクションを情報源と照合してください。角括弧を grep で検索すると、有効な Markdown リンクやセレクターまで除外されてしまいます。一方、任意の見出しが9つあるか数えても、誤ったセクションが含まれている可能性があります。どちらも、完全性や事実の正確性を証明するものではありません。

以下に示す9つのセクションがコードフェンスの外にあり、それぞれに実質的な内容または明示的な不明の記載があることを確認してください。テンプレートの各フィールドと置き換え後の内容を照合し、正当な角括弧の構文は保持してください。フレームワークのバージョンをロックファイルと照合し、現在の状態と推奨事項を分け、特定した値の出典を保持してください。未解決の不足情報と、次に有用なアクションを報告してください。任意の詳細が不足していても、後続のすべてのスキルが使えなくなるわけではありません。

完了条件

• .agents/qa-project-context.md が存在し、テンプレートの各フィールドに根拠のある値または明示的な不明の記載が含まれている。有効な Markdown リンクと角括弧付きのセレクターはそのまま保持されている。
• 9つのセクションがすべて存在する：Product、Tech Stack、Test Stack、CI/CD、Environments、Quality Goals、Risk Areas、Team、Conventions。
• Product には、判明している具体的なユーザーフローが記載されている。フローの根拠となる情報が不足している場合は、そのことが明記されている。
• Test Stack では、設定済みのフレームワーク、マニフェストに記載されたバージョン範囲、解決済みのバージョン、実行を確認した結果、明示的に存在しないツールまたは不明なツールが区別されている。
• Risk Areas では、根拠のあるリスクと提案が区別され、不明なスコアが明示されている。
• Quality Goals では、合意済みの数値目標と提案中または不明な目標が区別されている。
• Team には、提示された人数と比率が記載されているか、不明であることが明記されている。

関連スキル

• qa-start — 新規プロジェクトの QA を最初から最後まで立ち上げ、このスキルを最初のステップとして呼び出します。QA がまだ存在しない場合は qa-start を使用してください。コンテキストを作成または再入力する場合は、このスキルを直接使用してください。
• risk-based-testing — Risk Areas セクションを優先順位付けされたリスクマトリックスに変換します。「テストの重点をどこに置くべきか」が課題の場合は、このスキルの後に実行してください。
• test-strategy — Risk Areas、Quality Goals、Team を基に、複数四半期にわたる方針を策定します。
• qa-metrics — ここで定義された Quality Goals を追跡します。両者は同じ目標を参照します。
• playwright-automation / unit-testing — Test Stack セクションの入力後に、E2E / ユニットテストのフレームワークをセットアップします。セレクターと命名の方針については Conventions を参照します。
• ci-cd-integration — CI/CD セクションで説明されているパイプラインを構築します。

参考ファイル（references/ 内）

• examples.md — 入力済みのコンテキストファイル2つ（SaaS と複数サイトを運営する出版社）に加え、モノレポの Tech/Test Stack の構成例。