create-verification-skill

検証スキルを作成する

Codex では、このスキルに従う前に、スキルごとの注記を含めて プラットフォームマッピング を読んでください。

GitHub Copilot では、このスキルに従う前に、スキルごとの注記を含めて プラットフォームマッピング を読んでください。

Muse では、このスキルに従う前に、スキルごとの注記を含めて プラットフォームマッピング を読んでください。

本格的なプロジェクトにはすべて、実際のアプリを操作して動作を確認するスクリプト化された方法が必要です。アプリを起動し、ユーザーと同じように機能を使い、証拠を記録します。このスキルは、リポジトリに合わせたプロジェクトローカルのスキル（.claude/skills/verify/）を生成します。名前は verify にします。リポジトリのルートでは、この名前のプロジェクトスキルが、ユーザーだけが呼び出せる Claude Code 組み込みの /verify に置き換わるため、ドライバースキルを指定するすべてのプレイブックからプロジェクトスキルを呼び出せます（Claude Code 2.1.200 以降）。モノレポでは、変更したパッケージのディレクトリ内に作成してください。生成するのは、人間向けではなく、次のエージェント向けの手順です。アプリを見たことのないエージェントが、作業の途中で初めて読むことになります。

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 と、アプリ、対象サーフェス、およびこのスキルを使うべき場面を明記した description を含めます。フロントマターがないとスキルは登録されず、disable-model-invocation を指定するとモデルから呼び出せなくなります）を付けて、.claude/skills/verify/SKILL.md を作成します。また、以下の各セクションを、インタビューで実際に確認した内容に基づいて記述します（プレースホルダーを残さないでください）。

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

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

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

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

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

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

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