qa-test-planner

qa-test-planner スキルの概要

qa-test-planner ができること

qa-test-planner は、機能追加・リリース・バグ・UI 画面を、構造化されたテスト成果物に落とし込むための QA ドキュメント／計画作成スキルです。主な役割は、テスト計画、手動テストケース、回帰テストスイート、Figma ベースのデザイン検証メモ、バグレポートを、繰り返し使える一定の形式で生成することです。

qa-test-planner を使うべき人

このスキルは、QA エンジニア、プロダクト視点を持つテスター、エンジニアリングリード、そして毎回テンプレートをゼロから作らずに受け入れ条件のカバレッジを明確にしたいチームに向いています。特に、対象機能や変更範囲は把握している一方で、筋の通ったテスト成果物を素早く揃えたい場面で有効です。

最も適したジョブ・トゥ・ビー・ダン

qa-test-planner の本当の価値は、単に「QA ドキュメントを書く」ことではありません。情報が不完全な機能コンテキストを、テスト可能なスコープ、優先順位づけされたシナリオ、再現手順、そして他の人が実際に実行できる一貫したドキュメントへ変換することにあります。

なぜ汎用プロンプトではなくこれを選ぶのか

普通の「テストケースを書いて」というプロンプトと比べると、qa-test-planner skill には次の強みがあります。

• 明示的な起動方法とタスクの枠組みがある
• 計画、ケース、回帰スイート、バグレポート向けの出力パターンが最初から用意されている
• 前提条件、期待結果、優先度、エッジケースといった QA の基本構造がより強い
• 回帰戦略、Figma 検証、テンプレートに関する参照資料がある
• どんな情報モデルを想定しているかが分かる補助スクリプトがある

重要な差別化ポイント

際立つ違いは、目新しさより実務性にあります。

• 計画作成だけでなく、実行可能な手動テストケース作成にも対応している
• smoke、targeted、full regression を含む、回帰テストの考え方が専用ガイドとして整理されている
• 受け入れ確認や UI チェック向けの Figma 検証フローがある
• 再現性を高めやすい、構造化されたバグレポートテンプレートがある

qa-test-planner が向かないケース

自動テスト生成、コードレベルのテストハーネス作成、環境依存の深い QA オーケストレーションを最初から求めるなら、qa-test-planner for Acceptance Testing は適しません。このスキルが最も強いのは、手動 QA 成果物と構造化された分析であって、エンドツーエンドの自動化コードではありません。

qa-test-planner スキルの使い方

skills 環境に qa-test-planner をインストールする

共有リポジトリの installer パターンを使っている場合は、次のコマンドでインストールします。

npx skills add softaworks/agent-toolkit --skill qa-test-planner

このリポジトリでは explicit-trigger skill として扱われているため、インストールしただけでは使われません。必要なときに必ず名前で呼び出す必要があります。

qa-test-planner を明示的に起動する

リポジトリにある以下の形式で明示的に呼び出します。

• /qa-test-planner
• qa-test-planner
• use the skill qa-test-planner

ここが重要です。あいまいな QA 指示だけで暗黙的に有効化される設計ではありません。

まず読むべきファイル

短時間で全体像をつかみたいなら、次の順で読むのがおすすめです。

1. skills/qa-test-planner/SKILL.md
2. skills/qa-test-planner/README.md
3. skills/qa-test-planner/references/test_case_templates.md
4. skills/qa-test-planner/references/regression_testing.md
5. skills/qa-test-planner/references/bug_report_templates.md
6. skills/qa-test-planner/references/figma_validation.md

スキルがどの項目を前提にしているかまで正確に把握したい場合は、次の shell script も参考になります。

• scripts/generate_test_cases.sh
• scripts/create_bug_report.sh

プロンプトの前に成果物タイプを決める

qa-test-planner usage は、1 回の依頼で 1 つの具体的な出力タイプを指定したときに最も機能します。

• test plan
• manual test cases
• regression suite
• Figma validation
• bug report

複数を混ぜた依頼は、カバレッジが浅くなりがちです。おすすめは、まず plan を作り、その後に cases を派生させ、最後に regression のサブセットを組む流れです。

qa-test-planner に必要な入力情報

このスキルは、次の情報があると精度が大きく上がります。

• 機能名とビジネス上の目的
• 関わるユーザーロール
• 受け入れ基準または期待される振る舞い
• 対象環境とプラットフォーム範囲
• 既知の連携先や依存関係
• リスクの高い領域
• 関連 URL、スクリーンショット、または Figma リンク
• リリース種別: new feature, bug fix, refactor, hotfix

