検証スキルの生成

アプリを起動し、利用者と同じ操作で機能を動かし、証拠を残す手順を、プロジェクト専用のスキル<skills>/verify-<app>/として作る。<skills>は.claude/skills/とする。Claude Codeはここにあるスキルを読み込む。

生成するスキルの読者は人間ではなく次のエージェントである。作業の途中で、アプリを見たことのない状態から読まれる前提で書く。文章の言語はリポジトリの既存ドキュメントに合わせる。

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

次をコードベースから答え、観測できないことだけをユーザーに聞く。

• 操作面: 利用者が触るのは何か。Web UI、CLI・TUI、デスクトップアプリ、API、モバイルアプリ、ライブラリ。複数あれば主なものを選び、残りを記録する。
• 起動: ローカルでどう起動するか。リポジトリが文書化している開発用コマンド（package.jsonのscripts、Makefile、READMEの手順）を優先する。ポート、環境変数、シードデータ、認証を記録する。環境変数がシークレットなら、プロジェクトのop run --env-file .env.tpl -- <command>の仕組みを使い、.envを作らない。
• 操作手段: エージェントがプログラムから操作する方法。既存の仕組み（Playwrightなどのテスト、expectスクリプト、PTYの補助、curlで叩けるエンドポイント、デバッグ用ポート）を先に探す。なければ汎用の手段を選ぶ。WebとElectronはブラウザかCDP（Claudeデスクトップならブラウザペインのツール、ターミナル単体ならPlaywrightやCDPの接続）、CLI・TUIはtmuxかPTY、サービスはHTTP。新しい依存を足す場合は、追加する前にユーザーの承認を得る。
• 観測: 取れる証拠は何か。スクリーンショット、ターミナルの記録、レスポンス本文、ログ、終了コード、DBの状態。
• 分離: 2つのインスタンスを並べて動かせるか（ポート、データディレクトリ、プロファイル）。できないなら生成するスキルにそう書く。共有のインスタンスを二重に操作してユーザーのセッションを壊すより、操作を断る方がよい。

チェックアウトがそのままではビルドや起動ができない場合は、原因を正確に報告し、製品コードを直すかどうかはユーザーの承認を得てから決める。壊れた状態を前提に書いたスキルは、間違った手順を教える。検証に無関係な欠けている資産（APIが配信しない静的ディレクトリ、サンプル設定）が起動を妨げているだけなら、生成するスキルの中で「検証用の足場」と明記して作り、片付けで消してよい。

2. スキルを生成する

<skills>/verify-<app>/SKILL.mdを、YAMLフロントマター（name: verify-<app>と、アプリ名、操作面、使う場面を書いたdescription）付きで書く。フロントマターがないとスキルとして登録されない。次の節を、聞き取りで実際に分かったことだけで埋める。プレースホルダを残さない。

• 起動: 検証用にアプリを起動する正確なコマンドと、準備完了の判定方法（ログの行、プロンプト）。空のデータディレクトリから、マイグレーションとシードデータを含めて使える状態まで持っていく。準備完了とは使える状態のことで、プロセスが応答するだけでは足りない。DBのヘルスチェックは初期化スクリプトの実行中でも通ることがある。終了手順も書く。短時間で終わるCLIやTUIでは、維持するサーバーがない。起動とはバイナリのビルド（または依存のインストール）を1回行うことで、操作ごとに分離したPTYかtmuxのセッションで実行する。
• 診断（doctor）: 「このインスタンスは操作してよい状態か」に答える読み取り専用のチェックを1つ。プロセスが動いている、ビルドや版が正しい、ポートを自分のプロセスが持っている、認証が有効。何かおかしいと感じたら、エージェントは最初にこれを実行する。
• 操作: このリポジトリの実際のセレクタやコマンドで書いた手順。例ではなく実物を書く。座標やタブ順より、ARIAラベル、data属性、プロンプトの文字列、ルートのパスなど安定した手がかりを使う。
• 証拠: 何を取り、どこに置くか。置き場所の既定は対象リポジトリの.tmp/evidence/<task>/で、evidence.mdの形式は~/.claude/references/evidence.mdに合わせる。証明の基準も書く。内部のsetterやテスト専用のエンドポイントではなく、利用者と同じ経路を通す。最後の画面だけでなく、操作とその結果の状態を取る。見た目と一緒に副作用（書かれたファイル、挿入された行、送られたメッセージ）を確かめる。モックは、本番でも外部システムとの境界になっている箇所だけに使う。安全な経路がdry-runやテストモードなら、名前を信じず、実際に何を省いているかを観測で確かめる（ファイル、ネットワーク、gitのref）。dry-runでもネットワークに出たりブラウザを開いたりするものがある。
• 片付け: その実行で作ったインスタンスの終了方法。プロセス名で止めず、自分が起動したPIDだけを止める。片付けで消すのはインスタンスと一時的な状態だけで、証拠は消さない。証拠は、スキルが名指しした場所に残す。
• 補助スクリプト: スキルに同梱するスクリプトは実行権限を付け、呼び出し方を本文に書く。読み手が解読しないと使えないものは補助にならない。Node.jsはbun、Pythonはuvで実行する。

3. 機能一覧を作る

<skills>/verify-<app>/features/README.mdと、利用者から見える機能ごとに1ファイルを作る。最初はルート、コマンド、メニュー、ドキュメントから主要な3〜5機能を選ぶ。形はreferences/feature-map-example/に合わせ、READMEを索引にして機能ごとに1ファイルにする。

各ファイルは利用者の視点で、機能の内容、たどり着き方、操作手段での動かし方、動いたと言える観測可能な結果を書く。H2は次の4つをこの順に置く。英語のリポジトリでは例と同じ英語の見出しを使う。

1. サブ機能（Sub-features）
2. ユーザーからの到達方法（How to get to it (user POV)）
3. <操作手段>での操作（Driving it with <harness>）
4. 注意点（Gotchas）

シードデータに、ある手順の前提が欠けていたら、その手順は失敗と報告し、理由をその機能の注意点に書く。通すために手順を弱めない。機能一覧はリポジトリで保守する検証の正本で、一覧に複数の入口がある機能を1つの入口だけで証明しても、証明は不完全である。

4. 渡す前に生成したスキルを動かす

生成したスキルの手順を最初から最後まで1回実行する。起動、診断、一覧の機能を1つ操作、証拠の取得、片付け。機能は1つで足りる。残りは以後の実行で一覧に沿って確かめる。

片付けのあとで、証拠が指定した場所に残っていることを確かめる。片付けで証拠が消えたら、この段階は不合格である。失敗したら直し、失敗した回のあとにも生成した片付けを実行して、プロセスやポートを残さない。一度も実行していないスキルは下書きであって成果物ではない。

本来の対象の代わりの環境で証明した場合（新しいVMの代わりにコンテナ、リモートの代わりにローカル）は、代わりの環境が行っていて本来の対象では行われない準備を列挙する。それらは本来の対象で実行するまで未検証として扱う。

5. 保守の手順を伝える

アプリの変更に合わせて機能一覧を保つには/maintain-verification-skillを使うと伝える。実行の頻度は、聞かれたときだけ提案する。

生成したファイルのコミットは、ユーザーの依頼か承認を経て、CLAUDE.mdのGitの規則に従って行う。