qakit

qakit

AI エージェントが実装したばかりの機能をQA 計画にします。エージェントは可能な限りすべてのチェックを実行して結果を記録し、具体的な手順、インラインのチェックポイント、合格／不合格／スキップのボックスを含む短い手動テスト部分を人に残します。どちらの部分も、一般的なチェックリストではなく、実際にコードで変更された内容を基に作成されます。計画は docs/qa/ に書き込まれるため、人は手動テスト部分を上から順に実行して、機能を承認できます。

人が行うのは判断です。画面は正しく見えるか、モックアップに合っているか、操作の流れは快適か、文面は読みやすいか、といったことです。それ以外はすべてエージェントが担当します。この方法の価値は、差分に基づく規律ある計画を作成できることです。機械で確認できる内容を手動テスト部分に含めないため、その部分は短くなります。

観測可能な合格条件があるものは、人のチェックリストに含めません。たとえば、コマンドの出力、エンドポイントの応答、戻り値、そしてブラウザードライバーが利用可能な場合はページに表示される内容（数値が 7 と表示される、クリックすると /account/orders/ に移動する、検索フィールドが表示されない、幅 375 px で何もはみ出さない）です。エージェント自身がこれらを実行し、計画の最後にある自動検証セクションで結果を報告するため、人は手作業で再実行しなくても確認済みの結果を把握できます。また、エージェントは人が判断する必要のある画面をすべてスクリーンショットに撮るため、手動テストの大部分は画像を見るだけで済みます。

計画は、次元別ではなくセットアップ別に構成します。手動 QA に実際にかかるコストはセットアップにあります。データの再投入、ログイン、アプリを特定の状態にすることなどです。5 つのケースで同じ状態をそれぞれ設定し直させる計画は、ケース数を減らして各ケースに多くの内容をまとめた計画より劣ります。

このスキルが起動するタイミング

ユーザーが何かを作り終えて、手動で検証したいときです。「QA 計画を書いて」「手動テスト計画」「この機能はどうテストすればよい？」「テストのチェックリストを作って」「/qakit」、またはコーディングセッション後の単なる「QA して」などが該当します。qakit は、人が実行する手動テストケースを含む計画を作成します。テストコードは作成しません。プロジェクトに既存のテスト、リント、ビルドのコマンドがあれば実行し、エージェントが検証できるチェックに限って実行中のアプリをブラウザーで操作します。そのため、人が機械で確認できるチェックを繰り返すことはありません（自動チェックを自分で実行するを参照）。ユーザーが新たな自動テスト（ユニット、統合、E2E）を求めている場合は、その旨を伝えて手動テスト計画の作成を中止します。新しい作業のテストは TDD モードの implementkit が担当し、テストがまったくないコードベースには testkit を使います。これらのキットがない場合は、変更箇所のそばにテストを書くという通常の手順を案内します。

手順

1. 機能の範囲を定める

一般的な計画には価値がありません。実際に構築された内容に基づいて計画を立ててください。次の優先順位で情報を集めます。

• セッションのコンテキスト。つまり、ユーザーが何を依頼し、このセッションで何を実装したかです。自分で機能を構築した場合、これが最良の情報源であり、コストもかかりません。エントリーポイントや障害が起きるケースは、差分から読み取るよりも把握できているはずです。
• 変更内容。リポジトリがある場合は、対象となるファイルとコミットを確認するために、git diff --stat HEAD と git log --oneline -10 を実行します。QA 計画は行ではなく、動作（エンドポイント、画面、フラグ、コマンド、状態）を単位に作成します。そのため、まだ把握できていない動作を担うファイル（ルートまたはハンドラー、フォーム、CLI のエントリーポイント、マイグレーション、設定のデフォルト値）のみ、差分全体を読みます。ロックファイル、ビルド出力、ベンダーディレクトリは一切読みません。また、セッションですでに動作を把握しているファイルについても、差分全体を読む必要はありません。
• ユーザー。意図がまだ不明な場合に限ります。機能が本来どのように動作するべきか、また普段どのように操作するか（URL、コマンド、画面、認証情報）を、一度に焦点を絞った質問で尋ねます。聞き取り調査のように質問を重ねないでください。

機能の意図した動作、エントリーポイント、依存関係（サービス、データ、認証、設定）を自分用に書き留めてください。以降の作業はすべて、これらを基盤に進めます。

テスト対象のリビジョンも記録します。git rev-parse HEAD と、git status --porcelain の出力が空かどうかを確認してください。計画書のヘッダーに記載するスタンプと、再利用するすべてのチェック結果は、この2つの値に紐付けます。

差分がデータレイヤー（マイグレーション、スキーマファイル、モデル、クエリ）に触れている場合は、db.md を読み、そこに記載されているすべての手順に従ってください。

変更によって UI にデータが表示され、ドライバーがある場合、またはユーザーからコンポーネントを壊すテストを依頼された場合は、worst.md を読み、そこに記載されているすべての手順に従ってください。