これらがなくても体裁は整った出力になりますが、実際のエッジケースを取りこぼしたり、逆に広く一般化しすぎたりしやすくなります。

粗い依頼を強いプロンプトに変える

弱いプロンプト:

Generate test cases for checkout.

より良いプロンプト:

Use qa-test-planner to generate manual test cases for guest and logged-in checkout on web. Cover shipping address, coupon application, payment failure, order confirmation, and inventory edge cases. Environment: staging. Browser scope: Chrome and Safari. Include preconditions, test data, step-by-step expected results, and a priority for each case.

これが良くなる理由:

• 機能境界が狭く明確
• ユーザーモードが明示されている
• リスクの高いフローが分かっている
• 環境とブラウザ範囲が指定されている
• 欲しい出力構造が明示されている

qa-test-planner の受け入れテスト向けプロンプト例

qa-test-planner for Acceptance Testing を使うときは、単なる UI 操作ではなく、業務上検証できるシナリオを依頼するのがポイントです。

Use qa-test-planner to create an acceptance test plan for the user authentication feature. Include happy path, invalid credentials, password reset, session timeout, remember-me behavior, account lockout, and role-based redirect behavior. Mark which scenarios are critical for release sign-off.

こうすることで、汎用的な機能チェックではなく、受け入れ基準のカバレッジに寄った出力になります。

qa-test-planner の回帰テスト計画プロンプト例

良い回帰テスト依頼では、変更箇所とリリースリスクを明確にする必要があります。

Use qa-test-planner to build a targeted regression suite for the payment module after changes to card tokenization and retry logic. Separate smoke tests from deeper regression. Prioritize revenue-impacting paths first and call out dependencies on tax, order summary, and email confirmation.

これにより、単なる平坦な一覧ではなく、実行順と妥当な優先度づけを備えた出力になりやすくなります。

バグレポート作成のプロンプト例

スキルの bug-report 側を使うときは、観測できた事実を具体的に入れるのが重要です。

Use qa-test-planner to create a bug report. Issue: on Safari 17, the signup form clears all inputs after submitting with one invalid field. Environment: staging, macOS 14. Repro rate: 4/5. Expected: only the invalid field should be highlighted and valid inputs preserved. Include severity, priority suggestion, repro steps, and evidence checklist.

これはリポジトリのテンプレートとよく噛み合い、他のエンジニアがすぐ動けるレポートになりやすくなります。

Figma 検証は実務でどう使うか

このスキルには Figma MCP 前提のワークフローが含まれていますが、いくつか前提条件があります。

• Figma MCP server configured
• access to the design file
• usable Figma URL

実務では、デザイン側の対象と実装側の対象の両方を渡すのが効果的です。例:

Use qa-test-planner to validate the login page against this Figma design: [URL]. Focus on spacing, typography, button states, error message styling, and responsive layout differences. Output a discrepancy list and convert failures into test cases.

Figma MCP へのアクセスが設定されていない場合、design-validation の部分は相性がよくありません。

テンプレートを出力品質のチェックに使う

実用的な qa-test-planner guide として有効なのは、モデルの出力をリポジトリ内の reference と照らし合わせることです。

• test_case_templates.md で前提条件や test data の抜けを確認する
• bug_report_templates.md で環境情報や再現条件の不足を確認する
• regression_testing.md でスイート範囲のズレを確認する
• figma_validation.md で比較観点の弱さを確認する

最初からやり直すより、こちらのほうが速いことが多いです。

実チーム向けのおすすめ運用フロー

安定して使いやすい流れは次のとおりです。

1. feature test plan を作る
2. 高リスクフローの manual test cases を生成する
3. smoke または targeted regression のセットを抜き出す
4. 必要なら UI/design validation を行う
5. 検出した不具合から structured bug reports を作る

このように段階を分けるほうが、1 回で「全部」を求めるよりも、質の高い QA 成果物になりやすいです。

qa-test-planner スキル FAQ

qa-test-planner は初心者にも向いている？

はい。ただし、少なくとも対象機能の理解がある場合に向いています。テンプレートと構造のおかげで、経験の浅い QA 担当者でも、前提条件、期待結果、優先度、環境情報といった基本の抜け漏れを減らせます。逆に、製品の振る舞いそのものをこのスキルに発見させたい場合は、あまり向いていません。

qa-test-planner は自動テストも作る？

主目的ではありません。リポジトリから読み取れる中心機能は、手動テスト計画、回帰テストの構造化、Figma 検証、バグレポート作成です。Playwright、Cypress、unit test のコード生成が目的なら、これは最終実装レイヤーではなく、その前段の計画ツールとして使うのが適切です。

