qa-expert

qa-expert skill の概要

qa-expert ができること

qa-expert は、一般的なテスト案を並べるだけではなく、QA 計画と品質ゲートの設計を支援する skill です。とくに、何から優先してテストすべきか、どこまで深く検証するか、そしてどのチェックを commit・merge・release のブロッカーにするか を整理したいチームに向いています。

qa-expert を導入すべき人

qa-expert は、エンジニアリングリード、テスト自動化エンジニア、プラットフォームチーム、そして本格的な QA 組織をゼロから作るほどではないものの、品質に最低限の型を持たせたいプロダクトチームに適しています。とくに、qa-expert for Test Automation として、テスト計画、カバレッジ判断、リリースゲート設計に活用したい場合に相性が良いです。

実際の「片づけたい仕事」

多くのユーザーが欲しいのは、抽象的な QA 論ではありません。機能、repo、リリース計画をもとに、次のような形へ落とし込む支援です。

• リスクベースのテスト計画
• 現実的な testing pyramid
• 具体的な品質ゲート
• 次アクション付きのカバレッジレビュー

こうした用途では、単発の通常プロンプトより qa-expert skill のほうが実務で使いやすいです。

この skill の違い

qa-expert の実用的な差別化ポイントは、方針が明確な構造にあります。

• 影響度ベースのリスク優先順位付け
• testing pyramid の明示的な配分
• pre-commit や pre-merge など段階別の品質ゲート
• ゲート、メトリクス、戦略に関する参照資料
• test-plan と coverage-analysis の文書を生成する補助スクリプト

そのため、単なる「テストを書いて」系のアシスタントよりも、プロセス設計目的では qa-expert のほうが導入価値があります。

導入前に知っておきたいこと

この skill は、計画とガバナンスの支援 に最も強みがあります。repository を見る限り、フレームワーク固有のテスト実装、CI テンプレート、深いツール連携が最初から入っているわけではありません。Playwright/Cypress/Jest のコード生成まで必要なら、これ単体では完結しません。一方で、再利用できる QA 判断フレームを持ちたいなら、かなり有力な出発点になります。

qa-expert skill の使い方

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

repository の SKILL.md には skill 単体の install command は明示されていないため、コレクションの install パターンを使います。

npx skills add https://github.com/zhaono1/agent-playbook --skill qa-expert

インストール後は、agent 環境で skill が利用可能か確認し、デフォルト挙動をそのまま信用する前に source files を開いて中身を把握しておくのが安全です。

最初に読むべきファイル

qa-expert usage を素早くつかむなら、次の順番で読むのがおすすめです。

1. skills/qa-expert/SKILL.md
2. skills/qa-expert/references/strategy.md
3. skills/qa-expert/references/gates.md
4. skills/qa-expert/references/metrics.md
5. skills/qa-expert/scripts/generate_test_plan.py
6. skills/qa-expert/scripts/coverage_analysis.py

この順番なら、まず判断モデルを理解し、その後で再利用しやすいテンプレート群を追えます。

どんなときに qa-expert skill を呼ぶべきか

次のような依頼をしたいときは、qa-expert の出番です。

• 「この機能の QA plan を作って」
• 「repo 用の quality gates を設計して」
• 「最初に何のテストを書くべき？」
• 「coverage の抜けを見て優先順位を提案して」
• 「高リスクなワークフロー向けの release gate を設計して」

逆に、必要なのが「unit test を 1 本だけ書く」程度なら、この skill は少し大きすぎるかもしれません。

qa-expert に必要な入力

出力品質は、与える文脈にかなり左右されます。qa-expert は次の情報があると特に機能しやすくなります。

• 機能名またはシステム名
• ユーザーにとって重要な主要フロー
• money、auth、data loss、compliance、integrations などのリスク領域
• 現在の技術スタックとテストツール
• リリース頻度
• flaky な E2E や低い coverage など、現状の痛み
• commit、merge、release ごとに求める gate の厳しさ

これらがないと、skill はどうしても汎用的な QA 構成に寄ります。

ざっくりした目的を、強い qa-expert プロンプトに変える

弱い prompt:

Create a QA plan.

より強い prompt:

Use qa-expert to create a QA plan for our checkout flow. Stack: React, Node.js, PostgreSQL. Critical risks: payment failure, duplicate charges, promo code edge cases, order-loss after timeout. Current tests: some unit tests, almost no integration tests, no release gates. We deploy twice weekly. Recommend test levels, coverage priorities, pre-commit and pre-merge gates, and metrics we should track for the next 30 days.

この書き方が有効なのは、対象範囲、リスク、現状、意思決定上の制約が揃うためです。

リスクモデルを意図的に使う

qa-expert skill を入れる実務上の理由のひとつが、リスクベースのテスト分類テーブルです。repository では次のような区分がされています。

• money、security、data などの critical areas
• high-risk な core features
• medium-risk な secondary features
• low-risk な edge features

このモデルは、優先順位を強制するために使うべきです。critical path を明示的にラベル付けしないと、価値の低いテストに工数をかけすぎて、障害が起きやすい重要フローへの投資が不足しがちです。

テストを増やすのではなく、testing pyramid を当てはめる

この skill では、シンプルな配分として次を勧めています。

• 60% unit
• 30% integration
• 10% E2E

これは絶対ルールではなく、あくまで計画の初期値として扱うのが適切です。qa-expert for Test Automation として使う場合、この考え方は、遅くて flaky になりやすい E2E 偏重の test suite を避ける助けになります。単に割合で終わらせず、実際の module や user journey を各レイヤーへどう割り当てるかまで skill に出させるのがポイントです。

付属スクリプトを使って導入を速める

補助スクリプトは小ぶりですが、実務的です。

test plan テンプレートを生成する:

python skills/qa-expert/scripts/generate_test_plan.py --name "Checkout" --owner "Payments Team"

coverage analysis テンプレートを生成する:

python skills/qa-expert/scripts/coverage_analysis.py --name "Checkout Service" --owner "Payments Team"

これらの script はコードを自動解析するものではなく、skill と一緒に埋めたり磨いたりできる構造化ドキュメントを生成します。そのため、docs-first で軽量に回したいチームにとっても、qa-expert install には十分な価値があります。

意思決定ポイントに沿って出力を組み立てる

おすすめの進め方は次の通りです。

1. qa-expert にリスク順位付きの戦略を出させる
2. ライフサイクル段階ごとの quality gates を出させる
3. test plan document を生成する
4. critical areas の coverage gaps をレビューする
5. 推奨事項を CI checks と team ownership に落とし込む

最初から巨大な QA 回答を 1 回で求めるより、この順番のほうが実務で使える内容になりやすいです。

quality gates は自分たちの stack に合わせて調整する

repository の例には、たとえば次のような checks が含まれています。

• npm run lint
• npm run format:check
• npm run type-check
• npm run test:unit
• npm test
• npm audit
• npm run check:licenses

JavaScript / TypeScript プロジェクトには使いやすい初期値ですが、実際には自分たちの ecosystem に合わせて書き換える必要があります。qa-expert guide の価値は npm command そのものではなく、ステージ別に gate を設計するロジック にあります。

出力品質を実際に上げる依頼の仕方

skill には、次の観点を明示して依頼すると効果的です。

• ビジネス影響順の top 5 risks
• pre-commit、pre-merge、release における具体的な gates
• どの flows を E2E にし、どこを integration tests にすべきか
• 許容 coverage threshold と、一律にすべきでない箇所
• metrics owners と review cadence

ここまで指定すると、qa-expert usage は一般論から抜け出し、チームで運用できる出力に近づきます。

qa-expert skill FAQ

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

はい。プロダクト理解はあるものの、QA の意思決定に構造を持たせたい人には向いています。pyramid、gates、metrics が明確なので、戦略レベルでは初心者にも扱いやすいです。一方で、テストフレームワークをゼロから学ぶ教材として期待すると、やや不向きです。

qa-expert は自動テスト専用？

いいえ。重心は test automation と quality gates にありますが、計画モデル自体は manual validation、release criteria、risk review にも使えます。ただし、最も強い価値が出るのは exploratory testing の伴走というより、qa-expert for Test Automation の戦略設計です。

qa-expert は普通の prompt より何が優れている？

