現場実装の クムビーバー です。検証基盤が壊れやすい典型原因は、設定の上書きルールが曖昧なことです。「誰のYAMLが正」か分からない状態で git pull すると、共有設定とマシン固有値が衝突します。速いモデル選定より先に、設定が溶けない規則が必要です。
この回の答え
設定は7段の上書きで、上の層が勝ちます。意図しない層が勝つと事故ります。コマンド行の未指定は下層を潰しません。
この回だけの用語
| 用語 | ひとことで |
|---|---|
| 優先順位（precedence） | どの設定が最終的に勝つかの順番。CSS の詳細度に近い |
| 起動設計図（profile） | 用途の起動設計図。共有しやすい層 |
| 上書き差分（override） | ローカルや一時の差分。共有の正本を直接いじらない |
| 試運転（dry-run） | 頭の中でマージせず、最終解決値を表示して確認する |
| 空値による潰し（null潰し） | 未指定と空値を混ぜて、下層の値を消してしまう事故 |
| コマンド行引数（CLI） | いちばん上の層。一回限りの試験向き |
まずはこれだけ
- 壊れたら「どの層が勝ったか」を先に見る
- 共有の正本を直接いじらず、差分は上書き層へ
- 頭の中でマージせず、試運転で最終値を確認する
社内基盤では、低優先から高優先へ固定順でマージします。
- ランタイム既定
- 起動設計図
- クラスタ設定
- ノード設定
- ローカル上書き
- 環境変数
- コマンド行引数
後のレイヤが前を上書きし、辞書はキー単位マージ、リスト／単値は置換、というルールに統一します。
なぜこの順番か
- 共有できるもの（example、共通プロファイル）を低い層に置く
- マシン固有（ノード差、経路、秘密情報）を高い層に置く
- 一時的な試験をコマンド行で上書きできるようにする
これにより、git pull で共有ロジックだけ更新し、サーバ固有状態を壊しにくくします。レビューも「どの層の差分か」で議論できます。
| レイヤ | 置きたいもの | 置きたくないもの |
|---|---|---|
| 既定 / 起動設計図 | 用途の意図、再現可能な既定 | ホスト固有パス、秘密情報 |
| クラスタ / ノード | 共有クラスタ差、ノード差 | 個人の一時実験 |
| ローカル上書き | 開発者ローカルの差分 | チームの正本 |
| 環境変数 / コマンド行 | 秘密情報、一回限りの試験 | 長期の正設定（忘れやすい） |
マージ規則を一文で
現場トラブルの多くは、「配列がマージされたと思ったら置換だった」「空値で潰した」系です。規則を短く固定します。
- 辞書: キー単位で深いマージ
- リスト / 単値: 後勝ちで置換
- 明示の空値: 潰し事故になりやすいので、未指定と空値を混ぜない
- 最終解決値: 試運転で確認する（頭の中でマージしない）
「YAML を見た」と「最終起動値を見た」は別物です。
追跡するもの / しないもの
| git追跡（共有） | ローカル（管理外） |
|---|---|
| example YAML、docs、コード | .env、実ノード/クラスタ |
| 起動/評価テンプレート | 実 models.yaml、ローカル上書き |
| 生成器・テスト | results、ログ、モデル本体 |
秘密情報やホスト固有値をリポジトリに入れないことは、セキュリティだけでなく、再現実験のノイズ削減にも効きます。
運用チェック
- 試運転後の生成物で「最終解決値」を確認する
- 未指定のコマンド行が空値で設定を潰していないか確認する
- ノード切替は node_id と上書きで明示する
- 共有プロファイルを直接編集せず、差分は上書きに寄せる
- 一時試験はコマンド行 / 環境変数に閉じ、終わったら残さない
- レイヤを跨いだ同名キーの意図を、コメントか docs に残す
事故例と戻り方
| 事故 | 見え方 | 戻り方 |
|---|---|---|
| 共有設計図を直接編集 | 他用途まで巻き込まれる | 設計図を戻し、差分を上書きへ |
| 環境変数の消し忘れ | 昨日の試験設定が残存 | 環境変数一覧を起動前に確認 |
| 空値上書き | 突然既定に戻る | 未指定と空値の扱いをテスト |
| リストのつもりマージ | フラグが消える | 置換前提で差分を書く |
興味がある人向け
小さなチーム向けの実務ルールです。
- 共有に入れる前に「この値は全ノード共通か？」と問う
- 迷ったら高い層（ローカル / 環境変数）に仮置きし、安定したら適切な層へ下げる
- レビューではコード差分より、最終解決値の差分を優先する
- 設定変更もスパイラルの1軸として扱う（ついで変更禁止）
設定PRやプロファイル変更を見るとき、長い議論の前に次だけ確認します。
- この差分は7段のどの層か
- 最終解決値は試運転で確認したか
- 共有に残すべき値か、ローカルに閉じる値か
この3問で、大半の「気づいたら本番相当が変わっていた」系の事故を防げます。設定優先順位は哲学ではなく、レビュー言語です。
つまずいたこと
環境変数、Compose、プロファイル、コマンド行、秘密情報…どこが勝つか分からず、同じキーを三箇所で上書きして一夜を溶かしたことがあります。
苦労したのはドキュメントを書くこと自体より、実際に効いている値を表示する手段を先に用意することでした。優先順位表だけでは、運用事故は止まりませんでした。
この回の要点
- 優先順位表と実効値の表示をセットにする
- 同じキーの三重上書きを禁止する
- 効いている値が見えない設定を信用しない
優先順位の段組みは公開できますが、各段の推奨値一覧ではありません。実効値が意図どおりかの確認ログは運用側で残し、ベンチ数字は再計測・匿名化後に足します。
次は「起動設定はどうコマンドになるか」です。7段のどれが効いているかを意識したまま、起動コマンドへ落とします。
よくある質問
7段とは何ですか？
設定の上書き優先順位です。意図しない層が勝つと事故ります。
CLI で何も指定しないとどうなりますか？
下層の値が残ります。未指定で下層を潰さない設計が安全です。
壊れたときは何を見ますか？
どの層が最終的に勝ったかを先に確認します。