変更に UI が含まれる場合は、ブラウザードライバーを優先順に列挙します。URL を開き、クリックし、ページを読み取り、スクリーンショットを保存できる、PATH 上の CLI ドライバー（command -v playwright-cli で確認）を最初に挙げ、続けてこのセッションで利用できる各ブラウザー自動化 MCP ツールセットを挙げてください（ホスト独自のプレビューブラウザーも対象です）。自動チェックを自分で実行するでは、最初のドライバーを起動し、失敗した場合はリストの次へ進みます。ドライバーがなければ、テスト観点を導き出すの説明に従い、ページのチェックは人間が行います。インストールしてはいけません。verifykit がインストールされていれば、setup がインストールを行います。プロジェクトに DESIGN.md のブレークポイントがある場合は、そこからビューポート幅を読み取ります。ない場合は 1440 px と 375 px を使用します。

プロジェクトで宣言されている場合は、使い捨て可能な対象を特定します。たとえば、playground アプリやローカルデータベースコンテナーのように、ドキュメントに記載されたコマンドで破棄して再構築でき、プロジェクトのエージェント指示ファイルまたは README で使い捨てと明記されている環境と、そのリセットコマンドです。対象が宣言されている場合、その対象に限り、状態を変更するコマンドをエージェントが検証できます。宣言されていない対象を推測してはいけません。使い捨てと宣言されていないローカルデータベースには、誰かの作業データが含まれている可能性があります。

意図した動作、すべてのエントリーポイント、すべての依存関係、リビジョンの組み合わせを書き留め、db.md と worst.md が適用されるか、利用できるブラウザードライバーは何か、またプロジェクトが使い捨て可能な対象を宣言しているかどうかを把握したら、この手順は完了です。

2. テスト観点を導き出す

以下の各観点を確認し、この機能に当てはまるものについて、それぞれ候補となるテストケースを作成します。本当に関係のない観点のみ省略し、その場合は計画書の対象外に理由を記載してください。テスターが、忘れたのではなく検討したうえで対象外にしたと分かるようにします。

• ハッピーパス。 機能が意図どおりに使われる、主要なフローを最初から最後まで確認します。
• エッジケースと境界値。 空の入力、最大値／最小値、1 つずれた境界値、通常とは異なるが有効な状態、重複、Unicode／大きなペイロードを確認します。worst.md が適用される場合は、レンダリングされる各フィールドに最悪ケースの値を追加します。
• ネガティブケース／エラー処理。 不正な入力、認証情報の欠落／期限切れ、依存関係の利用不可、ネットワーク障害を確認します。明確なメッセージを表示し、データを破損させずに、適切に失敗することを確認します。
• リグレッション。 変更によって壊れた可能性のある、周辺の動作（共有コンポーネント、以前のフロー、隣接する機能）を確認します。
• セキュリティと権限。 ロール／所有権のチェック、他のユーザーのデータへのアクセス、インジェクション形式の入力、ログやレスポンスへのシークレットの漏えいがないことを確認します。
• データと状態。 再読み込み／再起動後の永続性、冪等性、正しい作成／更新／削除、孤立した状態や古い状態が残らないことを確認します。差分がデータ層に触れている場合、db.md にデータベースのアサーションを追加します。データ層に触れていない場合は、データベース関連の確認を省略し、他の各項目と同様に 対象外 にその旨を記載します。
• 並行処理とタイミング。 同時操作、二重送信、競合状態、再試行、応答の遅延を確認します。
• 互換性。 UI がある場合は、対象のブラウザー／OS／デバイス、レスポンシブ／モバイルレイアウト、ダークモードを確認します。
• アクセシビリティ。 UI がある場合は、キーボード操作、フォーカス順、スクリーンリーダー向けラベル、コントラストを確認します。
• パフォーマンス。 現実的なデータ量や大量のデータにおける応答性を確認し、明らかな速度低下やリークがないことを確認します。
• 使いやすさ／UX。 人間が判断する必要のある感覚的な部分を確認します。分かりやすい文言、適切なデフォルト、見つけやすい操作、役に立つ空状態／読み込み状態などです。

優先度：テスターが緊急度をすぐに把握できるよう、各ケースに絵文字付きの 3 段階の優先度を付けます。

• 🔴 重大。 リリースに必須です。不合格の場合はリリースを阻止します。
• 🟡 通常。 合格することが望ましい項目です。不合格は実際のバグですが、リリースを阻止するものではありません。
• 🟢 低。 あれば望ましい項目、仕上げ、または影響の小さいエッジケースです。

水増しは避けてください。重複する 10 件より、動作ごとに明確な確認項目が 1 件あるほうが有効です。機能の対象範囲とリスクに応じて件数を調整してください。このステップの最後にできるのは、候補ケースの一覧です。次のステップで、候補を実際に個別のケースへ分けるかどうかを判断します。

