create-verification-skill

検証スキルを作成する

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

プラットフォームに関する注意。 生成されるスキルは、Claude Code では .claude/skills/verify-<app>/ に配置します。Codex や別のランタイムでは、そのランタイムのプロジェクトスキル用の場所に配置してください。アプリを操作するハーネス（ブラウザー/CDP、PTY/tmux、HTTP）はプラットフォームに依存しません。ツール名は codex-tools.md で確認してください。

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. スキルを生成する

.claude/skills/verify-<app>/SKILL.md を作成します。YAML フロントマターには name: verify-<app> と、アプリ名、対象とする画面や機能、およびどのような場合に使うべきかを記した description を含めます（フロントマターがないと、スキルは登録されません）。以下のセクションを含め、各項目はインタビューで実際に確認できた内容に基づいて記述します（プレースホルダーを残さないでください）。

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

3. 機能マップを用意する

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

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

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

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

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