通常の prompt でも広めの testing checklist は出せます。ただ、次のような要件があるなら qa-expert のほうが役立ちます。

• リスクベースの優先順位付け
• 明示的な gate の段階分け
• 再利用できる test-plan 構造
• 継続的に追うべき QA metrics

要するに、単発回答ではなく、繰り返し使える運用モデルを作りやすいのが強みです。

qa-expert が向かないケースは？

次のような用途だけなら、qa-expert は避けたほうがよいでしょう。

• 単一の test case
• 単一バグの再現
• framework 固有の実装詳細
• 既存 CI pipeline に対する、ツール固有の深い監査と remediation

repository の中身を見る限り、実装寄りの自動化よりも、計画とテンプレート支援のほうが強いです。

qa-expert は CI とすぐ連携できる？

直接はできません。gate の例や補助資料はありますが、GitHub Actions、GitLab CI、Jenkins など、実際の pipeline system への落とし込みは自分たちで行う必要があります。

qa-expert は coverage の判断にも使える？

はい。これはこの skill の実用性が高いポイントのひとつです。付属の coverage_analysis.py script で coverage review 用テンプレートを作れますし、戦略面でも、単一の包括的な割合を追うのではなく、critical path と recent change risk を優先する考え方が促されています。

qa-expert skill を改善する方法

qa-expert にシステム文脈をきちんと渡す

qa-expert の出力を最も早く改善する方法は、次の情報を入れることです。

• architecture summary
• critical flows
• external dependencies
• compliance または security の懸念
• 現在の test inventory
• release と incident の履歴

この skill の質は、入力されたリスク像の解像度に大きく依存します。

repository 固有の対応付けを依頼する

「QA strategy を作って」で止めないでください。qa-expert には、推奨事項を次へマッピングするよう求めましょう。

• 実際の services や folders
• 変更頻度の高い modules
• 具体的な user journeys
• 名前付きの CI stages
• 担当チーム

そうすることで、汎用プランが実行可能な計画に変わります。

もっとも多い失敗パターンを修正する

典型的な失敗は、過度に一般化された回答になることです。制約なしで計画を求めると、もっともらしいが汎用的な戦略に寄ります。これを防ぐには、次のような tradeoffs を明示します。

• 限られた engineer time
• 許容できる最大 test runtime
• release frequency
• flaky-suite tolerance
• deploy を block できない modules

tradeoff を入れるほど、優先順位付けは現実的になります。

数字だけの coverage 思考から一段先へ進める

最初の回答が overall coverage の数値ばかりに寄っていたら、qa-expert に次の軸で見直しを依頼してください。

• critical path coverage
• mutation-risk または recent-change areas
• 足りていない integration contracts
• release-blocking scenarios
• defect escape patterns

こうすることで、見栄えのよい vanity metrics ではなく、実際の QA 成果に沿った使い方になります。

初稿のあとに必ず反復する

2 回目の prompt として有効なのは、たとえば次のようなものです。

Revise this qa-expert plan by cutting low-value tests, identifying the three highest-risk regressions, and rewriting the gates for a team that can only maintain 15 minutes of CI time on pull requests.

この種の反復は、単に詳細を増やすより、実用性を高めやすい傾向があります。

参照ファイルを回答の骨組みに使う

出力品質にばらつきがあるなら、回答を次のファイルに沿って構成するよう skill に指示してください。

• references/strategy.md を scope と objectives の骨組みにする
• references/gates.md を release criteria の骨組みにする
• references/metrics.md を team reporting の骨組みにする

これにより、qa-expert skill が generic QA prose に流れず、repository 内で最も強い資料に沿いやすくなります。

テンプレートに自分たちの事例を重ねる

同梱 script が生成するのは、完成済みの分析ではなく document skeletons です。結果を良くしたいなら、次のような実データを貼り付けてから使ってください。

• 最近の incident
• 現在の CI checks
• flaky test list
• feature spec または PRD
• module 単位の coverage snapshot

そのうえで、その証拠を使ってテンプレートを埋めるよう qa-expert に依頼してください。実チームで qa-expert guide の成果を引き上げるうえで、これが最も費用対効果の高い方法です。