人間のみで確認する項目とエージェントで検証できる項目を分けます。 ケースを作成する際は、各チェックポイントを次のテストで振り分けます。スクリプトで評価できるアサーションとして合格条件を書けるか？ 書ける場合は、エージェントで検証できます。これには、コマンド出力、HTTP レスポンス、戻り値のほか、ブラウザードライバーがあればページが公開するすべての要素が含まれます。たとえば、テキストや数値、クリック後の URL、要素の表示／非表示、リンクの href と target、テーマのようなクラスや属性、キーボードのフォーカス順、アクセシブルネーム、コンソールエラー、指定幅での横方向のはみ出しなどです。書けない場合は、人間のみで確認します。画面の見た目が適切か、モックアップと一致しているか、ダークモードで読みやすいか、操作が滑らかに感じられるか、文言が適切か、といった確認が該当します。アプリが観測できない外部への影響（WhatsApp メッセージが届く、決済が完了する、メールが届くなど）や、実際の認証情報または物理デバイスが必要な確認も、人間のみで行います。ブラウザードライバーがなければ、ページの確認も人間のみで行います。状態を変更するコマンド（セットアップ、マイグレーション、削除、リセットなど）は、使い捨て対象であることが明示されている場合に限り、エージェントで検証できます。それ以外では、人間が確認します。

人間のみで行うチェックポイントだけを、計画のテストケースに含めます。エージェントで検証できる項目は自分で実行し、その結果を 自動検証 セクションに記録します。観測可能な合格条件があるチェックを手動ステップとして記載してはいけません。ケースが分割されることもよくあります。数値やリンクはエージェントに任せ、「レイアウトがモックアップと一致しているか」は人間が確認します。UI の計画で人間が確認するチェックポイントは、おおむね 10 件以下を目安にしてください。これを大幅に超える場合は、各項目について再度アサーションテストを行います。

すべての次元に候補ケースまたは 対象外 の記載があり、すべての候補に優先度と「人間のみ」または「エージェントで検証可能」のタグが付いたら、このステップは完了です。

3. ケースをシナリオにまとめる

シナリオとは、1つのセットアップ、その上で実行できるすべてのケース、最後の1回のリセットをまとめたものです。候補となるケースを、それぞれが必要とする開始状態ごとに分類し、次のようにします。

• 開始状態が異なるごとにシナリオを1つ作成します。 同じ状態を必要とするケースは、必ず同じシナリオにまとめます。テスターは1回セットアップし、シナリオ全体を実行して、1回リセットします。
• セットアップとフローの両方を共有するケースは統合します。 3つの動作を確認するために、1つのフローを進みながら3つの点を確認するだけでよいなら、同じ6つの手順をそれぞれで繰り返す3つのケースではなく、チェックポイントが3つある1つのケースにします。失敗箇所の特定はケースではなくチェックポイントで行います。チェックされていないボックスがあれば、ケースの失敗と同じくらい正確に、該当する動作を特定でき、テスターの手間も増えません。これは移動ではなく統合です。統合後のケースにはチェックポイントを3つ設け、3つのケースでそれぞれ説明されていたすべてのアサーションを、ボックスの列として並べるわけではありません。計画ファイルを作成するのチェックポイントのルールにより、絞り込みが単に1段下で再発するのを防ぎます。
• フローが実際に分岐する場合に限り分割します。 つまり、エントリーポイントが異なる場合、または後続のケースが許容できない状態を残すケースがある場合です。
• シナリオ内では、まず読み取り専用、次に状態を変更するもの、最後に破壊的なものの順にします。 他のケースが必要とするレコードを削除するケースは最後にするか、独自のシナリオを設けます。
• 対象となる観点をカバーできる範囲で、シナリオ数を最小限にします。 新しいシナリオを作成するには、本当に異なる開始状態が必要です。「話題が違うように感じる」だけでは不十分です。

シナリオには、その話題（「検証」「エラー処理」）ではなく、開始時の状態（「新規テナント、データなし」「注文が200件ある既存ユーザー」「機能フラグがオフ」）に基づいて名前を付けます。名前を見れば、テスターはすでに適切な状態にあるかどうかを判断できます。

シナリオ内でケースに番号を付けます。TC-<scenario>.<case> の形式にするため、TC-2.3 はシナリオ2の3番目のケースです。

人間のみで実行する候補がすべて、ちょうど1つのシナリオに含まれ、各シナリオに異なる開始状態があれば、この手順は完了です。

計画全体に共通する内容は、シナリオのセットアップには含めません。 ブランチ、ビルド、ベース URL、認証情報、認証トークン、機能フラグ、起動コマンドは、冒頭の環境に1回だけ記載します。各シナリオのセットアップには、そのシナリオに固有の内容のみを記載します。この分離により、セットアップと、それを必要とするケースが対応付けられます。

4. 計画ファイルを作成する

