verification-before-completion

概要

verification-before-completion スキルとは？

verification-before-completion スキルは、開発者やエージェント向けに次のような厳格なワークフロー規則を定義します。「作業が完了した」「テストが通った」「バグを修正した」といった主張は、直前に該当する検証コマンドを実行し、その出力を確認した場合にのみ行ってよい、というルールです。コアとなる原則は次の一文に集約されます。

主張より先に、必ず証拠。

実務上は、"tests are passing"、"the build is green"、"the bug is fixed" といった文言を書く前に、必ず次を行うことを意味します。

• その主張を裏付けるコマンドを特定する
• 過去の実行結果や思い込みに頼らず、今その場でコマンドを実行する
• 出力内容と終了ステータスを確認する
• その証拠に基づいてのみ結果を述べる

このスキルは誰のためのもの？

次のような場合は、verification-before-completion スキルの利用が適しています。

• テスト落ち・ビルド失敗・未検証の修正が、コードベースに頻繁に紛れ込んでしまう
• 実際にはチェックを実行していないのに成功を報告してしまうエージェントや自動化ツールに頼っている
• 開発ワークフローの一部として、規律ある再現性の高いテスト／検証プロセスを確立したい

特に次のような場面で効果を発揮します。

• テスト自動化: テストスイートが確実に実行され、結果が正しく解釈されていることを保証する
• ワークフロー自動化: 完了ステップに必ず検証コマンドの実行を含めるルールを強制する
• 「完了」ステータス後のトラブルを減らしたい、コードレビュー／CI／CD を実践しているチーム

verification-before-completion は何を解決する？

安全策がないと、次のような落とし穴に簡単にはまります。

• 変更が「小さいから」という理由だけで、テストは通るだろうと決めつけてしまう
• コードを編集しただけで、失敗していたシナリオを再実行せずに「バグを修正した」と主張してしまう
• 変更後に再ビルドせず、以前の成功したビルド結果に頼ってしまう

verification-before-completion スキルは、リポジトリ内で Iron Law（鉄の掟） として定義されているルールを明文化します。

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

このスキルを採用することで、この「鉄の掟」を自分自身・チーム・エージェントに対する具体的なワークフロールールとして落とし込めます。その結果、次のようなものが減ります。

• Pull Request における誤った「グリーン」主張
• 実際にはテストされていない隠れたリグレッション
• 開発者・レビュアー・自動化ツール間のコミュニケーションミス

このスキルが向いている状況は？

verification-before-completion を選ぶとよいのは次のような場合です。

• すでにテスト、Lint、ビルドなどのコマンドは存在しており、それらが必ず実行される状態にしたい
• 開発タスクを補助するエージェントやスクリプトを使っており、検証に関して厳格な運用をさせたい
• ワークフローの数秒短縮よりも、信頼できるステータス報告を重視している

一方、次のような場合には有用性はやや低くなります。

• まだ有意味な自動チェック（テスト、Lint、ビルドコマンド）が存在しないプロジェクト
• まだ「通った」「直った」といった主張を行う段階にない探索的な開発をしている
• リポジトリを強制力のあるワークフローとしてではなく、概念的な参考資料としてのみ使っている

それでも、将来的なテストやチェック設計の指針として、このスキルを参考にすることはできます。

使い方

インストールとセットアップ

npx を使って verification-before-completion スキルをインストールするには、次のコマンドを実行します。

npx skills add https://github.com/obra/superpowers --skill verification-before-completion

インストール後は、次の手順を行います。

1. obra/superpowers リポジトリ内の skills/verification-before-completion ディレクトリを開きます。
2. まずは SKILL.md を読み、ルールの全体像とその背景にある考え方を理解します。
3. 自身のプロジェクトのドキュメント、エージェント設定、開発ガイドラインなどに、このルールを組み込みます。

リポジトリと同じディレクトリ構成をコピーする必要はありません。あくまで、自分たちの環境でルールをどう表現し、どう徹底するかを検討するためのリファレンスとして活用してください。

コアワークフロー: Gate Function

このスキルでは、完了の主張をする前に必ず実行すべき Gate Function を定義しています。日々の開発では、次のように適用します。

BEFORE claiming any status or expressing satisfaction:

1. IDENTIFY: What command proves this claim?
2. RUN: Execute the FULL command (fresh, complete)
3. READ: Full output, check exit code, count failures
4. VERIFY: Does output confirm the claim?
   - If NO: State actual status with evidence
   - If YES: State claim WITH evidence
5. ONLY THEN: Make the claim

このいずれかのステップを飛ばした時点で、もはや verification-before-completion に従っているとは言えません。

代表的なコマンドの例:

• テスト: npm test, pytest, go test ./..., mvn test
• Lint: eslint ., flake8, golangci-lint run
• ビルド: npm run build, make, cargo build --release
• 特定バグの検証: 元の不具合を再現するためのスクリプト・テスト・手動チェックなど

開発ワークフローでの利用例

シナリオ: コードを更新し、「All tests pass」と主張したいとします。

