# 検証プロファイル (Verify Profile)

本ファイルは**雛形**である．`.claude/verify-profile.md` にコピーし，各節の説明と記入例をこのプロジェクトの内容に置き換えて使う．

```bash
cp .claude/skills/verify/profile-template.md .claude/verify-profile.md
```

`.claude/verify-profile.md` が存在するプロジェクトでのみ，`/verify` と `/implement` の Phase 1b（verifier による検証）が動作する．存在しなければ，検証はスキップされ従来どおり人間が動作確認する．
verifier はプロジェクト固有の知識を一切持たず，**このファイルだけ**を頼りに検証する．書かれていないことは推測されるか，実行されない．

## 使い方 (How to Use)

- コピー後，各節の「説明」（引用ブロック）は消してよい．verifier に読ませたい内容だけを残す
- 記入例は Web アプリと CLI／API の 2 通りを載せてある．該当しない方は削除する．種別は Web に限らない（デスクトップアプリ・バッチ・ライブラリのサンプル実行等でも，同じ枠に載せられる）
- 実行結果の出力先は `.gitignore` に追加する（スクリーンショット・ログ・一時データをコミットしない）
- 検証中に「プロファイルに書いていなかったせいで verifier が間違えた」ことが起きたら，その場で本ファイルに追記する（次回以降の精度が上がる）
- 本ファイルは**プロジェクト所有**であり，`/sync-template` で上書き・削除されない

## 種別・検証手段 (Target & Method)

> 何を，どういう手段で操作して検証するかを 1〜3 行で書く．verifier はここで検証の全体像を掴む．

- 記入例（Web アプリ）: Web アプリケーション．ヘッドレスブラウザ（Playwright ＋ Chromium）でローカルの開発サーバー（`http://localhost:3000`）を操作する．API の確認はブラウザのリクエスト機能で行う
- 記入例（CLI／API）: CLI ツール．ビルド済みバイナリをローカルで実行し，標準出力・終了コード・生成ファイルを検証する．HTTP API はローカルサーバーを起動して `curl` 相当のリクエストで確認する

## 検証対象の環境 (Target Environments)

> verifier がアクセスしてよい環境を書く．**既定はローカルのみ**であり，この節に何も書かなければローカル以外への接続は行われない．
> staging 等の検証用環境を使わせる場合は，接続先を許可リストとして挙げ，**「いじっても影響が無い」と判断した根拠を環境ごとに書く**．
> 判断の主体は人間（プロジェクト側）であり，**根拠の書かれていない環境は許可していないものとして扱われる**（verifier は，ここに無い接続先を見つけても自分の判断で「影響なし」とみなさない）．
> **本番はここに書いても許可されない**（verifier はどんな場合もアクセスしない）．

- ローカルの接続先: `<例: http://localhost:3000（開発サーバー）・localhost:5432（開発 DB）>`
- ローカル以外で許可する環境: `<なし／下表のとおり>`（使わない場合は「なし」と書き，下表を削除する）

| 環境 | 接続先（許可リスト） | 影響が無いと判断した根拠 | 資格情報の受け渡し | テストデータの後始末 |
| --- | --- | --- | --- | --- |
| `<例: staging>` | `<例: https://staging.example.com，https://api-staging.example.com>` | `<例: 本番とは別の DB を使う／実ユーザーがいない／メール・push 通知・課金が無効化されている>` | `<例: .env.verify.staging（.gitignore 済み．値は人間が配置する．検証専用アカウントのみ）>` | `<例: 「テストデータの規約」の接頭辞に従い，ランナーが実行の成否に関わらず物理削除する>` |

- 接続を禁止する環境（拒否リスト）: `<例: https://example.com，https://api.example.com（本番）．どんな場合もアクセスしない>`

※ 許可した環境は他の開発者や CI も使っている可能性があるため，verifier は自分が作った検証用データだけを操作し，環境全体に効く破壊的な操作（DB のリセット・マイグレーション・デプロイ・設定変更等）は行わない（`.claude/agents/verifier.md`）．

## 実行コマンド (Run Command)

> シナリオの置き場所・実行方法・出力先を書く．verifier はここに書かれたコマンドしか実行しない（推測で別のコマンドを試させない）．

