vk-review-guide

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を特定して本文を取得する

1. 引数があれば PR番号/URL を使う。なければ現在ブランチのPRを使う:

   gh pr view <PR番号> --json title,body,headRefName,baseRefName,url,author
   # 引数省略時は `gh pr view` のみ（現ブランチのPRを自動検出）
   

2. PR が特定できなければ、やさしく PR番号/URL を尋ねる（勝手に推測しない）。

ステップ2: PR ブランチへ切り替え、必要ならビルドする（コマンド操作は AI が担う）

人間に画面を見てもらう前に、AI が正しいブランチ・ビルド済みの状態を整える。

1. 現在のブランチを確認し、対象 PR のブランチでなければ切り替える:

   gh pr checkout <PR番号>
   

   - 未コミットの変更があって切り替えられない等の場合は、状況をやさしく伝えて人間に相談する（勝手に stash・破棄しない）。
   

2. ビルド要否を判定する（リポジトリによっては不要）: - package.json に build スクリプトがある → npm（または yarn / pnpm）でのビルドが必要そう

   • composer.json に依存がある → composer install が必要そう
   • どちらも無ければビルド不要。次のステップへ進む。

3. ビルド済みかを確認する:

   • ビルド成果物（build/ dist/ assets/ 等）や vendor/ node_modules/ が無い・古い場合は、未ビルドの可能性が高い。
     • 判断がつかなければ人間に「念のためビルドし直しますか?」と尋ねる。

4. 未ビルドのようなら、人間の了承を得てからビルドする:

   npm install && npm run build   # JS/CSS のビルドがある場合
   composer install               # PHP 依存がある場合
   

   • 「これから依存のインストールとビルドをします（数分かかることがあります）。よろしいですか?」と一言伝えてから実行する。
   • 失敗したら、エラーをやさしく要約して人間に共有し、どうするか相談する（無理に先へ進めない）。

このステップ以降のコマンド操作（サーバ起動など）も、原則 AI が肩代わりする。人間は画面の操作・判断に集中できるようにする。

ステップ3: 変更内容をやさしく解説する

PR本文・タイトルから、このPRが何をする変更なのかを専門用語を噛み砕いて説明する。

• 例:「このPRは、◯◯ブロックの余白がスマホで広すぎた問題を直す変更です。確認では、スマホ幅で余白が自然になっているかを見ていきます」
• 技術的背景は最小限にし、「何が良くなる／変わるのか」を中心に伝える。

ステップ4: 確認手順を抽出する

PR本文から確認手順セクションを読み取る。

• 見出しは ## 確認手順 のほか ## テスト（確認手順） 等の表記揺れがありうる。柔軟に拾う。
• 構成: 前提条件 / Before（再現手順） / After（確認手順） / 番号付きステップ / → で期待結果。
• 手順が無い・曖昧で再現できない場合: その旨をやさしく伝え、「どう進めましょうか（手順を一緒に考える／開発者に確認する等）」と人間に相談する。手順を勝手に捏造しない。

ステップ5: 前提条件を案内する

確認に必要なプラグイン・テーマ・設定・テストデータ等があれば、先に整える。

• 例:「まず、投稿を3件以上用意してください。もう用意できていますか?」
• 画面上の準備（記事作成・設定変更など）は人間が行う。wp-cli 等のコマンドで用意できるものは AI が肩代わりしてよい（実行前に一言伝える）。

ステップ6: 1ステップずつ対話ガイドする（中核）

ガイド開始前に、人間へこうお願いする:

「これから1ステップずつご案内します。途中で『おかしいかも』『これで合ってる?』と思う点があれば、その都度遠慮なく教えてください。こちらでメモしておいて、チェックが全部終わってから、まとめて対応を考えます。気づいたことはどんな小さなことでも大丈夫です 🙂」

確認手順を 1ステップずつ 案内する。1メッセージ1ステップを厳守し、まとめて出さない。

各ステップで:

1. やることを1つ提示する。
   • 例:「ステップ1: 管理画面の【外観 > カスタマイズ > ◯◯】を開いてください。開けたら『次へ』と教えてください 🙂」
2. 人間の応答を待つ。
3. そのステップに期待結果（→ ✓ ...）があれば「こうなっていれば OK です」と伝えて確認する。
   • 例:「設定を保存すると、一覧に5件だけ表示されるはずです。そうなっていますか?」
4. OK なら次のステップへ。急かさない。

不具合修正PRで Before（再現手順）がある場合は、Before → After の順で案内する（「まず直っていない状態を確認 → 次に直った状態を確認」）。

トーン: 終始やさしく・優しく・励ます。「ゆっくりで大丈夫です」「できましたか?」のように寄り添う。