docs/qa/NNNN-qa-<feature-slug>-YYYY-MM-DD.md に、次の連番、短い小文字のケバブケースの機能スラッグ、計画の ISO 作成日を使って書き込みます（例：0012-qa-login-throttle-2026-07-23.md）。連番 NNNN を決めるには、このワークツリー、git worktree list に表示される他のすべてのワークツリー、および origin/HEAD（git fetch origin 後に git ls-tree --name-only origin/HEAD docs/qa/ を実行）にある docs/qa/ を対象に、先頭の4桁の連番が最も大きいものを取得し、1を加えます。該当する連番がなければ 0001 から始めます。並行しているワークツリーで同じ連番を使わないよう、3つすべてを確認してください。リモートがない場合など、確認に失敗したソースはスキップします。git がない場合は、そのディレクトリのみを一覧表示します。連番はディレクトリごとに管理し、再利用しません。後から編集してもファイル名全体は変えず、必要に応じて文書内の日付を更新します。docs/qa/ が存在しない場合は作成します。同じ成果物の QA 計画がすでにある場合は、そのファイルを直接更新し、連番が付いていなくてもファイル名を維持します。

ファイルは次の構成にします（以下の外側のフェンスは、内側の ```sh ブロックを表示するために4つのバッククォートで示しています。実際のファイルでは通常の3つのバッククォートを使用します）。

# QA Plan: <Feature name>

_Generated <date> · against `<commit sha>` (<clean or uncommitted changes>) · covers <brief scope>_

## Summary
- What the feature does, in one short sentence.
- What "working" means, in one short sentence.

## Environment
True for the whole plan. Do this once, before Scenario 1.

- Branch / build under test
- Base URL, credentials, and how to obtain any auth token the calls need
- Feature flags / config

Launch with:

```sh
<launch command>
```

- [ ] Environment ready

## Test cases at a glance

Priority legend: 🔴 Critical · 🟡 Normal · 🟢 Low

| # | Scenario | Test case | Priority |
|------|----------|-----------|----------|
| TC-1.1 | 1: <starting state> | <short title> | 🔴 Critical |
| TC-1.2 | 1: <starting state> | <short title> | 🟡 Normal |
| TC-2.1 | 2: <starting state> | <short title> | 🟢 Low |

## Scenario 1: <starting state>

**Setup.** Run once, for every case in this scenario.

1. <setup action>

```sh
<setup command>
```

- [ ] Setup complete

### TC-1.1: <short title>  ·  🔴 Critical

**Goal.** <one line: what this case proves>

**Steps**

1. <concrete action a human takes>
   - [ ] <one judgment the tester stops to make right here>
     - <what to look at, when the judgment needs a guide; a plain bullet, not a checkbox>
     - <another thing taken in at the same glance>
     - screenshot: `<path>` <light 1440 px · dark 1440 px · light 375 px, as captured>
   - [ ] <a second judgment, only when it's a genuinely separate look>
2. <next action; a command goes in its own block>

   ```sh
   <command to run>
   ```

   - [ ] <what the output or screen must show>

**Result**

- [ ] Pass
- [ ] Fail
- [ ] Skipped

**Notes.** _what actually happened on a fail; why it was skipped_

### TC-1.2: <short title>  ·  🟡 Normal
...

**Reset.** Run after every case above, before moving to Scenario 2.

```sh
<reset command>
```

## Scenario 2: <starting state>
...

## Automated verification (by AI agent)
_Checks the agent ran itself. No action needed from the tester; listed here for context and sign-off._

Commands run (one per block; chain with `&&` when they must run together):

```sh
<command 1>
```

```sh
<command 2>
```

- ✅ <command 1> → <what the output confirmed>
- ✅ <endpoint / assertion checked> → <result>
- ❌ <anything that failed, with the actual output> _(if any)_

### Browser checks
_Driven with `<driver>` against `<base URL>` at `<revision>`. Screenshots in `<screenshot directory>`._

- ✅ <page> · <what was asserted> → <the observed value>
- ❌ <page> · <what was asserted> → <the observed value, and what was expected>

## Not covered / needs human judgment
- <anything that can't be scripted: visual polish, UX feel, external integrations, timing>
- <dimension deliberately skipped, and why>

## Overall result
_Tick one when you finish the run, or skip the ticks. Report each failure in the agent session or as a PR comment, and the agent records it here._

- [ ] Pass: every case passed
- [ ] Fail: at least one case failed
- [ ] Partial: cases were skipped or not reached

適切なケースのルール：

• すでにわかっていることを、テスターに転記させないでください。 ヘッダーのスタンプには日付と、計画の作成対象となった正確なコミットが記載されます。git log から両方を自分で記入し、人が SHA を転記するための空欄の表を残さないでください。計画でテスターに求めるのは、機械には判断できない唯一のこと、つまり全体の判定だけです。スタンプとは異なるビルドで実行することになった場合は、どの計画にも永遠に空欄のままあるフィールドではなく、ケースの Notes に記載します。

• 全体の結果は最後、ファイルの末尾に置きます。 テスターは実行が終わったときにチェックを入れます。そして実行は計画の末尾で終わります。上部に判定欄があると、完了したすべてのケースを振り返るためにスクロールして戻る必要が生じ、チェックが入らないままになります。

• ケース本文は常に固定の4項目をこの順序で記載します。 Goal、Steps、Result、Notes です。省略する項目も、5つ目を追加するケースもありません。テスターはどの計画のどのケースに移動しても、同じ形式を見つけられるべきです。

• Goal は1行で、ケースが何を行うかではなく、何を証明するかを記載します。 「期限切れのトークンでは他のテナントの注文にアクセスできない」は適切ですが、「注文エンドポイントをテストする」は適切ではありません。

• 検証は、それを生じさせる手順の下に記載します。 ケースの末尾に期待結果の一覧を別途設けないでください。各手順の直後に、その手順固有の - [ ] チェックポイントを記載します。そうすれば、テスターは5つの期待結果を覚えて最後に照合するのではなく、進めながらチェックできます。観察するものがない手順には、チェックポイントを設けません。

• チェックポイントはアサーションごとではなく、判断ごとに1つです。 チェックポイントとは、機能がアサートする事実ごとではなく、テスターが立ち止まって判断する項目のことです。判断の基準は次のとおりです。1つ目にチェックを入れ、次の項目には入れないということがありそうでしょうか。 ひと目で両方を判断するなら、チェックポイントは1つです。テスターの注意が追いつかない粒度にしても精度は上がらず、精度があるように見せかけるだけです。1ページを一度スクロールする間に、7つの独立した判断をする人はいません。そのため、7つの項目すべてに形だけチェックが入り、実際にはなかった7つの確認として扱われます。

• 異なる判断は分け、ひとつの判断を一連の項目に適用する場合はまとめます。 「フッターの見出し、リンク、区切り線、著作権表示がすべて読みやすい」は、同じ領域を一度見るだけなのでチェックポイントは1つです。「アイコンが月に変わった」と「ストレージに dark が保存された」は、見る場所が異なるためチェックポイントは2つです。基準となるのは「および」という言葉ではなく、テスターの視線を移動させる必要があるかどうかです。

• 詳細はチェックポイントの下に、チェックを入れない通常のサブリストとして記載します。 何を見るべきかを明記する価値はあります。「ページを確認する」だけではなく、料金表で最も消えやすいのは注目プランだとわかるからです。ただし、詳細項目ごとにチェックを入れる必要はありません。

  1. Set the state to `light`. Scroll the whole page top to bottom at ≥1280px.
     - [ ] Every block reads correctly, with nothing illegible and nothing invisible on its own background
       - navbar: sticky background opaque; logo, links and control legible
       - hero: heading, sub-copy, both buttons; primary label against the primary fill
       - pricing-table: the toggle in both positions; the featured plan distinguishable; check marks
       - footer: headings, links, separator rule, copyright
  

失敗箇所の特定が崩れないのは、Notes がすでにあり、失敗したチェックポイントにはいずれにせよメモが必要だからです。この非対称性が目標です。合格時には手早く実行でき、失敗した箇所だけ詳しい確認が必要になる計画にします。

• 繰り返しの確認では、チェックポイントを1つ設け、新しい項目だけを追加します。 2つ目のバリエーションで、テスターがすでに実行した一連の確認を再実行する場合（別の配色、2つ目のブラウザー、次のブレークポイント、切り替えたプリセットなど）、同じ項目を再び列挙しないでください。「上記と同じ、<variant> で」とは絶対に書かないでください。 独自の観察内容がない行は、人が手作業でチェックを入れるループカウンターにすぎません。

  2. Set the state to `dark`. Scroll the page again.
     - [ ] The same sweep is clean in dark
     - [ ] Nothing is pure-black-on-dark where a muted token was intended
  

• チェックボックスは1行に1つずつ置きます。 - [ ] は行頭にある場合のみ、クリック可能なチェックボックスとして表示されます。[ ] Pass [ ] Fail のように同じ行に書くと、どのプレビューアーでも単なる文字列として表示され、テスターが手作業で編集しなければなりません。このルールは、Resultの3つの結果、各ステップのチェックポイント、EnvironmentとSetupのチェックボックスにも適用されます。例外なく1行に1つずつ置き、縦のスペースを節約するために横並びにしないでください。
• 内部状態ではなく、観察できる内容を書きます。 テスターが確認できない状態ではなく、テスターが目で見たり測定したりできる内容を書きます。
• 見た目に関する判断は、それぞれ対応するスクリーンショットを示します。 画面の見た目に関するチェックポイントには、自動チェックを自分で実行するで撮影したパスを記載する、screenshot: のサブ項目をプレーンテキストで付けます。バリエーションごとに1つずつ指定します。これにより、テスターはほとんどの画面を画像で判断でき、動き、感触、実際の操作を確認する場合にのみアプリを開けばよくなります。ドライバーを実行していない場合は、サブ項目を付けません。
• 具体的で再現可能な内容にします。 「ログインをテストする」ではなく、「[email protected] と空のパスワードを入力し、Sign inをクリックする」のように、実際の値と正確な手順を書きます。
• スキップも正式な結果として扱います。 ResultにはPass、Fail、Skippedを1行に1つずつ用意し、理由はNotesに記載します。環境がなかった、依存関係が停止していた、または時間切れでテスターが実行できなかったケースは、誰も着手しなかったケースと区別できなければなりません。何も記載されていない計画書を次の読者に渡しても、何も伝わりません。
• 計画書全体を手順書の文体で書きます。 テスターは作業中、時間に追われていることも多いため、Goal、Setup、Reset、Steps、チェックポイント、Not coveredを含め、計画書全体をASD-STE100 Simplified Technical Englishで書きます。1文に指示を1つだけ記載します。手順を説明する文は20語以内、描写する文は25語以内にします。能動態と現在形を使い、動作の主体を明記します（「リダイレクトが発生します」ではなく「アプリは/loginにリダイレクトします」）。冠詞は省略しません。比喩、慣用句、複数の意味を持つ語は使いません。短い文と箇条書きのサブリストを使い、段落は避けます。対象ごとに用語を1つ選び、計画書全体で統一します。 たとえば、Setupでcartと呼ぶなら、後のステップでbasketと呼んだり、チェックポイントでorderと呼んだりしません。2つの単語が同じものを指すとテスターに考えさせてしまうと、どちらの語も信用されなくなります。このルールは1つの計画書内に適用されます。別の文書では異なる語を使ってもかまいません。
• 未確認の範囲を正直に記載します。 意図的に省略した項目も含め、計画書で検証できない内容はNot coveredに列挙し、網羅できているかのように見せかけないでください。
• コマンドは1つずつ専用の```shコードブロックに記載します。 ターミナルコマンドを文章や表のセルにインラインで記載したり、1つのブロックに複数のコマンドを並べたりしないでください。そうすればテスターは、プレビューアーのコピーボタンを1回クリックするだけで各コマンドをコピーできます。複数のコマンドを続けて実行する必要がある場合は、1つのブロック内の1行に&&でつないで記載し、コピーして貼り付けるだけで一連のコマンドを実行できるようにします。
• APIエンドポイントごとに、実行可能なcurlを記載します。 ケースやチェックでHTTPエンドポイントを呼び出す場合は、リクエストを文章で説明するのではなく、正確なcurlコマンドを専用の```shブロックに記載します。メソッド、完全なURL（ローカルのベースURL、またはEnvironmentで定義した$BASE_URL）、必須ヘッダーすべて、具体的な値を使ったJSONボディを明記し、テスターが推測する必要のある<placeholders>を使わず、コピーしてすぐに実行できるようにします。チェックポイントでステータスコードを確認する場合は、-i（または-s -w '\n%{http_code}\n'）を使います。これはQA作業を最も大きく効率化する方法です。テスターがリクエストを組み立て直すのではなく、そのまま実行できます。

このステップは、ファイルが所定の連番パスに存在し、すべてのケースに4つの本文パートがそろい、すべてのコマンドとcurlがそれぞれ専用のブロックに記載されていれば完了です。

5. 自動チェックを自分で実行する

引き継ぐ前に、テストの観点を導き出すで切り分けた、エージェントが検証可能なチェック、つまりターミナルコマンド、エンドポイントへのアクセス、戻り値のアサーションを実際に実行し、それぞれの結果を計画の自動検証セクションに記録してください（✅ 成功した場合は出力で確認できたこと、❌ 失敗した場合は実際の出力）。HTTP 経由でアクセスしたものについては、人がリクエストを組み立て直さずに再実行または調整できるよう、実行した正確な curl コマンドを専用の ```sh ブロックに貼り付けてください。計画のうち、エージェントが完了するのはここだけで、人が完了するものではありません。シェルやファイルシステムが使えない場合は、その旨を伝え、セクションは人が記入できるよう空けておいてください。

