Communityコーディング&開発github.com

proof-it-works(証明して完了)

変更が実際に動作することを証明してから完了と主張するためのスキル。実際の画面やAPIを駆動し、再現可能な証拠を取得し、証拠がない場合はFAILとして閉じます。

proof-it-works(証明して完了) とは?

このスキルは、開発作業が「完了した」と宣言される前に、その変更が実際に動作することを機械的に検証可能な形で証明するための厳格なゲートです。従来の「動くはず」「コンパイルが通った」といった主張を排除し、実際のAPI応答、UIレンダリング結果、データフローのスナップショットなど、再現可能な証拠(アーティファクト)の提出を必須とします。主にClaude CodeやCursorなどのAIエージェント向けに設計されており、`/proof-it-works` コマンドで明示的に起動できます。このスキルは、証拠のレベルを「主張」「アーティファクト」「アーティファクト+逆方向ケース」の3段階に分類し、最低でも1つの肯定証拠と1つの逆方向ケース(変更前は通るが変更後は拒否される入力)の提出を要求します。また、証拠が不足している場合は `FAIL`、技術的に検証不可能な場合は `UNAVAILABLE/BLOCKED` と判定し、ユーザーによる明示的な承認がない限り `PASS` を許しません。これにより、開発プロセスにおける「完了」の質を大幅に向上させます。

対応~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/fan56/skills/tree/main/public/proof-it-works

Installed? Explore more コーディング&開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

ドキュメント

Proof It Works(証明して完了)

このスキルは、作業が「完了」と呼べるかどうかを判断する単一の決定権を持ちます。これはアドバイスではなく、ハードゲートです。

1. 基本法則: 完了 = 証明済み

  • 主張は証拠ではありません。別のエージェントが検査できる再現可能なアーティファクトだけが証拠となります。
  • セクション6の必須ゲート項目が1つでも欠けている場合、「完了」「修正済み」「テスト通過」「リリース済み」とは言えません。
  • 「動くはず」「正しそう」「理論的には問題ない」「コンパイルが通る」は完了状態ではありません。
  • 証明が不可能な場合は、PASS ではなく UNAVAILABLE/BLOCKED(セクション7)を宣言してください。書面によるユーザー放棄は FAIL を FAIL-WAIVED(セクション7)としてクローズできます。機械テスト不可能な次元は PENDING USER のままとし、ユーザー承認により PASS-BY-USER(セクション7)としてクローズできます。これら3つ(FAIL-WAIVED、PENDING USER、PASS-BY-USER)のみが非機械証拠による終了方法であり、いずれも PASS ではありません。
  • 証拠は、ワーキングツリーとレポート(セクション3、Change ref)で指定された変更コミットから取得する必要があります。古いアーティファクトは無効です。
  • このスキルは、ランタイムサーフェスまたはデザイン成果物がある作業にのみゲートをかけます。そのような作業に対しては、最小証拠セット(1つの肯定証拠+1つの逆方向ケース)が、より軽いチェックを置き換え、積み重ねません。ランタイムサーフェスがない作業は対象外であり、このスキルは完全に放棄します。ユーザーがすでに最小限として承認した成果物を上書きしません。

2. 証拠レベル

厳密な順序で3つのレベル:Claim(主張)(口頭または推論、証拠ゼロ)< Artifact(アーティファクト)(このタスクのサーフェスからの実際の生アーティファクトファイル)< Artifact + reverse case(アーティファクト+逆方向ケース)。ゲートが受け入れるのは後者の2つだけです。どの項目にどのレベルが必要かは、選択されたプロファイルのゲート項目によって設定され、グローバルルールではありません。Claim が PASS をサポートすることはなく、どの項目も実際の状態より高いレベルにラベル付けしてはいけません。