- シナリオの置き場所: `<例: .verify/<概要（kebab-case）>/scenario.<拡張子>>`
- 実行コマンド: `<例: node scripts/verify/run.mjs <シナリオのパス>>`
- 出力先: `<例: .verify/<概要>/run-<日時>/>`（`.gitignore` 済み）．実行ごとに別ディレクトリへ出力され，前回の証拠は上書きされない
- 出力されるもの: `<例: result.json（判定の一覧）・*.png（スクリーンショット）・server.log（サーバーログ）>`

※ verifier に許可されているコマンド（`.claude/agents/verifier.md` の `tools`）に含まれない実行コマンドは，実行のたびに許可を求められる．常用するなら `.claude/settings.json` の `permissions.allow` に追加するか，許可済みのランタイム経由で実行できる形にしておく．

## 前提条件と確認方法 (Preconditions)

> 満たされていなければ「検証不能」とする条件と，その確認コマンドを書く．verifier が**自力で解消してよい操作**があればそれも明記する（書いていない操作はしない）．

| 前提条件 | 確認方法 | 満たされない場合 |
| --- | --- | --- |
| `<例: 依存がインストール済み>` | `<例: ls node_modules>` | `<例: npm ci を実行してよい>` |
| `<例: ローカル DB が起動している>` | `<例: <DB の status コマンド>>` | `<例: <起動コマンド> を実行してよい>` |
| `<例: ブラウザ実行環境が導入済み>` | `<例: <バージョン確認コマンド>>` | `<例: 検証不能とし，導入コマンドを人間に案内する>` |
| `<例: 環境変数ファイルがある>` | `<例: ls .env.local>` | `<例: 検証不能（値は人間しか知らないため）>` |

※ 開発サーバーの起動・停止は実行基盤（ランナー）が行う．verifier に手作業で起動させない．

## 認証方法・ロール (Auth & Roles)

> 認証をどう通すか，どのロール・ユーザーで検証できるかを書く．認証が無いプロジェクトは「認証なし」と書く．

- 記入例（Web アプリ）: ヘルパー `launchLoggedIn({ role })` がログイン済みのセッションを返す．`role` は `admin` / `editor` / `viewer` / `null`（未ログイン）．ロールごとに別ユーザーなので，権限の確認はロールごとにセッションを分ける
- 記入例（CLI／API）: `VERIFY_TOKEN` 環境変数にローカル発行のトークンが入る．ランナーが権限違いのトークンを 3 種類用意する
- 認証情報の扱い: **本番の資格情報は使わない**．ローカル以外では，「検証対象の環境」で許可した環境の**検証専用の資格情報だけ**を使う（受け渡し方法も同節に書く）．資格情報を報告に書かない

## テストデータの規約 (Test Data Rules)

> 検証で作るデータの命名・後始末・触ってはいけないデータを書く．**検証データが本番やリポジトリに混入する事故はここの不備で起きる**．

- 命名: 検証で作るデータの名前は必ず `<例: verify->` で始める
- 後始末: ランナーがシナリオ終了後に `<接頭辞>` で始まるデータと従属レコードを**成否に関わらず物理削除**する（論理削除では残る．残ると seed の書き出し等を通じてリポジトリへ混入しうる）
- 触ってはいけないデータ: `<例: シードデータ（既存の組織・ユーザー）は編集・削除しない．更新系の確認は自分で作った verify- データに対して行う>`
- 削除できなかったデータがあれば，verifier は報告の「後始末」に明記する

## 待ち方・操作の癖 (Waiting & Selectors)

> フレームワーク固有の注意点．「待てずに落ちる」「セレクタが当たらない」の原因になる癖をここに書く．

- 記入例（Web アプリ）: 画面遷移はクライアント遷移のため通信の完了では待てない．遷移は URL の変化で待ち，描画は目的の要素の出現で待つ．一覧はローディング表示が消えるのを待つ．固定時間の待機は最後の手段
- 記入例（Web アプリ）: セレクタはロール・ラベル・表示文言で指定する．推測で書かず，対象コンポーネントのソースで実際の文言を確認してから書く
- 記入例（Web アプリ）: 入力エラーをメッセージではなく送信ボタンの `disabled` で表現している画面がある．対象画面の実装を見て検証方法を選ぶ
- 記入例（CLI／API）: 非同期処理の完了は終了コードと出力ファイルの存在で判定する．ログの文言は変わりやすいので判定条件にしない

## 既知のノイズ (Known Noise)

> 不具合と誤認しやすい既知の現象．ここに書いていないものは verifier が不具合として報告する．

