verification-before-completion

verification-before-completion スキルの概要

verification-before-completion は何のためのスキルか

verification-before-completion スキルは、作業が完了した、修正できた、テストが通った、レビューに出せる、といったことを言う直前に使う厳格な最終確認ワークフローです。役割は明快で、根拠のない成功宣言を止め、まず最新の証拠を出すことを強制します。

特に相性がいいのは、AI支援コーディング、エージェント運用、コミット前の最終確認、PR引き継ぎです。実際には適切なコマンドを走らせていないのに、「tests should pass」「the bug is fixed」「build looks good」といった言い方をしてしまう――このスキルは、まさにその失敗パターンを狙って防ぎます。

このスキルを入れるべき人

特に向いているのは、次のようなユーザーです。

• AIエージェントにコード編集を任せる開発者
• 根拠つきで、よりクリーンなステータス報告を求めるレビュアー
• 楽観的だが未検証な完了メッセージに疲れているチーム
• 自信より証拠を重視する Skill Validation パターンを使っている人

一方で、主目的がコード生成、実装計画、広範なデバッグ支援なら、これはその代替にはなりません。verification-before-completion スキルは総合的な作業フローではなく、あくまでガードレールです。

本当に片付けたい仕事

本当の目的は、単に「テストを回す」ことではありません。やるべきなのは次の4つです。

1. その主張を証明するには何が必要かを特定する
2. その証明にあたる検証を今この状態で実行する
3. 実際の出力を読む
4. 証拠が裏づける範囲だけを主張する

当たり前に見えますが、AI支援ワークフローが崩れやすいのはまさにこの部分です。verification-before-completion は、この期待値を「完了を語る前のハードゲート」に変えます。

verification-before-completion が他と違う点

最大の違いは、守備範囲をあえて狭くしていることです。verification-before-completion は、リポジトリ全体を賢く理解しようとはしません。代わりに、価値の高い1つのルールを徹底します。

最新の検証証拠なしに完了を主張しない

この狭さがあるからこそ、仕上げレイヤーのスキルとして非常に使いやすくなっています。よくある「注意して検証してから答えて」というプロンプトよりも一貫して発動しやすいのは、判断手順が再現可能だからです。つまり、特定する、実行する、読む、検証する、その後で話す、という流れです。

このスキルが強くハマる場面

verification-before-completion スキルは、次のようなことを言おうとしているタイミングで使うと効果的です。

• 「tests pass」
• 「the bug is fixed」
• 「the build succeeds」
• 「this is ready to merge」
• 「the linter is clean」

これらの主張には、それぞれ異なる証拠が必要です。このスキルは、「近い何かは確認したが、結論だけ大きく言ってしまう」というありがちなミスを防ぐのに役立ちます。

verification-before-completion スキルの使い方

verification-before-completion の導入方法

obra/superpowers リポジトリからインストールします。

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

このスキルは単一の SKILL.md に収まっているため、導入負荷は軽めです。事前に理解しておくべき補助スクリプトや追加リソースファイルはありません。

最初に読むべきファイル

まず読むのは次です。

• skills/verification-before-completion/SKILL.md

このファイルに挙動の契約がすべてまとまっています。このスキルはリポジトリ内の補助構造が最小限なので、まず SKILL.md を読めば、自分のワークフローに合うかどうかを十分判断できます。

このスキルが必要とする入力

verification-before-completion スキルが最も機能するのは、次の3点をこちらから渡したときです。

• これから自分が言おうとしている主張
• その主張を実際に証明できるコマンド
• 検証を妨げている環境上の制約

入力例:

• 「I want to say the fix works. The proving command is pytest tests/api/test_login.py -q.」
• 「I want to say the build passes. The expected verification is npm run build.」
• 「I think lint is clean, but I have not run ruff check . yet.」

主張とコマンドが具体化されていないと、このスキルが返せるのは一般論としての注意喚起にとどまります。

曖昧な依頼を使えるプロンプトに変える

弱いプロンプト:

• 「Can I say this is done?」

よりよいプロンプト:

• 「Before I claim this is complete, apply the verification-before-completion skill. The claim is: ‘the login bug is fixed.’ The best proving command is pytest tests/auth/test_login_bug.py -q. If that is not enough, tell me what additional verification is required.」