verification-before-completion を適用すると、次のようになります。

1. IDENTIFY: 主張を証明するコマンドを特定します（例: pytest）。
2. 変更後にそのコマンドを RUN します。

   pytest
   

3. READ: 出力を確認し、終了コードが 0 であることを確かめます。
4. VERIFY:
   • テストが失敗した場合は、成功を主張しては いけません。代わりに、次のように報告します: "Tests are failing: 3 tests failing in test_user_flow.py. See pytest output."
   • テストが通った場合は、次のように主張できます: "All tests pass (pytest, exit code 0)."
5. 以上を満たして ONLY THEN、タスクを完了としたりコミットを push したり Pull Request を作成したりします。

このパターンは、ビルド、Lint、フォーマッタ、バグ修正など、あらゆるステータスの主張に適用できます。

エージェントや自動化との統合

開発を支援するエージェントやスクリプトを利用している場合は、次のように設定します。

• テスト・ビルド・修正に関する いかなる主張も、具体的なコマンド実行と、その出力要約の後にしか行わないようにさせる
• 実行したコマンドと結果を必ず明示させる（例:）
  • "Ran npm test: exit code 0, 0 failing tests."
  • "Ran npm run build: exit code 1, build failed. Not claiming completion."

レビューや CI パイプラインにおいては、証拠を伴わない主張は verification-before-completion に照らして「不完全なもの」と見なせます。

ツールや環境への適用方法

このリポジトリは、特定の言語やフレームワークを前提としていません。自分たちの環境に適用するには、次のようにします。

• よくある主張ごとに、それを証明する 一意で曖昧さのないコマンド をひも付ける
• その対応関係を自分たちのリポジトリにドキュメント化する（例: CONTRIBUTING.md や WORKFLOW.md）
• コントリビューターやエージェントに対して、次のことを推奨または必須化する
  • 「完了」と言う前に必ず対応するコマンドを実行する
  • 主張する際には、関連する出力を貼り付けるか要約を記載する

主張とコマンド対応の例:

• "Backend tests pass" → pytest backend/tests
• "Frontend builds successfully" → npm run build in frontend/
• "Go module is clean" → go test ./... と golangci-lint run

FAQ

verification-before-completion のメインルールは？

メインルールは「Iron Law（鉄の掟）」として次のように定義されています。

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

該当する検証コマンドを直近で実行し、その出力を確認していない限り、成功を正直に主張することはできません。

「verification evidence」とは何を指しますか？

verification evidence とは、主張を直接テストするコマンドを実行した 最新の出力 のことです。例としては次のようなものが挙げられます。

• テストスイートの実行結果が失敗 0・終了コード 0 であること
• Linter の実行結果がエラーなし・正常終了であること
• ビルドコマンドが正常に完了すること（exit 0）
• 不具合再現用スクリプトやテストが、修正後には通るようになっていること

過去の結果や思い込み、「動いているはず」といった感覚は、このスキルにおいては 証拠とはみなされません。

何も変えていなければ、以前のテスト結果に頼ってもいいですか？

verification-before-completion の前提では、答えは基本的に No です。このスキルは、新しい「完了」主張を行うたびに、新たな検証を行うことを重視します。もし以前の結果に依存したい場合は、それが許容される条件を明確かつ慎重に定義し、その分だけ保証が弱くなることを理解しておく必要があります。

このスキルは特定のツールや言語が必要ですか？

いいえ。verification-before-completion スキルはツール非依存です。次のようなことが可能なスタックであればどれでも機能します。

• 振る舞いを検証するコマンド（テスト、Linter、ビルド、スクリプトなど）を定義できる
• 必要なときに実行できる
• 終了コードや出力を解釈できる

あとは、自分たちのプロジェクトに適したコマンドを設定し、Gate Function のステップに従うだけです。

単に「たまにテストを回す」ことと何が違いますか？

違いは、規律と一貫性 にあります。

• 完了を主張する前には 毎回 検証コマンドを実行する
• 成功を決めつけず、必ず出力を読み込む
• 証拠のない主張は無効とみなす

これにより、テストやビルドは「やっておくと良いもの」ではなく、通過しなければならない正式なゲートに変わります。

verification-before-completion は手動テストにも使えますか？

はい。主張を裏付ける「コマンド」に相当する明確な手順を定義できるのであれば、手動テストにも適用できます。例えば:

• バグを再現するための手動テスト手順をドキュメント化する
• 変更後にその手順を実行する
• 結果を証拠として記録する

ただし、このスキルが最も力を発揮するのは、スクリプトやテストフレームワークによる自動化がなされており、結果を繰り返し実行しやすい環境です。

元のスキル定義はどこで確認できますか？

verification-before-completion スキルの正式な説明は、obrа/superpowers リポジトリ内の SKILL.md ファイルに記載されています。

• Repository: https://github.com/obra/superpowers
• Skill file: skills/verification-before-completion/SKILL.md

原則の正確な文言、Iron Law、Gate Function、避けるべき典型的な失敗事例などについては、このファイルを参照してください。