create-verification-skill

Files (4)

• SKILL.md
• README.md · references/feature-map-example/
• create-note.md · references/feature-map-example/
• search.md · references/feature-map-example/

SKILL.md (first lines)

# 検証スキルを作成する

本格的なプロジェクトには必ず、実際のアプリを操作して振る舞いを証明するスクリプト化された方法が必要です。アプリを起動し、ユーザーと同じ方法で機能を実行し、証拠を取得します。このスキルは、それをリポジトリに合わせたプロジェクトローカルなスキル（`.pi/skills/verify-<app>/`）として生成します。生成物は人間ではなく、次のエージェントのために書いてください。その生成物は、アプリを一度も見たことがないエージェントによって、タスクの途中で事前知識なしに読まれます。

## 1. ユーザーではなくリポジトリに質問する

以下をコードベースから把握し、観察できないことだけをユーザーに尋ねてください。

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

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

## 2. スキルを生成する

`.pi/skills/verify-<app>/SKILL.md` を YAML frontmatter（`name: verify-<app>` と、アプリ、サーフェス、使用すべき状況を示す `description`。frontmatter がなければスキルは登録されません）付きで作成し、以下のセクションを含めてください。各セクションは、調査で実際に判明した内容に基づくものとし、プレースホルダーを残してはいけません。

- **Launch:** 検証用にアプリを起動する正確なコマンドと、準備完了を判断する方法（ログ行、応答するポート、プロンプト）。終了方法も含めます。短時間で終了する CLI や TUI には、維持すべきサーバーはありません。起動とは、バイナリを一度ビルド（または依存関係をインストール）した後、操作のたびに分離された専用の PTY または tmux セッションで開始することを意味します。
- **Doctor:** 「このインスタンスは操作する価値があるか」に答える、読み取り専用のチェックを 1 つ用意します。プロセスが起動しているか、正しいバージョン/ビルドか、ポートを自分たちが所有しているか、認証が有効かを確認します。何かがおかしい場合、エージェントは必ず最初にこれを実行します。
- **Drive:** このリポジトリに実在するセレクター/コマンドを使ったハーネスのレシピを記載します。例を使ってはいけません。座標や Tab 順序ではなく、安定したハンドル（ARIA ラベル、data 属性、プロンプト文字列、ルートパス）を優先します。
- **Evidence:** 証明のために何を取得し、どこに保存するかを記載します。証明の基準も明記してください。内部 setter やテスト専用エンドポイントではなく、実際のユーザーパスを実行すること。最終画面だけでなく、操作とその結果の状態を取得すること。目に見えるものに加えて、副作用（書き込まれたファイル、挿入された行、送信されたメッセージ）も検証すること。mock は、本番の境界ですでに外部システムが分離されている場合にのみ使用すること。安全な経路が dry-run またはテストモードの場合、その名前を信用せず、実際に何を省略するかを観察（ファイル、ネットワーク、git ref）して検証すること。一部の dry-run は、それでもネットワークに接続したりブラウザを開いたりします。
- **Cleanup:** 実行によって作成したインスタンスを終了する方法を記載します。プロセス名で kill してはいけません。自分が起動したものを kill してください。クリーンアップではインスタンスと一時状態だけを削除し、証拠は削除しません。証明用アーティファクトは終了後も、スキルで指定した場所に残します。
- **Helpers:** スキルに同梱するスクリプトには実行権限を付け、呼び出し方法をスキル本文に記載します。読者がリバースエンジニアリングしなければならないヘルパーは、ヘルパーではありません。

## 3. 機能マップの初期データを作る

`.pi/skills/verify-<app>/features/README.md` と、特定できるユーザー向け機能ごとのファイルを作成してください（まずはルート、コマンド、メニュー、ドキュメントから主要な 3～5 個を目標にします）。[`references/feature-map-example/`](references/feature-map-example/) の形式に従い、README の索引と機能ごとのファイルを用意します。各ファイルでは、ユーザーの視点から、機能は何か、そこへ到達する方法、ハーネスで操作する方法、動作を証明する観察可能な終了状態は何か、に答えます。4 つの H2 は `Sub-features`、`How to get to it (user POV)`、`Driving it with <harness>`、`Gotchas` とします。マップは、リポジトリで保守される検証の情報源です。マップに複数のエントリーポイントが記載されている場合、都合のよい 1 つだけを操作する証明は不完全です。

## 4. 引き渡す前に生成したスキルを証明する

そのスキル自体の手順を一度、最初から最後まで実行してください。起動し、doctor を実行し、マップにある機能を 1 つ操作し（1 つで十分です。マップがあるため、後続の実行で残りを網羅できます）、証拠を取得し、クリーンアップします。クリーンアップ後、指定場所に証拠が残っていることを確認してください。証拠を消してしまうクリーンアップは、このステップの失敗です。失敗した箇所を修正し、反復が失敗するたびに生成したクリーンアップも実行して、失敗した試行がプロセスやポートを残さないようにします。一度も実行されていない生成スキルは、成果物ではなく下書きです。

## 5. メンテナンスループを案内する

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

From yasuhito/skills, MIT.

More from yasuhito/skills