create-verification-skill

検証スキルを作成する

本格的なプロジェクトには、実際のアプリを操作して動作を確かめるスクリプトが必要です。アプリを起動し、ユーザーと同じように機能を試し、その証拠を記録します。このスキルは、リポジトリに合わせてプロジェクト内のスキル（.cursor/skills/verify-<app>/）を生成します。生成した内容は人間向けではなく、次のエージェント向けに作成します。アプリを見たことがないエージェントが、タスクの途中で初めて読むことになります。

1. ユーザーではなくリポジトリに聞く

コードベースから次の点を確認し、観察できないことだけをユーザーに尋ねます。

• 操作面： ユーザーが実際に操作するのは何ですか？ Web UI、CLI/TUI、デスクトップアプリ、API、モバイルアプリ、ライブラリのどれですか？ リポジトリに複数ある場合は、主要なものを選び、ほかも記載します。
• 実行方法： アプリをローカルで起動するにはどうしますか？ リポジトリに記載された開発用コマンドを優先します（パッケージスクリプト、Makefile、README のクイックスタートなど）。ポート、環境変数、シードデータ、認証についても記載します。
• 操作方法： エージェントがプログラムから操作するにはどうすればよいですか？ まず既存のハーネスを確認します。Playwright/Cypress のテスト、expect スクリプト、PTY ヘルパー、curl で呼び出せるエンドポイント、デバッグポートなどです。その後で汎用的な方法を選びます。Web と Electron にはブラウザー/CDP、CLI/TUI には tmux/PTY ハーネス、サービスには通常の HTTP を使用します。
• 観察方法： どのような証拠を記録できますか？ スクリーンショット、ターミナルの記録、レスポンス本文、ログ、終了コード、DB の状態などです。
• 分離方法： 2 つのインスタンスを並行して実行できますか（ポート、データディレクトリ、プロファイルなど）？ できない場合は、生成するスキルにその旨を記載します。共有インスタンスを二重に操作してユーザーのセッションを壊すより、操作を拒否するほうが安全です。

チェックアウトした状態でビルドまたは起動できない場合は、スキルを生成する前に修正するか、問題を正確に報告します。壊れた基盤を前提にスキルを書くと、誤った手順を教えることになります。起動時に、無関係な不足アセット（API が配信しない静的ディレクトリやサンプル設定など）が障害になる場合、生成するスキルでそれらを作成してもかまいません。その場合は検証用の補助ファイルであることを明記し、クリーンアップ時に削除します。

2. スキルを生成する

YAML フロントマター（name: verify-<app> と、アプリ名、対象の操作面、どのようなときに使うべきかを示す description を含めます。フロントマターがないとスキルは登録されません）を付け、実際のインタビューで判明した内容に基づいて、次の各セクションを記述した .cursor/skills/verify-<app>/SKILL.md を作成します（プレースホルダーを残さないでください）。

• Launch： アプリの検証を開始する正確なコマンドと、準備完了を判断する方法（ログ行やプロンプトなど）を記述します。空のデータディレクトリから使用可能な状態まで起動できるようにし、マイグレーションとシードデータも含めます。準備完了とは、プロセスが応答するだけではなく、使用可能な状態であることを意味します。データベースのヘルスチェックが成功しても、初期化スクリプトの実行中である場合があります。終了方法も記述します。短時間で終了する CLI や TUI には、稼働し続けるサーバーはありません。その場合の起動とは、バイナリを一度ビルドする（または依存関係をインストールする）ことを指し、その後、操作を行うたびに専用の PTY または tmux セッションで開始します。
• Doctor： 「このインスタンスを操作する価値があるか」を判断する、読み取り専用のチェックを 1 つ記述します。プロセスの起動状態、正しいバージョン／ビルドであること、ポートがこのアプリによって使用されていること、認証が有効であることを確認します。問題が疑われる場合、エージェントは必ず最初にこのチェックを実行します。
• Drive： サンプルではなく、このリポジトリに実在するセレクター／コマンドを使ったハーネスの手順を記述します。座標やタブ移動順よりも、安定した識別子（ARIA ラベル、データ属性、プロンプト文字列、ルートパスなど）を優先します。
• Evidence： 証明として何を記録し、どこに保存するかを記述します。証明の基準も明記します。内部セッターやテスト専用エンドポイントではなく、実際のユーザーパスを操作すること、最後の画面だけでなく操作とその結果の状態を記録すること、目に見える状態とともに副作用（ファイルの書き込み、行の挿入、メッセージの送信など）も確認すること、本番環境の境界で外部システムがすでに分離されている場合にのみモックを使うことを含めます。安全な方法がドライランやテストモードである場合は、その名前を信頼せず、実際に何が省略されるかを観察して確認します（ファイル、ネットワーク、Git の参照など）。ドライランでもネットワークにアクセスしたり、ブラウザーを開いたりするものがあります。
• Cleanup： 実行時に作成したインスタンスを終了する方法を記述します。プロセス名で強制終了してはいけません。自分が起動したプロセスを終了します。クリーンアップで削除するのはインスタンスと作業用の一時データのみで、証拠は削除しません。証明用の成果物は終了後も保持し、スキル内で指定した場所に保存します。
• Helpers： スキルに含めるスクリプトは実行可能にし、スキル本文に実行方法を記載します。読者がリバースエンジニアリングしなければ使えないものは、ヘルパーとはいえません。

3. 機能マップにシードデータを追加する

.cursor/skills/verify-<app>/features/README.md と、特定できるユーザー向け機能ごとに 1 つのファイルを作成します（ルート、コマンド、メニュー、ドキュメントから判断し、まずは上位 3～5 個を目指します）。references/feature-map-example/ に従い、README の索引と機能ごとのファイルを用意します。各ファイルではユーザーの視点から、機能の内容、アクセス方法、ハーネスを使った操作方法、動作を証明する観察可能な終了状態を説明します。H2 は次の 4 つです。Sub-features、How to get to it (user POV)、Driving it with <harness>、Gotchas。シードデータに必要な前提条件がなく、操作手順が成立しない場合は、失敗を報告し、その理由を該当機能の Gotchas に記載します。合格させるために操作手順の要件を緩めてはいけません。このマップはリポジトリで継続的に管理する検証情報です。マップに複数の入口が記載されている場合、そのうち都合のよい 1 つだけを操作した証明は不完全です。

4. 引き渡す前に、生成したスキルが動作することを確認する

スキル独自の手順を最初から最後まで一度実行します。起動し、診断し、マッピングした機能を1つ操作し（1つで十分です。マップがあるので、後の実行では残りを確認できます）、証拠を記録して、クリーンアップします。クリーンアップ後、証拠が指定された場所に残っていることを確認します。証拠を消してしまうクリーンアップでは、この手順を完了したことになりません。失敗した箇所を修正し、失敗した試行の後も、毎回生成されたクリーンアップを実行します。壊れた試行によってプロセスやポートが残らないようにしてください。一度も実行していない生成スキルは成果物ではなく、草稿です。実際の対象の代わりとなる環境（新しい VM の代わりにコンテナ、リモート環境の代わりにローカルスタック）で動作を確認した場合は、その代替環境で実行したセットアップ手順のうち、実際の対象では行われないものをすべて列挙してください。それらの手順は、実際の対象で実行して確認するまで未検証のままです。

5. メンテナンスの手順を案内する

アプリの変更に合わせてマップを正確に保つため、ユーザーに /maintain-verification-skill を案内します。ユーザーから求められた場合にのみ、実施頻度を提案してください。