qa-test-planner が普通の AI プロンプトより優れる点は？

最大の利点は一貫性です。qa-test-planner は出力形式と QA のベストプラクティスに明確な型を持っているため、前提条件、エッジケース、環境情報、回帰範囲を毎回書き足したり、整形し直したりする手間が減ります。

どんな場合は qa-test-planner をインストールしないほうがいい？

次のようなチームなら、qa-test-planner install の優先度は高くありません。

• 欲しいのが自動テストコードだけ
• 手動 QA 成果物の運用がない
• 構造化されたバグレポートを使わない
• 受け入れテストや回帰計画が不要
• 有用な出力に必要な機能コンテキストを提供できない

qa-test-planner は UI テスト専用？

いいえ。機能テスト、連携を意識した観点、回帰テスト計画にも対応できます。ただし Figma validation をサポートしているため、UI 比重の高い受け入れワークフローでは特に魅力が大きいです。

qa-test-planner は Agile のリリース業務にも合う？

はい。スプリント単位の受け入れ計画、リリース回帰範囲の整理、検証中に見つかったバグの記録に向いています。包括的な test management tool というより、しっかりした QA 成果物を素早く作るためのスキルだと考えると分かりやすいです。

qa-test-planner スキルを改善する方法

qa-test-planner の対象範囲を狭くする

最もよくある失敗は、「アプリ全体をテストして」のように範囲が広すぎる依頼です。より良いのは、1 つの機能、1 つのリリース、1 つのロールセット、または変更された 1 つのサブシステムに絞ることです。範囲を狭めるほど、現実的で中身のある出力になり、表面的なチェックリスト化を避けやすくなります。

機能名だけでなく受け入れ基準を渡す

「Test login」では弱すぎます。「Test login with MFA, lockout after five failures, remembered session for 7 days, and redirect to original page after auth」のようにすると、スキルが振る舞いの軸を持てます。これは qa-test-planner usage を改善する最短ルートです。

具体的な環境と制約を含める

次の情報を入れると、出力の質が上がります。

• browser/device matrix
• staging vs production-like environment
• role permissions
• test data limits
• external dependencies
• release deadline or smoke-test time budget

これにより、何を smoke に入れるべきか、targeted regression に回すべきか、フルカバレッジに含めるべきかを、スキルが判断しやすくなります。

リスクベースの優先順位づけを依頼する

実行順が重要なら、そのことを明言してください。例:

Use qa-test-planner and prioritize by revenue impact, authentication risk, and production incident history.

これを言わないと、網羅的でも、実際のリリース現場では使いにくい並びになることがあります。

ハッピーパスとエッジケースを分けて依頼する

強いプロンプトは、スキルに対して次の分割を明示します。

• core acceptance scenarios
• negative tests
• boundary conditions
• cross-browser or responsive checks
• integration failure cases

この構成にしておくと、実行もしやすく、後から回帰テスト資産へ転用もしやすくなります。

reference ファイルを使って改善を回す

初稿のあと、リポジトリ内の reference を見ながら絞り込むと精度が上がります。

• severity や repro data が不足 → references/bug_report_templates.md
• edge case が弱い → references/test_case_templates.md
• regression の選定が甘い → references/regression_testing.md
• design check があいまい → references/figma_validation.md

プロンプト全体を書き直さずに結果品質を上げるには、これが最短です。

helper script を項目チェックリストとして使う

この 2 つの shell script は、実行しなくても役立ちます。保守者が、良い bug report や test case に何の項目が必要だと考えているかが、そのまま見えるからです。プロンプトからそれらの項目が抜けていると、出力もたいてい実務で使いにくくなります。

初回出力後に直したい典型的な問題

qa-test-planner の出力では、次の点をチェックしてください。

• 手順が抽象的すぎて実行できない
• expected results が操作の言い換えで、システム応答になっていない
• preconditions や test data がない
• priority や risk のラベルがない
• regression suite で smoke と full regression が区別なく混在している
• bug report に正確な環境情報と reproduction rate がない

多くは、1 回の焦点を絞った追加入力で修正できます。

最も有効な追いプロンプトの型

最初の出力のあと、最初からやり直すのではなく、修正指示を出すほうが効果的です。

Revise this qa-test-planner output. Add missing preconditions, explicit test data, browser coverage, and edge cases for invalid input, timeout, duplicate submission, and permission failure. Re-rank tests into P0/P1/P2 and separate smoke tests from full regression.

このように方向性を限定した 2 回目の依頼のほうが、広い依頼を 1 回だけ投げるより、はるかに実務向きの QA ドキュメントになりやすいです。