検証レイヤー:完了とは証拠があること
変更がコミットされる前に機能することを証明し、次の証明を低コストにするためのチェックを構築します。人間の仕事は、すべての差分を読むことから、「完了」を定義し、証拠を読むことに移ります。あなたの仕事は、その証拠を正直に生成することです。
原則はClaude Codeチームが検証について考える方法(Addy Osmani、2026年11月)に基づいています。references/templates.mdのファイル形式はこのスキル独自のものです。記事は慣行を説明していますが、形式は示していません。
使用するタイミング
- 変更が完了し、「完了」またはコミットしようとしているとき
- ユーザーが「これは機能しますか?」「証明してください」「これを検証してください」と尋ねたとき
- リポジトリにアプリを起動してスモークテストする反復可能な方法がないとき
- ユーザーが機能、リライト、またはマイグレーションに対してどのテストを書く価値があるか尋ねたとき
- レビューまたはテストスイートがユーザーに届くバグを見逃し、ユーザーが次回はそれをキャッチしたいと考えているとき
- テストがフレーキーで、誰かが再試行またはスキップしたいとき
- ユーザーが複数のエージェントを同時に実行したいが、すべての差分を読めないとき
使用しない場合: 他の人の差分を一行ずつレビューするとき(それはレビューであり、検証ではありません)、何も実行できない一行のドキュメントまたはコメント変更、またはカバレッジ数を上げるためのテスト追加。
核となる原則
変更は証拠がそう言うときに完了し、変更は決して自身の判定基準を編集してはなりません。 「テストが通った」というのは、同じ変更がテストを書いた場合、弱い証拠です。強力な証拠とは、変更が触れることのできない何かによってチェックされた、ユーザーが依頼したことを実行中のアプリが行っていることです。
ルール
- 変更を実行する。 実際のアプリを起動し、変更された動作を実行します。これはユニットテストよりも重要です。アプリが起動しないのにユニットスイートが通っているのは、検証の失敗です。
- 3ラウンド、その後人間。 チェックを実行し、失敗したものを修正し、再度実行します。3ラウンド後もチェックが失敗している場合は、証拠とともに停止して人間に引き継ぎます。4ラウンド目を開始しないでください。
- 通すために判定基準を弱めない。 テスト、リントルール、チェックリスト項目、またはREVIEW.mdルールを、それが判定するのと同じ変更で編集、スキップ、削除しないでください。判定基準が間違っている場合は、その旨を伝え、ユーザーが承認する別のコミットで変更します。
- ベースブランチから判定基準を読み込む。 レビュールール、チェックリスト、ゲート設定はデフォルトブランチから取得し、テスト中のブランチからは決して取得しません。
- 証拠は1つのコミットに属する。 古いコミットの検証は新しいコミットについては何も語りません。新しい編集後は、再度検証するか、証拠が古くなったことを報告します。
- 安価なチェックを最初に、かつローカルで。 テスト、ビルド、リントはPRがオープンされる前に実行し、レビュアーの時間内では実行しません。
- 差分がトリガーするチェックリスト項目のみ実行する。 通常は3~10項目が一致します。毎回すべてを実行すると、皆がリストを無視するようになります。
- 各コミットに検証方法をスタンプする。
noneも含む。 正直なnoneは後で検索できます。スタンプがないものは検索できません。 - フレーキーテストはバグです。 スキップしたり、スリープを追加したり、通るまで再試行したりしないでください。根本原因を見つけてください。できない場合は、テストを削除し、その理由を書き留めてください。
- 人間を必要とするチェックはその理由を述べなければならない。 「レビューが必要」は理由ではありません。「セッションファイル形式を変更しました。古いトランスクリプトが読み込めない可能性があります。」は理由です。
- すべての見逃しはルールになり、ルールは剪定される。 すり抜けたバグはレイヤーの穴です。チェックでそれを塞ぎ、もはや価値のないチェックは削除します。
どのテストを書くか
| 状況 | テスト | 証明すること |
|---|---|---|
| ユーザー向けフロー(1つだけテストを書くなら、これを書く) | エンドツーエンド | 実際のユーザーパスが最初から最後まで機能する。失敗はステップ、トレース、スクリーンショットを示し、「タイムアウト」だけではない。 |
| パーサー、エンコーダー、お金、ステートマシン、エッジケースがあるもの | プロパティ(fast-check, Hypothesis, proptest) | あなたが考えなかった数千の生成された入力に対して文が成立する。 |
| すでに機能しているもののリライト、マイグレーション、最適化 | 差異 | 古いバージョンと新しいバージョンが同じ入力に対して同じ出力を生成する。 |
チェックする価値のあるプロパティ:
| プロパティ | 文 |
|---|---|
| ラウンドトリップ | エンコードしてからデコードすると、元のものが返される |
| 不変条件 | 何かが常に成立する(残高がマイナスにならないなど) |
| 冪等性 | 2回実行することは1回実行することと同じ |
| 等価性 | 高速バージョンが、低速で明らかに正しいバージョンと一致する |
差異テストの場合:ランダムまたはサンプリングされた実際の入力を使用し、重要でない差異(空白、キー順序、タイムスタンプ)を正規化し、承認した差異のリストを文書として保持します。
遅いスイートは実行頻度が下がるため、カバレッジが低下します。編集ごとのループを高速に保ち、重いテストはコミットの直前に移動します。
保持すべきもの(編集不可)
- 既存のテスト、リントルール、チェックリスト項目、REVIEW.md、ゲート設定:それらが判定するコミットでは決して変更しない。
- コマンド出力、終了コード、失敗したステップ名とカウント:印刷されたとおりに報告する。
- スタンプ:実際に実行したことを述べる。実行していないのに
e2eと書かない。 - スクリーンショットとトレース:記憶から説明するのではなく、そのまま添付またはリンクする。
方法
A. 変更を検証する(毎回)
-
「完了」が何を意味するかを述べる。 ユーザー側から一文か二文を書く:彼らが何をし、何を見るか。リポジトリに機能マップがある場合は、そのエントリを見つけ、期待される結果を評価基準として使用する。「完了」を述べられない場合は、検証する前に尋ねる。
-
安価なチェックを実行する。 ビルド、リント、型チェック、高速なテスト。失敗を修正する。これがラウンド1です。
-
変更を実行する。 リポジトリの
verifyスキルがあればそれを使用する(変更したコードの近くの.claude/skills/にある)。ない場合は、自分でアプリを起動する。- ウェブ:ブラウザを操作する(Chrome拡張機能、DevTools MCP、Playwright)。
- モバイル:モバイルMCP経由のシミュレーター。
- デスクトップ:コンピューター使用。
- バックエンドまたはCLI:サービスまたはコマンドをローカルで実行し、呼び出す。
変更されたパスと、変更されるべきでない隣接する1つのパスを実行する。スクリーンショット、トレース、または出力をキャプチャする。
-
トリガーされたチェックリスト項目を実行する。 ベースブランチから信頼性チェックリストを読み取る。各項目について、差分に対してトリガーをテストする。一致するすべてのチェックを実行し、結果を記録する。一致した項目を名前でレポートにリストする。
-
不足しているテストを追加する。 上記の表を使用する。新しいテストが変更なしでは失敗し、変更ありでは通ることを確認する。
-
ラウンドをカウントする。 各「チェック実行、修正、再実行」が1ラウンドです。3ラウンド後もチェックが失敗している場合は停止する。何が失敗したか、各ラウンドで何を試みたか、原因の最善の推測を報告する。
-
スタンプして報告する。 コミットメッセージにスタンプを追加する(
references/templates.mdの形式)。レポートには以下を含める:完了の定義、実行したもの、証拠、一致したチェックリスト項目、および理由とともに検証されなかったもの。
B. レイヤーを構築する(リポジトリごとに1回、その後調整)
これらを順番に行う。それぞれが単独で有用なので、ユーザーが望むところで停止してよい。
-
verifyスキル。 それをカバーするコードにできるだけ近い.claude/skills/verify/に配置する(モノレポではアプリごとに1つ持つことができる)。アプリを起動してスモークテストする方法を記録する。信頼する前に数回連続して実行する:高速で、毎回同じ結果を返さなければならない。 -
機能マップ。 ユーザーの観点から機能をリストする。それぞれについて:パス、キーボードショートカット、セレクター、期待される結果。エージェントはガイドおよび評価基準として使用する。
-
最も重要なフローに対する1つのエンドツーエンドテスト。 次に、表が適切と言う場所にプロパティテストと差異テスト。
-
信頼性チェックリスト。 各項目には3つの部分がある:差分から読み取れるトリガー、チェック、およびそれを引き起こしたインシデントまたはPR。インシデントがない場合、項目はない。例:トリガー「セッションストレージまたはメッセージタイプの変更」、チェック「新しいフィールドがそれを持たない古いトランスクリプトから安全に読み込まれるか?」。
-
REVIEW.md。 レビュアーにこのコードベースで注意すべきことを伝える。これを複数ラウンドにわたって1人のレビュアーで調整し、各ラウンドは前のラウンドが見つけたものに基づいて構築される。その上にさらにレビュアーを重ねない。コードオーナーが、自分がフラグを立てるであろうものをフラグできるようになるまで洗練する。
-
ローカルでの強制。 エージェントが終了したときにテストを実行するフック、または合格したスイートを必要とする目標。
-
コミットゲート。 セッションがレビューも検証ステップも実行しなかった場合にコミットをブロックする。3つのモードで展開する。
モード 動作 off何もしない observeブロックしたであろうものをログに記録する。これを最初に実行して、誤検出を見つける。 enforceコミットをブロックする。コミットにはスキップの理由を文書で記載してもよい。1セッションで2回ブロックされた後、次のコミットは通過するため、エージェントがスタックすることはない。
フック、ゲート、またはCIの変更を追加する前にユーザーに尋ねる。これらは全員のコミット方法を変える。
C. 見逃しをルールにする
テストやレビューをバグがすり抜けた場合にこれを使用する。
- パターンを見つけるのであって、バグを見つけるのではない。 人間のレビューコメントとリバートを調べる。候補となるルールは、少なくとも2つのPRに現れ、差分だけで確認できるものでなければならない。
- 反証を試みる。 ルールが間違っているか、広すぎるか、すでにカバーされていることを示すために、3つの独立した試行を実行する。サブエージェントが利用可能な場合は、3つ使用する。ルールが生き残った場合のみ保持する。
- キャッチ可能であったかを確認する。 インシデントを引き起こしたPRを、3つの独立したバグファインダーで再生する。2つ以上がバグを見つけた場合、それは検出可能であり、小さな差分に対する見逃しはREVIEW.mdルールまたはチェックリスト項目になるべきである。
- 人間の承認を得る。 コードオーナーがルールを入れるかどうかを決定する。あなたは提案し、彼らが承認する。
- レビュアーを評価する。 それぞれが一文の解答キーを持つ少数のインシデントケースと、過剰なフラグ付けに対するコントロールとして同サイズのマージされたクリーンな変更のセットを保持する。チューニングセットと別のテストセットを保持する。見つかったものを
Important、Nit、またはPre-existingとタグ付けする。リコールが評価にしか適合しなくなったらチューニングを停止する。 - 剪定する。 テストスイート、チェックリスト、
.mdルールファイルは、誰かがカットしない限り成長するだけである。定期的に、決して発火しないルール、別のルールと重複するルール、またはもはや存在しないコードをガードするルールを削除する。
動作例
リクエスト: 「チャットセッションにpinnedフラグを追加して、ピン留めされたものが最初にソートされるようにする。」
スキルなし:
pinnedをセッションタイプに追加し、ソートを更新しました。ユニットテスト合格。完了。
スキルあり:
完了の意味: ユーザーがサイドバーでセッションをピン留めすると、それが先頭に移動する。再起動後も先頭にある。
実行したもの: ビルド、リント、148のユニットテスト(ラウンド1:ソートコンパレータで2つ失敗、修正;ラウンド2:すべて合格)。リポジトリの
verifyスキルでアプリを起動し、セッションをピン留めし、再起動し、順序を確認。スクリーンショット添付。一致したチェックリスト項目(31中2):
- セッション形式の変更が古いデータを読み込む: この変更前に保存されたセッションファイルを開いた。クラッシュした:
pinnedがundefinedで、コンパレータがエラーをスローした。読み込み時にデフォルトでfalseにすることで修正。ラウンド3:合格。- ソート変更が安定した順序を維持する: ピン留めされていないセッションは以前の順序を維持する。合格。
追加したもの: プロパティテスト「2回ソートすることは1回ソートすることと同じ」と、ピン留め、再起動、順序確認のエンドツーエンドステップ。両方とも修正なしでは失敗する。
検証されていないもの: モバイルレイアウト。このマシンにシミュレーターがありません。
スタンプ:
Verified-By: run, e2e, property, checklist(2)
ユニットテストは合格したが、アプリは既存のすべてのユーザーのデータでクラッシュした。古いファイルに対して変更を実行したことでそれが見つかり、チェックリスト項目がそれを試すように指示した。
提供前の自己チェック
- レポートにユーザー側から書かれた「完了の意味」行がある。
- アプリが起動され、変更されたパスが実行された。またはレポートに理由とともに「未実行」と書かれている。
git diff <base>が既存のテスト、リント設定、チェックリスト、REVIEW.md、またはゲート設定への編集を示さない。もし編集がある場合、それは明示され、独自のコミットにある。- テストを通すために
.skip、.only、xit、sleep、retry、タイムアウトの延長が追加されていない(差分でそれぞれを検索)。 - 一致したチェックリスト項目が名前でリストされ、それぞれに結果がある。
- すべての新しいテストが変更なしで失敗することが確認された。
- ラウンド数が3以下である。3ラウンド目も失敗した場合、レポートは人間に引き継ぎ、コミットしていない。
- コミットメッセージに
Verified-By:スタンプがあり、その中の各単語が実際に実行したものと一致する。 - 証拠は現在の
HEADで収集され、以前のコミットではない。 - すべての新しいチェックリスト項目またはルールは、その背後にあるインシデントまたはPRを命名している。