これがよい理由:

• 主張の内容が明示されている
• 証明の道筋が提案されている
• 不十分な検証であれば、スキル側が異議を出せる

verification-before-completion を実運用で呼ぶタイミング

verification-before-completion は、完了報告、コミット要約、PRコメントのような「締めの文」を書く直前に使うのが基本です。実用的な流れは次のとおりです。

1. コード変更を終える
2. どの主張をしたいのかを正確に決める
3. その主張を証明するコマンドを特定する
4. その完全なコマンドを今の状態で新たに実行する
5. 出力と終了ステータスを確認する
6. 証拠が不十分なら、主張を弱めるか条件つきにする

この順番は重要です。人は要約の段階でつい楽観的になりやすく、verification-before-completion が最も効くのはまさにその瞬間だからです。

主張に対して正しい証拠を当てる

verification-before-completion スキルの実務上の大きな価値は、「主張と証拠のズレ」を止められることです。

例:

• 主張: 「Tests pass」
  証拠: 関連する完全なテストコマンドが失敗ゼロで完了していること

• 主張: 「Linter is clean」
  証拠: linter コマンドがエラーゼロを示していること

• 主張: 「Build succeeds」
  証拠: build コマンドが正常終了していること

• 主張: 「Bug is fixed」
  証拠: 元の不具合再現経路を含む検証が通ること

linter が通ったことは build 成功の証明にはなりません。ファイルを変更したことも bug fix の証明にはなりません。AIエージェントの弱い出力は、まさにこの切り分けに失敗しがちです。

何を「最新の検証証拠」とみなすか

ここでいう最新とは、今この作業状態に対して実行されたコマンド結果であることを指します。以前の試行を思い出して使うことではありません。実務的には次を意味します。

• 古いターミナル出力に頼らない
• ファイルがあまり変わっていないから結果も同じだろうと決めつけない
• 周辺のシグナルから成功を推測しない
• 狭い検証結果を、より広い主張の根拠にしない

最後の実行後にコードを変えたなら、その結果は完了判断の材料としてはもう古い、ということです。

検証を実行できないときの対応

実行環境の都合で検証できないことはあります。依存関係不足、認証情報の欠如、サービス停止、非対応OS、時間制約などです。その場合は、より強い主張をしないことが大前提です。

代わりに、証拠ベースの表現を使います。

• 「I made the change, but I could not run npm test in this environment.」
• 「The fix is implemented, but build verification remains unconfirmed.」
• 「I verified formatting only; full integration tests were not run.」

これでも verification-before-completion の使い方としては成功です。このスキルの目的は、無理に確信を作ることではなく、状況を正確に報告することだからです。

エージェント向けの実用プロンプト

再利用しやすい強いプロンプトの例:

“Use the verification-before-completion skill before any success claim. For each claim, identify the proving command, run it fresh if possible, read the full output, and only state what the evidence confirms. If verification is blocked, report the limitation instead of implying success.”

この形は、エージェント指示、PRアシスタント、コミット文生成フローで特に使いやすいです。

Skill Validation 用途での最適な使い方

verification-before-completion for Skill Validation では、このスキルをメインの作業者ではなく、最後の検証者として扱うのが基本です。おすすめの流れは次のとおりです。

1. まず別のスキルで実装またはデバッグする
2. その後 verification-before-completion に切り替える
3. 外部に出したい限定的な主張を検証する
4. 実行コマンドと結果証拠を含む要約を作る

この分離によって、実装と検証が混ざらず、信頼性が上がります。

verification-before-completion スキル FAQ

verification-before-completion は単なる「テストを回しておいて」という注意喚起ですか？

いいえ。verification-before-completion スキルは、単なるリマインダーより厳格です。主張と証明を対応づけることを求めます。重要なのは「何かを実行する」ことではなく、「これから言おうとしている文を正しく証明できるコマンドを実行する」ことです。

このスキルは初心者にも役立ちますか？

はい。特に、どのチェックが何を証明するのかを学び始めた段階の初心者に有効です。「証拠以上のことは言わない」という強い習慣が身につきます。この習慣は、技術的な正確さだけでなく、レビュアーからの信頼向上にもつながります。