3. バインディング / タスクバインディング

  • report.md の先頭に、ユーザーのリクエストから受理目標を定義する文をそのまま引用してください。「XをYに変更して証明せよ」という指示で十分です。「完了」を明示する必要はありません。ラベルは Acceptance target (user verbatim)(ユーザー原文による受理目標)とします。リクエストに受理目標がまったく定義されていない場合(「完了」の状態が何かがまったく示されていない場合)、その旨を1行で述べ、ユーザーに受理目標を述べるよう依頼し、停止してください — ゲート対象がありません。セクション2の証拠レベル Claim は別概念であり、その名前は維持します。
  • Change ref(レポートヘッダー)= テスト対象の変更を含むコミット。このレポートを追加したコミットではなく、必ずしもHEADではありません。gitがない場合は、ハッシュの代わりに「変更ファイルのsha256 + ファイルリスト」を使用します。レポートがコミットされた後、HEADは進みます。これは正常であり、検証者は Change ref で判断し、HEADでは判断しません。
  • Working tree(レポートヘッダー)は自由記述であり、2値の列挙ではありません。例:tracked clean; .proof/ untracked。
  • この変更が触れたファイル/関数/ルート/コンポーネントを、現在の差分から宣言します。
  • 選択されたすべてのプロファイルには、この差分に作用する(触れたパスを実行または検査する)証拠項目が少なくとも1つ必要です。すべてのアーティファクトが存在しても、差分に触れるものがない場合 = FAIL。
  • DESIGNベースラインは外部ソース(セクション6、proof-profiles.md)を持つ必要があります。トレース不可能なベースラインは Claim であり、そのゲート項目はFAILとなります。

4. プルーフプロファイルの選択

ユーザーの受理目標文に最も適合するワンライナーテストを持つプロファイルを選択します。タスクがDESIGNとFEATUREを同時に持つことは可能であり、その場合は両方を満たす必要があります。一致するプロファイルがない場合は、その旨を1行で述べて停止してください — ランタイムサーフェスがない変更にプロファイルを強制しないでください。

プロファイルワンライナーテスト詳細
DESIGN仕様、レイアウト、インタラクション、アーキテクチャ、または契約を作成し、それが単に提案されたのではなく実装されたことを示す必要がある。references/proof-profiles.md
FEATUREランタイム動作を変更し、それが機能し、不正な入力が拒否されることを示す必要がある。references/proof-profiles.md
DATAFLOW値が複数のステージ(入力、変換、永続化、出力)を通過し、各ホップを示す必要がある。references/proof-profiles.md
  • 「デザインが実装されたか」→ DESIGN。「これは動作するか」→ FEATURE。「データはどこへ行ったか/永続化されたか」→ DATAFLOW。

5. 実行フロー

