principle-prove-it-works

動作を実証する

すべてのタスクの出力を、実物を直接確認して検証してください。代替指標、自己申告、「コンパイルできた」ことから推測してはいけません。

理由： 検証されていない作業の正しさは不明です。間接的な検証（ファイルの更新日時、出力の新しさ、エージェントの自己申告、キャッシュされたスクリーンショット）は、直接確認するより手軽に感じられます。しかし、誤った推測に基づいて行動すると、元の情報を確認するよりはるかに大きな損失につながります。

代替指標ではなく、実物を確認してください。

• 派生状態を間接的に確認するのではなく、プロセスが実際に動作しているかを直接確認します
• キャッシュ済みまたは派生した表現ではなく、実際の値を読み取ります
• 検証に失敗したときは、システムを疑う前に、観測方法を疑います
• 成功を報告する前（マージ済み、送信済み、起動済みなど）に、実際の状態と終了コードを読み取ります。出力の切り詰め（| tail -1）や自分のエコーは、何の証明にもなりません

結果だけでなく、プロセスも検証してください。結果が正しくてもプロセスが壊れていることがあり、結果だけを確認するレビューはそれを見逃します。たとえば、ユーザーの貼り付け内容から復元した節を永続的な記録から復元したものとして扱う場合や、読んでいないファイルに含まれる制約を偶然守っている場合です。根拠として使った事実ごとに、その事実の出典となった記録を明示し、プロジェクトのルールが参照先として指定している記録と一致することを確認してください。

赤色は色であって、測定値ではありません。失敗したチェックが検証手段の正しさを証明するのは、失敗の内容が予測した不一致そのものである場合に限られます。例外、空であるべきでないコレクション、実際の不一致は、どれも赤いエラーとして出力されます。そのため、アサーション（assert {...} == {...}）ではなく、アサーションの差分（Extra items in the right set）を引用してください。収束プローブでは、新しい成果物だけが示せる動作を確認し、古い成果物も出力する識別フィールドを確認してはいけません。同じ SHA で再起動すると、古いコードが新しいコミット SHA を報告することがあります。

可能であればチェックをスクリプト化する

最も強力な証拠は、一度だけ目視で確認することではなく、同じ比較を再実行する決定論的なスクリプトです。スクリプトを書いて実行し、レビュー担当者があなたの言葉を信頼せずに再実行できるよう、その出力を成果物として残してください。

人が確認できるよう、成果物を見える状態にしておいてください。後から経緯を監査できるようにする必要がある、大規模な移植や移行などの大規模または複雑な作業に限り、成果物をコミットしてください（show-me-your-work スキル）。