verification-before-completion を使わないほうがよい場面は？

これを唯一のコーディングスキル、あるいは唯一のデバッグスキルとして使うべきではありません。アーキテクチャ設計、根本原因の特定、包括的なテスト計画の作成まではやってくれません。これはあくまで仕上げのチェックポイントであり、実装志向のスキルと組み合わせるのが前提です。

普通のプロンプトより何が優れていますか？

普通のプロンプトでも「回答前に検証して」とは書けますが、それでもエージェントは曖昧な成功表現に流れがちです。verification-before-completion skill が優れているのは、根拠のない断言に対して明確な制約を設けた、一貫した事前ゲートとして使える点です。

特定のスタックやツールチェーンが必要ですか？

不要です。このスキルのロジックは言語やフレームワークではなく、証拠に基づいているため、スタック非依存です。pytest、npm test、go test、cargo test など、環境に合った証明コマンドを自分で渡せば動きます。

フル検証のコストが高すぎる場合でも使えますか？

はい。ただしその場合は、主張の範囲も狭める必要があります。対象を絞ったテストしか回していないなら、「その対象テストが通った」と言うべきです。より広い検証をしていないのに、「everything passes」にまで広げてはいけません。

verification-before-completion スキルを改善する方法

検証を頼む前に、主張文そのものを出す

出力品質を最も改善しやすいのは、自分が書こうとしている文をそのまま示すことです。たとえば:

• 弱い例: 「validate this」
• 強い例: 「I want to say: ‘the payment bug is fixed and tests pass’」

こうすると、複合主張を分解し、それぞれに必要な証拠を割り当てやすくなります。

最適な証明コマンドを明示する

リポジトリの慣習が分かっているなら、スキルに推測させないほうがよいです。より強い入力例:

• 「The canonical project check is make test.」
• 「The bug is proven by pytest tests/payments/test_refund.py -q plus npm run build.」

これにより、不完全なチェックに基づく誤った安心感を減らせます。

実装済みかどうかと、検証済みかどうかを分ける

よくある失敗は、「コードは変えた」と「問題は解決した」を混同することです。verification-before-completion usage を改善するには、次の2部構成で答えるよう求めるのが有効です。

• 何を変更したか
• 実際に何を検証できたか

こうしておくと、実行がブロックされた場合でも、要約の誠実さを保てます。

狭い確認結果から広い結論を出さない

1本の focused test を回しただけなら、リポジトリ全体の健全性まで認定させるべきではありません。よりよい聞き方は次のような形です。

• 「Can I say the targeted regression test now passes?」
• ではなく「Can I say the system is fully fixed?」

これは、このスキルが促す習慣の中でも特に価値が高いものの1つです。

証拠が足りないときの言い換えも依頼する

実務で verification-before-completion guide をより使えるものにするには、代替表現を求めるのが有効です。

• 「If the claim is too strong for the evidence, rewrite it to the strongest accurate version.」

これにより、このスキルは単なるブロッカーではなく、コミュニケーション品質を上げる道具にもなります。

重要な変更後は再実行する

検証成功後にコードを編集したなら、verification-before-completion スキルをもう一度使ってください。必要なのは以前のドラフトではなく、現在の状態に結びついた最新証拠です。特に、エージェントの高速ループで最後に「小さな微調整」を入れたとき、以前の確認結果が無効になるケースは少なくありません。

最終サマリーに証拠を入れる

信頼性を高めるには、完了メモの中に証拠を直接入れるのが効果的です。

• 実行したコマンド
• pass/fail の結果
• 制約や未実施項目

例:

• 「Verified with pytest tests/auth/test_login_bug.py -q: passed, 1 test, 0 failures.」
• 「Did not verify full integration suite in this environment.」

この書き方にすると、verification-before-completion はレビュアーにとっても、あとで見返す自分にとっても価値が高くなります。

最も多い失敗パターンを意識する

verification-before-completion for Skill Validation の誤用で最も多いのは、出力結果ではなく、意図・コード変更・期待だけを根拠に成功を主張してしまうことです。改善したいなら、完了メッセージの前に毎回こう自問すると効果的です。

「What command output would make this statement true?」

この問いに明確に答えられないなら、その主張はまだ出す準備ができていない可能性が高いです。