実行するものとその理由。 既存のプロジェクト独自のテスト、lint、ビルドコマンド、該当する場合は db.md に定義された読み取り専用チェック、および以下のブラウザチェックを実行してください。これらは機械で確認できるチェックなので、実行して人の作業リストから外します。新しいテストを書いたり、テストファイルを編集したりしないでください。操作を伴うブラウザチェックは計画に記載し、テストスイートには追加しません。

決して実行しないコマンドの種類と、再実行せずに再利用するもの：

• 禁止：状態を破壊または再構築するものすべて。 たとえば、*:destroy、*:reset、ティアダウンと再スキャフォールド、データベースへの書き込みや削除、ビルドを消去する clean などです。各シナリオ固有のセットアップブロックとリセットブロックもすべて含まれます。これらは人が実行するために書かれたものであり、エージェントは実行しません。内容を説明するにとどめ、実行しないでください。環境についての計画を作成しているのであって、環境を管理しているのではありません。また、状態をリセットする QA エージェントは、人がこれからテストしようとしていたビルドそのものを消去しかねません。唯一の例外は、以下に示す、使い捨てと宣言されたターゲットです。
• 再利用：このリビジョンですでに成功が記録されているゲート。 これは、機能の範囲を定めるで記録したものと同じ HEAD sha、および同じダーティ状態を示すテスト、ビルド、lint、verify の結果を指します。何の結果だったか、実行したリビジョン、成功したことを記録してください。再実行しても同じ結果を得るために、最も高いコストをもう一度払うことになり、この手順がパイプラインで最も高コストになる一般的な原因です。リビジョンが記載されていない結果や、異なる sha またはダーティ状態の結果は再利用できません。ゲートを実行してください。テスト対象の変更がそのゲート自体に関わる場合も、実行してください。

