検証ゲートと自動化
概要
検証がどこに存在し、何によってそれが現実のものとなるか。CIが真実の源であり、ローカルフックは利便性のためのミラーです。 迂回不可能なゲートによって強制されないルールは「提案」に過ぎません（原則7）— そのため、プラットフォームがそのゲートを提供できない場合、プロジェクトは advisory モードを宣言し、ルールを意図的に保持します。自分が持っていない機械を想定することはありません。
ルール
- 1つのタスクランナーが、すべての日常的操作への正規のエントリポイントである — test、build、dev、deploy は名前付きのレシピです。誰かの頭の中にだけ存在する手順は確実に実行されず、エージェントに引き継ぐこともできません。
- CIは真実の源である — 権威があり、共有され、プラットフォームが許す限り迂回不可能である。 リンター、型チェック、契約チェック、テスト、セキュリティスキャン、コミット検証はすべてここで実行され、
enforcedモードではマージ前に通過しなければなりません。CIが言うことがすべてです。advisoryモードでは同じチェックが実行され報告されますが、ゲートは規律であり、それは決してチェックを減らす理由にはなりません。 - pre-push フックは presubmit ミラーであって、壁ではない。 同じ高速チェックをローカルで実行し、CIにプッシュする前におそらくパスするようにします。これは明示的にバイパス可能（
--no-verify）であり、ツールチェーンがインストールされている場合にのみ実行されます。その役割はスピードと早期フィードバックであり、強制ではありません。フックは決してゲートにならず、プラットフォームが許可する場所でCIがゲートとなります。 - チェックを削除するのではなく階層化してCIを高速に保つ。 フルスイートがすべてのPRで大きくなりすぎた場合、presubmit（高速サブセット、PRをブロック）とpostsubmit（フルスイート、マージ後、プロモーションをブロック）に分割します — 権威あるチェックをバイパス可能なフックに戻してはいけません。
- コンテナイメージはCIでビルドし、コンテンツダイジェストで識別し、provenance 証明書とともに公開します。レジストリのレイヤーキャッシュやセルフホステッドランナーでコストを抑えましょう — ビルドをラップトップに移すことは絶対に避けてください。そこでは成果物の provenance を他者が検証できません。
- 強制モードを宣言する。
enforced— CIがブランチ保護を介してマージをブロックします。CIが言うことがすべてです。advisory— CIは実行して報告し、ゲートは規律です。ブランチ保護が利用できない場合（無料プランのプライベートリポジトリなど）に該当します。Advisory は正当ですが、実際には持っていない強制を主張することは許されません。プロジェクトの最初の意思決定記録にモードを記載し、何があれば enforced に移行するかを明記してください。
名前付きの緊張関係
バイパス可能なローカル presubmit は高速だが強制不可能であり、権威あるCIは強制可能だが低速です。それぞれに異なる役割を与えることで解決します — フックは内部ループを最適化し、CIは正しさの記録を担います — そしてフックではなくCIがマージをブロックするものとします。
よくある理屈
| 言い訳 | 現実 |
|---|---|
| 「pre-push フックがテストを実行するから、CIは最小限でいい」 | フックはバイパス可能でツールチェーンに依存します。真実の源にはなり得ません。CIはすべてを再実行しなければなりません。 |
「今回だけ --no-verify しよう」 | 問題ありません — CIがまだキャッチするからです。だからこそ、フックではなくCIがゲートなのです。 |
| 「CIが遅いから、テストをフックに移そう」 | CIを階層化（presubmit/postsubmit）してください。権威あるチェックをバイパス可能なゲートに移してはいけません。 |
| 「CIのビルドが遅いから、イメージをローカルでビルドしよう」 | ラップトップでビルドされた成果物は、他者が検証できないprovenanceを持ちます。レイヤーキャッシュかセルフホステッドランナーでレイテンシを解決してください。 |
| 「ブランチ保護はお金がかかるから、ルールは適用されない」 | ルールは適用されます。強制の仕方が異なるだけです。advisory モードを宣言して規律を維持するか、リポジトリを公開にして保護を無料で手に入れてください。 |
レッドフラグ — 停止
- 権威あるチェックがローカルフックにしか存在しない
- CIがフックで実行したチェックを再実行しない
- CIが赤の状態でマージが許可されている
- CI以外の場所でビルドされたイメージ、またはダイジェストではなくタグでプロモートされたイメージ
- ブランチ保護が存在しないのに、CIがマージをゲートしているかのように振る舞うプロジェクト
完全な根拠: 憲法第VIII条、engineering-constitution/references/engineering-constitution.md にバンドルされています。Deploy/k8s の詳細: cloud-delivery-aks。