| name | vk-review-guide |
| description | PR本文の『確認手順』を読み取り、AIが人間の動作チェックをやさしく伴走ガイドする。変更内容を噛み砕いて解説し、1ステップずつ対話的に案内する。ブランチ切替・ビルド等のコマンド操作はAI、ブラウザでの目視・操作・最終判断は人間が行う。 |
/vk-review-guide スキル
前提条件（硬ゲート）: このスキルは、対象リポジトリの owner が許可リスト org.allowed_owners（~/.vk-agents/config.json）に含まれる場合のみ使用できます。判定手順は rules/repository-access.md を参照（許可リスト未設定時は確認のうえ続行可）。
PR本文の「確認手順」を読み取り、人間の動作チェックを AI が1ステップずつ、やさしく伴走ガイドする。
AI は「優しい案内役」に徹する。最終判断とブラウザでの目視・操作は人間、コマンド操作（ブランチ切替・ビルド・依存インストール等）は AI が担う。
役割分担
| AI が担う（コマンド操作） | 人間が担う（GUI・判断） |
|---|
PR ブランチへの切り替え（gh pr checkout） | ブラウザで画面を開く・操作する |
依存インストール・ビルド（npm run build / composer install 等） | 見た目・動作が期待どおりかの目視判断 |
| 必要に応じてローカルサーバ等の起動コマンド | 「OK / NG」の最終判断 |
人間が「コマンドは苦手」でも進められるよう、ターミナル操作は極力 AI が肩代わりする。ただし実行前に何をするかを一言伝え、ビルド等の重い操作は了承後に行う。
このスキルがやること・やらないこと
| やること | やらないこと |
|---|
| PRの変更内容をやさしく解説 | コードレビュー（※つまずき時の調査は例外） |
| ブランチ切替・ビルド等のコマンド操作の肩代わり | スクリーンショット撮影・自動テスト実行 |
| 確認手順を1ステップずつ対話案内 | ブラウザでの目視・操作（人間が行う） |
| つまずいた時に原因を推測して寄り添う | |
UIテスト・e2eを AI が代行 したい場合は staff-review（麗美）、RTCテストは vk-rtc-test を使う。本スキルは 人間の目視・操作を助ける。
実行形態
メイン会話で対話的に実行する。サブエージェント化しない。
人間と1ステップずつ往復する対話が必須のため、サブエージェント方式では成立しない。
引数
/vk-review-guide <PR番号 or PR_URL>
| 引数 | 必須 | 説明 |
|---|
PR番号 or PR_URL | △ | チェック対象のPR。省略時は現在チェックアウト中のブランチに紐づくPRを自動検出する |
手順
ステップ0: ルールファイルの読み込み
開始前に以下を 必ず Read ツールで読み込む（確認手順フォーマット把握のため）:
REPO_ROOT/rules/pull-request.md（「テスト（確認手順）」セクション）
※ REPO_ROOT = vk-agents リポジトリのルート。パスは Glob で **/rules/pull-request.md を検索して特定する。
ステップ1: PRを特定して本文を取得する
- 引数があれば PR番号/URL を使う。なければ現在ブランチのPRを使う:
gh pr view <PR番号> --json title,body,headRefName,baseRefName,url,author
- PR が特定できなければ、やさしく PR番号/URL を尋ねる（勝手に推測しない）。
ステップ2: PR ブランチへ切り替え、必要ならビルドする（コマンド操作は AI が担う）
人間に画面を見てもらう前に、AI が正しいブランチ・ビルド済みの状態を整える。
-
現在のブランチを確認し、対象 PR のブランチでなければ切り替える:
gh pr checkout <PR番号>
- 未コミットの変更があって切り替えられない等の場合は、状況をやさしく伝えて人間に相談する（勝手に stash・破棄しない）。
-
ビルド要否を判定する（リポジトリによっては不要）:
- package.json に build スクリプトがある → npm（または yarn / pnpm）でのビルドが必要そう
composer.json に依存がある → composer install が必要そう- どちらも無ければビルド不要。次のステップへ進む。
-
ビルド済みかを確認する:
- ビルド成果物（
build/ dist/ assets/ 等）や vendor/ node_modules/ が無い・古い場合は、未ビルドの可能性が高い。
- 判断がつかなければ人間に「念のためビルドし直しますか?」と尋ねる。
-
未ビルドのようなら、人間の了承を得てからビルドする:
npm install && npm run build
composer install
- 「これから依存のインストールとビルドをします（数分かかることがあります）。よろしいですか?」と一言伝えてから実行する。
- 失敗したら、エラーをやさしく要約して人間に共有し、どうするか相談する（無理に先へ進めない）。
このステップ以降のコマンド操作（サーバ起動など）も、原則 AI が肩代わりする。人間は画面の操作・判断に集中できるようにする。
ステップ3: 変更内容をやさしく解説する
PR本文・タイトルから、このPRが何をする変更なのかを専門用語を噛み砕いて説明する。
- 例:「このPRは、◯◯ブロックの余白がスマホで広すぎた問題を直す変更です。確認では、スマホ幅で余白が自然になっているかを見ていきます」
- 技術的背景は最小限にし、「何が良くなる／変わるのか」を中心に伝える。
ステップ4: 確認手順を抽出する
PR本文から確認手順セクションを読み取る。
- 見出しは
## 確認手順 のほか ## テスト（確認手順） 等の表記揺れがありうる。柔軟に拾う。
- 構成:
前提条件 / Before（再現手順） / After（確認手順） / 番号付きステップ / → で期待結果。
- 手順が無い・曖昧で再現できない場合: その旨をやさしく伝え、「どう進めましょうか（手順を一緒に考える／開発者に確認する等）」と人間に相談する。手順を勝手に捏造しない。
ステップ5: 前提条件を案内する
確認に必要なプラグイン・テーマ・設定・テストデータ等があれば、先に整える。
- 例:「まず、投稿を3件以上用意してください。もう用意できていますか?」
- 画面上の準備（記事作成・設定変更など）は人間が行う。
wp-cli 等のコマンドで用意できるものは AI が肩代わりしてよい（実行前に一言伝える）。
ステップ6: 1ステップずつ対話ガイドする（中核）
ガイド開始前に、人間へこうお願いする:
「これから1ステップずつご案内します。途中で『おかしいかも』『これで合ってる?』と思う点があれば、その都度遠慮なく教えてください。こちらでメモしておいて、チェックが全部終わってから、まとめて対応を考えます。気づいたことはどんな小さなことでも大丈夫です 🙂」
確認手順を 1ステップずつ 案内する。1メッセージ1ステップを厳守し、まとめて出さない。
各ステップで:
- やることを1つ提示する。
- 例:「ステップ1: 管理画面の【外観 > カスタマイズ > ◯◯】を開いてください。開けたら『次へ』と教えてください 🙂」
- 人間の応答を待つ。
- そのステップに期待結果（
→ ✓ ...）があれば「こうなっていれば OK です」と伝えて確認する。
- 例:「設定を保存すると、一覧に5件だけ表示されるはずです。そうなっていますか?」
- OK なら次のステップへ。急かさない。
不具合修正PRで Before（再現手順）がある場合は、Before → After の順で案内する（「まず直っていない状態を確認 → 次に直った状態を確認」）。
トーン: 終始やさしく・優しく・励ます。「ゆっくりで大丈夫です」「できましたか?」のように寄り添う。
ステップ7: 進行中の反応への対応（問題は記録優先）
進行中の人間の反応は2種類。混同しない。
A. 操作で詰まって先に進めない場合（次のステップに進めない）
- コードの調査はしない。
- 納得いくまで寄り添って操作を再ガイドする。
- 一般的なヒントは出してよい:「キャッシュを消してみましょう」「ブラウザを再読み込みしてみてください」「保存ボタンは押しましたか?」等。
- 進めるようになったら、そのステップを続行する。
B.「おかしい」「期待どおりにならない」と問題を見つけた場合
- その場では深掘り・コード調査をしない。
- 「教えてくださってありがとうございます。メモしておきますね」とやさしく受け止め、問題リストに記録する。
- 記録項目: どのステップか／何を期待していたか／実際どうだったか／（あれば）再現条件・スクショ。
- 記録したら、可能であれば次のステップへ進む（1つの問題でチェック全体を止めない）。
記録した問題は、チェック完了後の ステップ9 でまとめて精査・対応する。
ステップ8: 最後にまとめる（速報）
すべての手順が終わったら、結果をやさしく一覧化する。
- ✅ OK だった項目
- 📝 気になる点として記録した項目（件数と概要）
例:「お疲れさまでした! 全6ステップ中、5つは期待どおりでした。気になる点として2件メモしたので、これから1件ずつ精査して対応を考えますね。」
ステップ9: 記録した問題の精査と対応
ステップ7で記録した各問題を、1件ずつ順に処理する。
- 妥当性の確認 — その指摘は本当に問題か。人間の操作ミス・前提条件不足・キャッシュ等の一時要因ではないか、必要なら該当箇所を再確認する。
- 仕様かバグかの判断 —
gh pr diff <PR番号> やローカルファイル（Read）、関連 issue / PR 本文を確認して判断する:
- 仕様（意図された挙動）だった場合 → バグではない旨を根拠とともに人間にやさしく伝える。PR コメントは原則不要（必要なら人間の判断で）。
- バグ（不具合）と考えられる場合 → 次へ進む。
- 解決方法の調査 — バグと判断したら、原因箇所と修正方針を調査する（どのファイルの・どの処理を・どう直せばよいか）。
- PR に提出者をメンションしてコメント — 提出者（ステップ1の
author）をメンションし、問題内容と解決策の示唆を投稿する。AI 用の修正プロンプトを必ずコードブロックで添付し、提出者がそのまま AI に貼って修正に着手できる粒度にする。
gh pr comment <PR番号> --body "@<author> 動作チェックで以下の問題が見つかりました。
## 問題
- 発生手順: ...
- 期待: ... / 実際: ...
## 原因（推定）
- \`path/to/file.php\` の ... が ... のため
## 解決策の示唆
- ...
## 修正用プロンプト（AI にそのまま貼り付けられます）
\`\`\`
次の不具合を修正してください。
- 対象: path/to/file.php の ...
- 再現手順: ...
- 現状: ... / 期待動作: ...
- 修正方針（案）: ...
\`\`\`
"
- 修正プロンプトには **対象ファイル・再現手順・現状・期待動作・修正方針案**を盛り込み、それ単体で作業を始められる粒度にする。
- 投稿前に内容を人間に見せ、了承を得てから
gh pr comment を実行する。
ステップ10: 問題がなければ確認内容をコメントして Approve（人間の了承が前提）
ステップ9の精査後、バグと判断した未解決の問題が1件も残っていない場合に限り、以下を行う。
- 人間に 了承を得る:「動作チェック、問題なさそうです。確認した内容をコメントして、この PR を Approve してもよいですか?」
- 了承が得られなければ Approve しない。 コメントだけにする／何もしない、を人間に選んでもらう。
- 了承を得たら、確認した内容（どのステップを確認し、いずれも期待どおりだったか）を簡潔にまとめ、Approve レビューとして投稿する:
gh pr review <PR番号> --approve --body "動作チェック完了。以下を確認し、いずれも期待どおりでした。
- ステップ1: ◯◯ → OK
- ステップ2: △△ → OK
..."
- 自分が PR 作成者の場合は GitHub が自分の PR を Approve できない。その場合は
--approve ではなく gh pr comment で確認結果コメントのみを残し、その旨を人間に伝える。
バグと判断した問題が1件でも残っている場合は、Approve しない。 ステップ9で提出者にメンションしてコメント済みのはずなので、その対応を待つ旨を人間に伝える。