順番に実行します。スキップや順序変更はしないでください。

  1. リポジトリ内に .proof/<task-name>/ を作成します(短いケバブケースの名前)。証拠はここにファイルとして存在するまで、証拠ではありません。
  2. 証拠を収集する前に、report.md に3〜7個の受理アサーションを記述します。8つのカラム id | assertion(アサーション) | expected(期待値) | pass criterion(合格基準、チェック可能) | changed path(変更パス、ファイル:関数/ルート) | level required(必要レベル) | evidence file(証拠ファイル) | depends on(依存関係) を使用します。「正しく見える」「問題なさそう」「期待通りに動作する」は禁止。チェック可能な条件、例えば「HTTP 200 かつ body.field X = Y」「rect width = 120px」「invalid token returns 401」を使用してください。
    • expected は、証拠収集前に記入される予測結果です(例:401 + BAD_CREDENTIALS、rect width 240px)。FEATURE/DATAFLOW はすべての行でこれを記入する必要があります。DESIGN は n/a と記入してもかまいません。レポートヘッダーに登録時刻を Expected registered (UTC): <time> として記録します。事前登録は自己宣言です。ハッシュやディスク上の儀式は不要です。
    • expected と pass criterion は、1つの条件の2つの表現(予測 vs 判定可能なチェック)です。矛盾があってはなりません。矛盾する行は、収集前に修正する必要があります。ステータスは、pass criterion に対する observed(観測値)のみで決定されます。observed が基準を満たしているが expected から逸脱している場合、実装を expected に合わせるか、アサーションをFAILとマークします — 決して expected を観測値に書き換えてはいけません(セクション8)。
    • changed path には、アサーションが実行するファイル/関数/ルートを記入します。コードパスを実行しないDESIGN行にのみ n/a を記入します。少なくとも1つのアサーションがこの差分で変更されたコードパスを実行し、その名前を示さなければなりません。触れられていないパスに対するアサーションはバインディングされません。FEATURE/DATAFLOW は少なくとも1つの非 n/a の changed path セルを持つ必要があります。DESIGN は n/a を使用してもかまいません。
    • depends on = カンマ区切りの前提条件ID(ない場合は空)。トポロジカル順に収集します。前提条件は、そのステータスが PASS または PASS-BY-USER の場合にのみ満たされたとみなされます。それ以外の場合、下流の行は NOT RUN(セクション7)となり、NOT RUN が1つでもあるとゲートはFAILになります。depends on グラフは非循環である必要があります — 循環はFAILです。USER-JUDGMENT 行はリーフです。どの行も depends on に USER-JUDGMENT IDをリストしてはいけません。
  3. このマシンで実際に利用可能なコマンドを使用して、実際のサーフェスを駆動します(例:起動に npm run dev、APIに curl -i -X POST http://localhost:3000/login -d '{"user":"a","pass":"wrong"}'、UIに実際のブラウザ+DevTools、ログに tail -f)。生のstdout/stderr/response/スクリーンショットを番号付きファイルに保存します(セクション11)。raw = 完全な出力をキャプチャしたものであり、要約、抜粋、並べ替えは禁止です。感度情報の除去は、キャプチャ時に適用される1回限りの変換であり、「生」を壊しません。トークン/パスワード/キーを *** に置き換えて保存し、証拠インデックスと各ペーストされた生ブロックの横に redacted: <field name> (N occurrence(s)) とファイルのsha256を記録することで、レビュアーがキャプチャ後の編集がないことを確認できるようにします。ステータスコード、エラーコード、またはアサーションが依存する値を決して秘匿化しないでください。レポート内に <起動コマンド> / <スクリーンショットツール> スタイルのプレースホルダーが残っている場合 = FAIL。実行した正確なコマンドに置き換えてください。
  4. 最初に逆方向ケースを実行します。「1つの変更された振る舞い」を、差分内の追加または変更された各ブランチ(if/else、ガード、バリデーション、新しいルート)と定義します。すべてをレポートにリストし、アサーションテーブルに各行を与えます。境界ケースは判定可能です。同じ入力が変更前の実装では受け入れられ(または異なる振る舞いをし)、変更後は拒否される(または正しく振る舞う)ものです。git stash、変更前コミットのワークツリー/チェックアウト、または元のファイルの保存コピーを使用して元の状態を再構築して変更前ベースラインをキャプチャします。どの方法を使用したかをレポートに記載し、変更前の状態でまったく同じコマンドを実行し、結果を 00-pre-change.log(セクション11)として保存します。この「変更前なら失敗することを示す」段階が逆方向ケースのベースラインであり、決してターミナルFAILアサーション行ではありません(セクション9)。次に、変更された各振る舞いに対して、1つの逆方向ケース(誤った入力、権限不足、境界値、削除された前提条件)を実行し、期待される方法で失敗することを記録します。変更前も失敗していたケースはカウントされません。ケースが変更後に受け入れられた場合、テストは実際のパス上にありません。修正して再収集してください。
  5. データフロー:収集前に、report.md に期待される変換の1行(入力形状 -> 出力形状)を書き、すべてのホップでそれを参照します。次に、同じ相関IDを使用して、ホップごとに1つの実際のサンプル(入力 -> 中間 -> 永続化 -> 出力)をキャプチャします。永続化については、実際の読み取りクエリとストアからの生の戻り値をペーストします。書き込んだ値を再表示することはスナップショットではありません。また、ステップ4に従って逆方向ケースの変更前ベースライン(00-pre-change.log)もキャプチャします。変更前に拒否された値が出力に到達することを示す必要があります。
  6. DESIGNの観測値は、機械的にキャプチャされたソース(計算済みスタイルJSON、getBoundingClientRect、DOM textContent、CDP出力)から取得し、ファイルとして保存する必要があります。スクリーンショットから目視で数値を読み取ってはいけません。ベースラインは数値許容差(各辺 ≤2px、各チャンネル ≤8)を与える必要があります。これを超える場合 = FAIL。スクリーンショットは人間の目視レビューのみに使用し、決して数値ソースとしては使用しません。
  7. references/report-template.md からレポートを作成します。コピーしてください。形式を発明しないでください。選択したプロファイルに関連するセクションのみを保持し、該当しないセクションは完全に削除します。削除しても「コピーする、形式を発明しない」に違反しません。
  8. ゲート判断(セクション6):必要なすべての項目が必要なレベルで存在し、すべての非 USER-JUDGMENT アサーションが PASS/PASS-BY-USER であり、少なくとも1つのアサーションが機械的な判定を持ち、depends on に循環がない場合のみ PASS。それ以外の場合は FAIL、UNAVAILABLE/BLOCKED、または PENDING USER(セクション7)。Gate と Result は同じ列挙を使用し、同一でなければなりません。

6. ハードゲート(1つでも欠けている = FAIL)

「完了」にはすべてのボックスにチェックが入っている必要があります。ファイルの欠落、逆方向ケースの欠落、実際のパス上のモック、または差分から外れた証拠は、いかなる説明があってもFAILです。

  • 完全性(未知の項目がないこと):レポートはアサーション総数Nを述べ、N個のアサーションそれぞれのステータスをリストします。有効なステータスは PASS | FAIL | NOT RUN | UNAVAILABLE | BLOCKED | USER-JUDGMENT | PASS-BY-USER のみです。空のステータス、このセット外のステータス、またはリストされた数がNと異なる場合はFAIL。PASS には、すべての非 USER-JUDGMENT 行が PASS/PASS-BY-USER であり、FAIL/NOT RUN/UNAVAILABLE/BLOCKED がないことが必要です。
  • USER-JUDGMENT は、判定可能な機械的基準がまったくない次元にのみ有効です。機械が行を判断できる場合、または判断済みで条件が成立しない場合、そのステータスは機械の判定(PASS/FAIL)であり、決して USER-JUDGMENT ではありません。機械で測定できるものはすべて、機械の判定を持つ独自の行でなければなりません。この差分にバインドされたアサーション(セクション3)は、決して USER-JUDGMENT であってはなりません。すべてのアサーションが USER-JUDGMENT であるレポートは、PASS条件が空虚に真となり、FAILです。少なくとも1行は機械的判定を持たなければなりません。機械でテストされ、基準を満たさない場合 = FAIL(USER-JUDGMENT ではありません)。
  • depends on はDAGです:循環はFAIL。前提条件は PASS または PASS-BY-USER によってのみ満たされます。どの行も USER-JUDGMENT 行に依存してはいけません。そのような行はリーフです。
  • グローバル:バインディングが成立していること(セクション3)、少なくとも1つのアサーションが差分にバインドしていること(セクション5ステップ2)。USER-JUDGMENT 行は決してPASSとカウントされず、別の項目のPASSをブロックしません。
プロファイル最小証拠セット — すべて必須
DESIGN(a) 外部ソースを持つベースラインアーティファクト:既存のデザインファイル+作成コミット、またはそれを含む/承認するユーザー原文メッセージ、または実装ファイルが存在する前にベースラインファイルとしてランディングされた仕様テーブルで、固定メタブロック(source_type、source_quote_or_path、captured_at_utc、sha256、baseline_method)がランディング時に記入されていること。実装から値をベースラインにリバースエンジニアリングすることは禁止。(b) 変更コミットでの実際のレンダリングスクリーンショット。(c) 対象範囲内のすべての要素(範囲 = デザイン成果物で指定されたすべての要素、除外要素とその理由をリスト)のサイズ、色、間隔、テキスト、状態の比較。各行でベースライン値と機械的にソースされた観測値を引用し、ベースラインに数値許容差(各辺 ≤2px、各チャンネル ≤8)を明記。(d) 許容差の境界上の値(例:±2pxの仕様で240pxに対して243px)を持つ1つの逆方向項目で、生の出力によって欠落/不一致を示すもの。(e) 仕様ギャップを明示的に宣言:解釈(実装前に書かれたベースライン解釈、位置/マッピングのみを追加し、ユーザー値と矛盾しない)、除外(ベースライン値が存在しない、そのまま記述)、利用不可(値は存在するがここでは測定不可能)— 除外と利用不可は別のレポートセクションに記述し、黙示の省略は禁止。(f) 差分上の証拠項目が1つ以上。
FEATURE(a) 変更コミットで変更されたコードパスを実行する、実際の駆動I/Oトランスクリプト1つ。(b) 変更された各振る舞いに対する1つの逆方向ケース。その無効入力は判定可能な境界上にある(変更前は受け入れられる/異なる、変更後は拒否される/正しい)。変更前ベースライン 00-pre-change.log と、正しい拒否を示す生の出力で裏付けられる。変更前も失敗していたケースはカウントされない。(c) 正確なコマンド/アクションと変更参照を記録。(d) すべてのアサーションが changed path が記入されたファイルにマッピングされ、少なくとも1つのアサーションが変更されたパスを実行し、変更されたファイル/関数/ルートを指定する。(e) チェーンを代替するモック/スタブがないこと。(f) 差分上の証拠項目が1つ以上。
DATAFLOW(0) 収集前に書かれ、各ホップで参照される期待される変換行(入力形状 -> 出力形状)。(a) 同じ相関IDを持つホップごと(入力、中間、永続化、出力)の1つのスナップショット。(b) 永続化スナップショットは、ストアからの実際の読み取りクエリ+生の戻り値をペーストします。書き込んだ値の再表示ではありません。(c) 永続化スナップショットは、ストアからの実際の読み取りクエリ+生の戻り値をペーストします。書き込んだ値の再表示ではありません。(d) 逆方向ケース:不正なデータが永続化に到達するのを防ぐこと、または永続化されても出力に拒否が表示されること (e) 各ホップが changed path を指定し、少なくとも1つが差分にバインドしている (f) 差分上の証拠項目が1つ以上。

7. 結果コード(終了コード)

コード意味ゲートがいつ使うか
PASSすべての必須項目が必要なレベルで存在し、すべての機械チェックが合格。セクション6のすべての条件が満たされた場合。
PASS-BY-USERゲートは非機械次元について閉じられており、ユーザーが明示的に承認した。機械テスト不可能な次元の PENDING USER からの移行。
FAIL少なくとも1つの必須項目が欠けているか、機械チェックが失敗した。証拠が不足している、または基準を満たさない場合。
FAIL-WAIVED書面によるユーザー放棄により FAIL がクローズされた。FAIL からユーザーが放棄した場合。
UNAVAILABLE証拠項目に必要なリソースがこの環境に存在しない。ツール、アクセス権、または依存関係がない場合。FAIL と同時に発生はしない。AVAILABLE / UNAVAILABLE は証拠ごとの判定。
BLOCKED外部ブロッカーが証拠収集を妨げている(例:ダウンストリームAPIがダウンしている)。UNAVAILABLE と同時に発生はしない。
PENDING USER機械テスト不可能な次元。ユーザーが明示的に確認するまで閉じられない。判定可能な機械的条件が存在しない場合。
NOT RUN前提条件が PASS または PASS-BY-USER ではないため、このアサーションはスキップされた。依存関係が未解決の場合(セクション5ステップ2)。
  • 明確化:UNAVAILABLE と BLOCKED は相互に排他的ではありませんが、証拠項目ごとに1つの値です。ゲートは UNAVAILABLE を単一のコードとして返します。
  • PASS-BY-USER に到達するには、PENDING USER 行を先に宣言する必要があります。ユーザーが承認すると、行は PASS-BY-USER に移行します。ゲートが PASS になるには、少なくとも1行が機械的に判定されている必要があります。

8. 証拠の改ざんと非合法な書き換え

  • 証拠収集後に expected を観測値に合わせて書き換えることは禁止。これは事後的な書き換えであり、改ざんです。
  • expected は証拠収集前に記録されなければなりません。レポートヘッダーに Expected registered (UTC): <time> があり、証拠ファイルがそれより後のタイムスタンプであれば、改ざんがなかったことが証明されます。
  • もし expected が矛盾しており矛盾に気づいた場合、収集前に修正します。収集中に矛盾に気づいた場合は停止し、収集を破棄し、修正してから再収集します。これを怠るとFAIL。
  • 観測値が expected と pass criterion の両方に一致する場合のみ、アサーションはPASSです。

9. 永久ループ防止

  • ゲートは失敗しても同じ変更を再実行してはいけません。変更を拒否するか、証拠ギャップを修正するために新しい作業サイクルを開始します。
  • 以下の場合、ループを終了します:(a) すでに2回同じ変更を拒否した場合(FAIL → FAIL、FAIL-WAIVED → FAIL-WAIVEDはリセットしない)、(b) 変更がまったく新しいコミットなしで再提出された場合。
  • この作業サイクルでゲートの判断を下した後、同じコミットに対して即座に別の証明ラウンドを開始してはいけません。ユーザーが新しい変更を要求するか、証拠が修正された後にのみ再評価します。
  • 証拠のない変更を許可するために「完了」の定義を狭めることは禁止。

10. 以前の変更に対する動作

  • 以前に done と主張した変更をユーザーが再訪した場合、ゲートは新しいコミットが新しい証拠を持っている場合にのみPASSします。
  • 既存の .proof/ ディレクトリと report.md は捨て、新しいタスク名で最初からやり直します。
  • 前のラウンドの証拠ファイルとレポートを引っ張ってきて再利用することは不正です。

11. フォルダ構造とファイル命名規則

.proof/<task-name>/
├── 00-pre-change.log          # 変更前ベースライン(逆方向ケース)(あれば)
├── 01-response.json           # API応答
├── 02-screenshot.png          # UIスクリーンショット
├── 03-computed-style.json     # 計算済みスタイル
├── 04-query-result.log        # データベースクエリ結果
├── ...
└── report.md                  # references/report-template.md のコピー
  • 同じタイプの複数の証拠は連続番号を使用します(例:01-response.json、02-response.json)。
  • 拡張子は内容を反映する必要があります(例:JSONには .json、生のテキストには .log、画像には .png)。

12. 境界値と浮動小数点

  • DESIGNの数値比較では、明示的な許容差(各辺 ≤2px、各チャンネル ≤8)が必要です。レポートでこれらを指定しなかった場合、ゲートはFAILです。
  • 非DESIGNのアサーションでは、バグを隠す可能性があるため、浮動小数点に緩い許容差を使用しないでください。小数第2位までの完全一致を使用してください。

13. 証拠の索引

保存されたすべての証拠ファイルの索引を、番号、ファイル名、sha256ハッシュ、証拠の簡単な説明とともに含めます。レポートの先頭近く、アサーションテーブルの前に配置します。例:

#ファイルsha256説明
100-pre-change.loga1b2c3...変更前のログイン、不正なパスワード — 変更前は200、変更後は401を示す。
201-response.jsond4e5f6...有効なトークンによるログイン応答。

14. プロファイルの確認

  • DESIGNプロファイルの完全なゲート項目のリストについては references/proof-profiles.md を参照してください。
  • FEATUREプロファイルの完全なゲート項目のリストについては references/proof-profiles.md を参照してください。
  • DATAFLOWプロファイルの完全なゲート項目のリストについては references/proof-profiles.md を参照してください。

このスキルは references/ ディレクトリ内のリファレンス文書の指示をオーバーライドします。競合がある場合は、このSKILL.mdが優先されます。

関連スキル