- 記入例: 開発モードでは初回描画時にエフェクトが 2 回実行され，1 回だけ失敗するリクエストが記録される（本番ビルドでは起きない）
- 記入例: 計測ツールが挿入するスタイルの影響で，初回描画の差分警告が出ることがある
- 記入例: 初回起動時のみビルドに時間がかかり，最初のリクエストがタイムアウトしやすい（再実行で解消するなら不具合ではない）

## 禁止操作 (Prohibited Operations)

> 検証中に実行してはいけない操作．人間のローカル環境を壊す操作は必ずここに書く．

- `<例: ローカル DB のリセットコマンド（人間の作業データが消える）>`
- `<例: 「検証対象の環境」で許可していない接続先へのアクセス（CLI・MCP 経由を含む）．本番への操作は許可リストに関わらず禁止>`
- `<例: 許可した環境（staging 等）での，自分が作った検証データ以外の更新・削除，および環境全体に効く操作（リセット・マイグレーション・デプロイ・設定変更）>`
- 自分が起動していないプロセスの停止（人間が起動済みのサーバーには触らない）
- `<例: マイグレーションの適用（適用は人間に依頼する）>`

## シナリオのテンプレート (Scenario Template)

> そのままコピーして動く最小のシナリオを載せる．verifier はこれを出発点にシナリオを書く．ヘルパーの引数と，チェックの書き方（アサーションの方法）を必ず含める．

```text
<例: 実際に動くシナリオのコードをここに貼る>

- ヘルパーの一覧と引数（セッションの起動・チェックの記録・アサーション）
- 1 チェック = 「何がどうなるべきか」が分かる名前を付ける
- 失敗しても次のチェックへ進み，成否どちらでも証拠（スクリーンショット・出力）を残す
- 画面を伴わないチェック（API・CLI のみ）の書き方
- 後始末（作成したデータ・起動したプロセス）はランナー側で行うため，シナリオには書かない
```

## 実行基盤の要件 (Runner Requirements)

> 検証を安定させるための，実行基盤（ランナー）側の要件．シナリオの実行・環境の準備・後始末を担うスクリプトをプロジェクト側に用意し，以下を満たすこと（運用で分かった失敗を踏まえた要件であり，満たさないと検証が不安定になったり事故につながる）．

- **判断はエージェント，決定的な処理はスクリプト**に分ける．サーバーの起動・ログイン・結果の集計・後始末をエージェントに毎回手書きさせない
- **後始末はランナーが，シナリオの成否に関わらず確実に行う**（検証データの物理削除・一時ファイルの削除）．エージェントの操作に任せない
- **停止するのは自分が起動したプロセスだけ**にする．プロセス名のパターンで一括終了しない（無関係なプロセスや自分自身を巻き込む）．人間が起動済みのサーバーは使うだけで止めない
- **実行ごとに出力ディレクトリを分ける**（`run-<日時>/` 等）．再実行で前回のスクリーンショット・結果を上書きしない（不具合の証拠が消える）
- **ローカルと，本ファイルの「検証対象の環境」の許可リスト以外の URL・接続先を拒否するガードをスクリプト側に持つ**．本番のホストは拒否リストとしても持ち，許可リストの設定ミスで到達しないようにする．指示書の禁止事項だけに頼らない
- **計測アーティファクト**（検証ツール自身が挿入する設定・スタイル等で挙動が変わる現象）に注意し，見つけたら本ファイルの「既知のノイズ」に追記する
- 前提条件を満たさない場合は，破壊的な復旧を試みずに**明確なエラーメッセージで終了**する（verifier が「検証不能」と報告できるようにする）

## 参考実装 (Reference Implementation)

実行基盤はプロジェクトの認証方式・データストアに強く依存するため，テンプレートには同梱していない．Web アプリ（ヘッドレスブラウザ）向けの実装例は以下を参照する．

- 導入: [rintoHasegawa/KarutaMatcher PR #93](https://github.com/rintoHasegawa/KarutaMatcher/pull/93)
- 検証データ混入の修正（後始末の設計）: [同 PR #94](https://github.com/rintoHasegawa/KarutaMatcher/pull/94)
- 初運用での改善: [同 PR #99](https://github.com/rintoHasegawa/KarutaMatcher/pull/99)

※ 1 回の検証にかかるコストは規模にもよるが小さくない（目安: 10 分前後）．挙動に関係しない変更で走らせないよう，`/implement` の Phase 1b には実行判定がある．