verifying-before-done

完了前の検証

必須の背景知識： principal-engineering スキル。

概要

完了とは検証済みであることを意味し、検証済みとは何を確認したかを明示するものです。慎重に作業することは、確認することではありません。

規律

1. 変更箇所で実行し、何が起きたかを記録します。 実行中のシステムで変更したコードを実行する最短の手順を実行します。詳しくは、以下の「表面で検証する」を参照してください。
2. 検証コマンドを実行し、その出力を貼り付けます。 検証コマンドは変更前のチェックポイントで決めます。ゲートを通過することを証明し、実際の出力によってその主張を裏付けます。出力を引用する前に、秘密の値をマスキングしてください（秘密情報の取り扱いは operating-safely が担当します）。「検証済み」とは常に「PASS（X と Y を確認）」を意味し、単なるチェックマークではありません。
3. 両方向に正確に報告します。 失敗したテストは出力とともに報告し、スキップした手順はスキップしたと明記し、検証済みの作業は曖昧にせず明確に述べます。検証済みの作業を過小に申告することは、過大に申告して信頼を損なうのと同じように、読み手に再検証の手間をかけさせます。
4. 成功を鵜呑みにしません。 動作しないコードに対してテスト一式が成功するなら、そのテスト一式は実行されていないか、対象を網羅していないか、失敗を検出できないかのいずれかです。変更規模に対して結果が良すぎるように見える場合は、テストが実行されたことを確認し（単独で実行し、実行される様子を確認します）、失敗を検出できることも確認します（コードを壊して失敗することを確認し、元に戻します）。一度も実行されないテストや、一度も作動しないゲートは、誤った「完了」を自信満々に生み出します。
5. 段階を区別します。 実装済み（リポジトリ内）は、デプロイ済み（稼働中）とも、外部検証済み（外部システムで確認済み）とも異なります。前の段階の証拠から、次の段階に進んだと主張してはいけません。
6. 完了を宣言する前に振り返ります。 差分を確認します。無関係な変更がないこと、コードやコメントに計画の残骸がないこと、同じ変更でドキュメントが更新されていること、すべての受け入れ基準をおおよそではなく実際に満たしていることを確認します。
7. 最重要の変更は独立して検証します。 変更を作成した人は、それを検証するうえで最も適した立場にいません。プロジェクトが定める重要な経路（金銭、販売、保存データ、安全性など、システムが決して誤ってはならないもの）や、元に戻せない移行では、コードを書いていない人または仕組みが検証を担当します。期限内に独立した検証者を確保できない場合は、可能な限りそれに近い代替手段を使い、それがより弱い形式であることを明示します。確認の水準を黙って下げることは失敗ですが、明示して下げることは判断です。

表層で検証する

ゲート（verify コマンド、テストスイート、ビルド）は、リポジトリが正常であることを証明します。変更が証明されるのは、呼び出し元と接する場所です。つまり、実行するコマンドライン、提供するエンドポイント、描画する画面、またはインポートする利用側です。

• 実行中のシステムで、変更したコードを実行する最小の経路をたどります。 変更したフラグにはそのフラグを設定して実行し、変更したハンドラーにはリクエストを送り、変更したエラーパスのエラーを発生させます。内部関数は表層ではありません。その呼び出し元は表層に行き着くので、そこで観察します。
• テストは検証ではなく、作者が示した根拠として読みます。 テストは何を実行すべきかを示し、ゲートがそれを再実行します。
• 変更箇所の周辺も調べます。 正常系は主張を確認しますが、隣接するケースもテストします。空の値、繰り返しの呼び出し、競合するオプション、変更で触れていない隣接エラーです。主張の範囲を一つ超える確認が最低限必要です。確認が問題なく通った場合も、何をカバーしたかを示すため、報告します。
• システムが出力した内容を引用します。 レスポンス本文、端末出力、描画された画面が主張の裏付けになります。引用する前に、トークン、接続文字列、認証ヘッダーをマスキングします。曖昧な出力は、マスキング済みの生データを添えて失敗として扱い、合格と解釈してはいけません。
• 該当するものがない場合は「ランタイムの表層なし」と明記します。 振る舞いを生み出さないドキュメント、コメント、型宣言については、それを検証結果とし、空白を埋めるために代わりのゲートを実行してはいけません。
• 破壊的な経路を実環境で実行してはいけません。 変更したコードがワークスペースの外を削除または書き込み、かつ安全な対象が存在しない場合は、その周辺を検証し、未実行の経路を明記します（ガードは operating-safely が担当します）。

自分が担当する失敗中のゲート

まず原因の所在を特定し、テストが誰のものであっても修正します。「以前から存在していた」は報告の注記であり、ゲートを通さない言い訳にはなりません。唯一の例外は手続き上のものです。メインブランチに以前からある失敗によって、無関係な修正が通らない場合は、その旨を伝えたうえで、通った修正だけを先にマージする案を提示し、判断はオペレーターに委ねます。

よくある間違い

• 差分が正しそうに見えるだけで完了を宣言すること。差分は仮説であり、表層での実行が実験です。
• 対象を絞った検証コマンドではなくテストスイート全体を実行し、「新たな失敗はない」を「自分の変更は動作する」と受け取ること。その経路を一度もカバーしていないテストスイートは、変更の裏付けにはなりません。
• ゲートを再実行して、それを検証と呼ぶこと。ゲートが通っていても表層を実行していなければ、「CI は動作する」としか言えず、「変更は動作する」とは言えません。
• リスクが失敗時の経路にある変更で、正常系だけを検証すること。
• 環境にリスクがある変更（設定、マイグレーション、権限、本番データの形式）について、最終的な報告を「テストはローカルで通りました」で済ませること。
• 失敗が都合悪いからといって、コードではなくテストを修正すること。テストは知らせてくれただけです。