どちらのルールも同じ考え方です。あるものを調べ、再現しないでください。 良いケースを書くためにビルド済み成果物が必要なら、すでにあるものを読んでください。

使い捨てターゲットでのシナリオ。 機能の範囲を定めるで使い捨てと宣言されたターゲットが見つかった場合、セットアップ、手順、リセットのすべてがそのターゲットだけに作用する各シナリオを、自分で実行してください。

• 最初にターゲットを伝えます。 最初のコマンドを実行する前に、ターゲットとそのリセットコマンドを1行で示し、担当者が停止できるようにしてください。
• シナリオを記載どおりに実行します。 セットアップを実行し、続けて各ケースのコマンドを順番に実行し、その後リセットを実行します。ターゲット外では何も実行せず、別のホスト、別のデータベース、または共有サービスにアクセスするコマンドに到達したら、シナリオを停止してください。
• ケースに証拠を記録します。 確認した各チェックポイントにチェックを付け、ケースの結果にもチェックを付け、チェックポイントを証明する行だけに絞った実際の出力をメモに記載してください。シナリオの見出しに · run by the agent on <target> at <revision> を付けてください。
• ターゲットをクリーンな状態にします。 最後のシナリオでターゲットを変更した場合は、最後に宣言済みのリセットコマンドを実行し、その実行結果も記録してください。