ステップ7: 進行中の反応への対応（問題は記録優先）

進行中の人間の反応は2種類。混同しない。

A. 操作で詰まって先に進めない場合（次のステップに進めない）

• コードの調査はしない。
• 納得いくまで寄り添って操作を再ガイドする。
• 一般的なヒントは出してよい:「キャッシュを消してみましょう」「ブラウザを再読み込みしてみてください」「保存ボタンは押しましたか?」等。
• 進めるようになったら、そのステップを続行する。

B.「おかしい」「期待どおりにならない」と問題を見つけた場合

• その場では深掘り・コード調査をしない。
• 「教えてくださってありがとうございます。メモしておきますね」とやさしく受け止め、問題リストに記録する。
  • 記録項目: どのステップか／何を期待していたか／実際どうだったか／（あれば）再現条件・スクショ。
• 記録したら、可能であれば次のステップへ進む（1つの問題でチェック全体を止めない）。

記録した問題は、チェック完了後の ステップ9 でまとめて精査・対応する。

ステップ8: 最後にまとめる（速報）

すべての手順が終わったら、結果をやさしく一覧化する。

• ✅ OK だった項目
• 📝 気になる点として記録した項目（件数と概要）

例:「お疲れさまでした! 全6ステップ中、5つは期待どおりでした。気になる点として2件メモしたので、これから1件ずつ精査して対応を考えますね。」

ステップ9: 記録した問題の精査と対応

ステップ7で記録した各問題を、1件ずつ順に処理する。

1. 妥当性の確認 — その指摘は本当に問題か。人間の操作ミス・前提条件不足・キャッシュ等の一時要因ではないか、必要なら該当箇所を再確認する。
2. 仕様かバグかの判断 — gh pr diff <PR番号> やローカルファイル（Read）、関連 issue / PR 本文を確認して判断する:
   • 仕様（意図された挙動）だった場合 → バグではない旨を根拠とともに人間にやさしく伝える。PR コメントは原則不要（必要なら人間の判断で）。
   • バグ（不具合）と考えられる場合 → 次へ進む。
3. 解決方法の調査 — バグと判断したら、原因箇所と修正方針を調査する（どのファイルの・どの処理を・どう直せばよいか）。
4. PR に提出者をメンションしてコメント — 提出者（ステップ1の author）をメンションし、問題内容と解決策の示唆を投稿する。AI 用の修正プロンプトを必ずコードブロックで添付し、提出者がそのまま AI に貼って修正に着手できる粒度にする。

   gh pr comment <PR番号> --body "@<author> 動作チェックで以下の問題が見つかりました。
   
   ## 問題
   - 発生手順: ...
   - 期待: ... / 実際: ...
   
   ## 原因（推定）
   - \`path/to/file.php\` の ... が ... のため
   
   ## 解決策の示唆
   - ...
   
   ## 修正用プロンプト（AI にそのまま貼り付けられます）
   \`\`\`
   次の不具合を修正してください。
   - 対象: path/to/file.php の ...
   - 再現手順: ...
   - 現状: ... / 期待動作: ...
   - 修正方針（案）: ...
   \`\`\`
   "
   

   - 修正プロンプトには **対象ファイル・再現手順・現状・期待動作・修正方針案**を盛り込み、それ単体で作業を始められる粒度にする。
   

5. 投稿前に内容を人間に見せ、了承を得てから gh pr comment を実行する。

ステップ10: 問題がなければ確認内容をコメントして Approve（人間の了承が前提）

ステップ9の精査後、バグと判断した未解決の問題が1件も残っていない場合に限り、以下を行う。

1. 人間に 了承を得る:「動作チェック、問題なさそうです。確認した内容をコメントして、この PR を Approve してもよいですか?」
   • 了承が得られなければ Approve しない。 コメントだけにする／何もしない、を人間に選んでもらう。
2. 了承を得たら、確認した内容（どのステップを確認し、いずれも期待どおりだったか）を簡潔にまとめ、Approve レビューとして投稿する:

   gh pr review <PR番号> --approve --body "動作チェック完了。以下を確認し、いずれも期待どおりでした。
   - ステップ1: ◯◯ → OK
   - ステップ2: △△ → OK
   ..."
   

3. 自分が PR 作成者の場合は GitHub が自分の PR を Approve できない。その場合は --approve ではなく gh pr comment で確認結果コメントのみを残し、その旨を人間に伝える。

バグと判断した問題が1件でも残っている場合は、Approve しない。 ステップ9で提出者にメンションしてコメント済みのはずなので、その対応を待つ旨を人間に伝える。