Fork: 0
hasegawa / programming-template
Transfer to URL with SHA Find file
Newer
Older
programming-template / .claude / skills / verify / profile-template.md
@rintoHasegawa rintoHasegawa 27 days ago 14 KB [add] ブラウザ検証（verifier・/verify・/implement Phase 1b）をテンプレート化し検証プロファイルで固有情報を分離
Raw Blame History

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

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

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 アプリケーション．ヘッドレスブラウザ（Playwrighttp://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 はこれを出発点にシナリオを書く．ヘルパーの引数と，チェックの書き方（アサーションの方法）を必ず含める．

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

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

実行基盤の要件 (Runner Requirements)

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

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

参考実装 (Reference Implementation)

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

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