これらのシナリオはケースとして計画に残し、自動検証には含めません。レビュー担当者が確認する記録は、その出力だからです。ターゲットが使い捨てと宣言されていないコマンドケースは、手動で実行します。

ブラウザチェック。 機能の範囲を定めるでブラウザドライバーが見つかった場合は、実行中のアプリを操作し、各ページのアサーションをブラウザチェックに記録してください。worst.md が該当する場合は、対象範囲の各画面についても、そこに記載されたモック、再読み込み、アサーションのループを実行してください。

• アプリにアクセスします。 ベース URL をすでに提供している開発サーバーを再利用します。そうでない場合は、プランの起動コマンドで一度だけ起動し、チェックが終わったら停止します。状態に到達するために、宣言済みの破棄可能なターゲット以外では、Setup、Reset、seed、migration を実行しません。それ以外の場所で必要となるチェックは、手動チェックポイントのままにします。
• ローカルの状態だけを操作します。 作成、削除、送信、支払い、送信を行うクリック操作は、アプリ経由で実行します。サンプルデータまたはデモデータを使ったローカルサーバー、あるいは宣言済みの破棄可能なターゲットに対してのみ操作します。それ以外のホストでのチェックは、手動のままにします。
• アサーションを行い、観測した値を記録します。 「✅ /account/ · アクティブな注文カード → 7」は、「✅ 数値は正しい」よりも多くのことを証明します。❌ には、ページに表示された内容とプランの想定を記録します。
• 人が確認する画面をキャプチャします。 人だけが判定する各チェックポイントについて、変更が対応する各バリアントでスクリーンショットを撮ります。ライトモードとダークモード、およびレスポンシブページの場合は機能の範囲を決めるで指定された各ビューポート幅が対象です。${TMPDIR:-/tmp}/qakit/<plan file name without .md>/ に保存し、リポジトリ内には保存しないでください。各チェックポイントにスクリーンショットのパスを記載します。
• CLI ドライバーはコマンド間もバックグラウンドでブラウザーを起動したままにするため、チェックが終わったらブラウザーを閉じます。

ドライバーの起動に失敗した場合は、そのエラーをブラウザーチェックに一度だけ記録し、リストの次のドライバーを試します。すべてのドライバーが失敗した場合は、ページのチェックを手動ケースに戻し、引き継ぎ内容に各エラーを記載します。起動させるためにドライバーのサンドボックスやセキュリティ設定を変更しないでください。変更するかどうかはオペレーターが決定します。

❌ は、人が見つける必要のなくなった不具合です。qakit はコードを書かないため、修正しないでください。引き継ぎ内容の最初に記載します。

テストの次元を導き出すにあるエージェントが検証できるチェックすべてに、✅ または ❌ の行、あるいは再利用した結果のリビジョンを明記した行があり、破棄可能なターゲットでの各シナリオにチェックマークと出力があり、ターゲットがリセットされ、人だけが確認するすべてのビジュアルチェックポイントにスクリーンショットがあるか、その理由がプランに記載され、起動したブラウザーやサーバーが動作していない状態になったら、このステップは完了です。

6. 引き継ぐ

このセクションは手順を示す文体で書きます。1 文につき指示を 1 つ、能動態、現在形とし、比喩は使いません。

次の 3 つの短い項目で締めくくります。

• 失敗を最初に記載します。 ブラウザーまたは自動チェックが失敗した場合は、ほかの内容より先に、観測した値とともに各 ❌ を列挙します。
• 変更内容を記載します。 1 行で要約します。シナリオ数と手動チェックポイント数（🔴 重要なものの数も含む）、自動チェックおよびブラウザーチェックの結果を記載します（例：「2 件のシナリオ、7 件の手動チェックポイント、うち重要なものは 2 件 · 6 件のコマンドと 41 件のブラウザーチェックを実行、1 件失敗 · シナリオ 3 はエージェントがプレイグラウンドで実行し、実行後にリセット済み」）。手動ケースにチェックマークを付けていないことを明記します。人には、失敗をセッション内または PR コメントで報告するよう伝えます。ファイルにチェックマークを付けるかどうかは任意です。
• 保存先を記載します。 プランのパス docs/qa/<file>、プランを作成した対象のリビジョン、スクリーンショットのディレクトリを記載します。
• 次の手順を記載します。 ❌ がある場合は、まず implementkit で修正し（それ以外の場合は手作業で修正し）、その後 qakit を再実行します。❌ がない場合は、prkit で PR を開き、PR のテストプランから QA プランへリンクできるよう docs/qa/<file> を渡します。prkit がない場合は、gh pr create を実行し、本文にプランのパスを記載します。

手動ケースに、自分で合格の印を付けないでください。実行するのは人です。エージェントが記入するのは、自動検証セクションと、破棄可能なターゲットで実行したシナリオだけです。それ以外は記入しません。prkit に引き継ぎます。呼び出してはいけません。

注意事項

• シェルの使用範囲。 qakit は、変更内容の確認と、プロジェクト独自の検証チェックの実行に限ってシェルを使用します。計画の根拠とするための git diff／git log と、自動チェックを自分で実行する に記載された自動チェック（プロジェクトのテスト、リント、ビルドコマンド、ローカルまたは接続先を確認済みのホストでの読み取り専用のデータベース調査、ローカルの開発サーバーに対するブラウザードライバー）を実行します。実行したすべてのコマンドは、計画の 自動検証 セクションに表示されるため、ユーザーは何が実行されたかを正確に確認できます。リモートコードの取得、認証情報へのアクセス、破壊的な操作は行いません。また、同じリビジョンの結果であることを明示できる場合に限り、ゲートの結果を再利用します。詳しくは、自動チェックを自分で実行する の2つのコマンドルールを参照してください。検証手順で状態の変更や昇格されたアクセス権が必要になる場合は、実行せず、人間が行う手順として説明してください。
• テストスイートではなく、計画です。 qakit の出力は QA 計画で、自動チェックの結果を記入し、手動テスト項目は人間が実施できるよう未実施のままにします。ユニットテスト、統合テスト、E2E テストは作成しません。プロジェクトに既存のテストスイートを実行し、この計画のためにブラウザーを操作します。
• ブラウザー MCP は allowed-tools の対象外です。 Bash で playwright-cli などの CLI ドライバーを使用できます。ブラウザー MCP はサーバーが決めた名前のツールとして提供されるため、allowed-tools を厳密に適用するホストでは、qakit がそれらのツールを使えるよう許可する必要があります。許可されていない場合、qakit はドライバーなしで実行され、ページのチェックは手動のままになります。新しい自動テストは、新規作業では implementkit（TDD モード）に、テストのないコードベースでは testkit に任せてください。どちらもインストールされていない場合は、特定のスキルがあると仮定せず、通常の手順を明記してください。
• ファイルシステムもシェルも使えない場合 ファイルを書き込むことも、差分を読むこともできません。その場合は、変更内容を貼り付けるか機能を説明するようユーザーに依頼し、完成した計画を、ユーザー自身で保存できるよう、標準の docs/qa/NNNN-qa-<feature-slug>-YYYY-MM-DD.md パスとともにコードブロックで出力してください。ユーザーの QA 計画を一覧表示できない場合は、0001 を使用してください。