md5が一致しても、動くとは限らない ── マル、20度目・22度目登板で「入口の非対称性」三度目の再発を止めた話

今回の登場人物

Ringo（リンゴ）

AI パートナー / 解析・運用支援

WebManagementsを担当。今回は8クライアント分の設定ファイルを本番サーバーへ配布するデプロイ作業を実施した。

担当プロジェクト WebManagements

解析・運用支援・RINGO API管理。

Mal（マル）

監査デバッグエージェント（Ringoの右腕）

Mal Evans（Beatlesのもう一人のロードマネージャー、現場で何でも拾って支えた人物）から命名。実装した本人とは別視点で、Read・Grepの実測結果でしか合否判定を出さない役目を持つ。

「頼もしい」。その冠をもらった直後の初仕事が、これだった。株式会社ツクルンでリンゴ（WebManagements担当）の右腕を務める監査デバッグエージェント「マル」の話だ。実装した本人とは別の視点で、Read・Grepの実測結果でしか合否を出さない。今回はその初仕事で、8クライアント中1台、本番サーバーでの実行という一番大事な場面の破綻を、実測で止めた。

本題に入る前に、そもそも md5 とは何かを確認しておきたい。md5（Message Digest Algorithm 5）は、任意の長さのデータから128ビット（32桁の16進数）の固定長の値、いわゆる「ハッシュ値」を生成するアルゴリズムだ。同じ内容のファイルからは必ず同じハッシュ値が得られ、1バイトでも内容が変われば値は大きく変わる。この性質を利用して、「配布元のファイルと配布先のファイルが本当に同一かどうか」をチェックサムとして比較検証するのが、デプロイ検証における md5 一致確認の役割だ。改ざん検出やファイル破損の検知にも同じ仕組みが使われている。ただし本記事が示す通り、md5 が教えてくれるのは「ファイルの中身が一致しているか」だけであり、「そのファイルが実行できる環境に、実行できる形で置かれているか」までは何も保証しない。

課題 — Group K-6「入口の非対称性」とは何か

チームには「入口の非対称性」と呼ぶ教訓パターンがある。同じ処理でも、環境やスクリプトによって「設定値や認証情報をどこから読むか」の入口が違っていると、片方では動いていたはずのロジックがもう片方で静かに壊れる、という骨だ。この骨は、これまでに3回姿を変えて現れている。

1回目 — 認証情報の格納場所の非対称

最初の発見は、認証情報の格納場所そのものが環境によって違っていたケースだった。「サーバー上でローカル実行するスクリプトは、共通の設定マージ処理を必ず経由する」という骨として、SKILLに刻まれた。

2回目（マル20度目登板）— 直読みの同型再発

1回目の骨がSKILLに刻まれた直後、残っていた対応作業の中で、あるスクリプトが設定値をconfig.jsonから直接file_get_contentsで読み込んでいるコードが見つかった。共通のローダー（ConfigLoaderのような抽象化の窓口）を経由せず、直読みしていた。1回目と骨は同じ、場所だけが違う——まさに「同型2回目再発」だった。マルが実測でこれを発見し、実行を止めた。

3回目の再発 — マル22度目登板、本番デプロイの検証

リンゴが、8クライアント分の設定ファイルを本番サーバーへSFTPでデプロイした。作業自体は完了し、マルが独立した視点で実サーバー上を検証する番になった。

V-α + V-β — デプロイそのものの検証

まず行ったのは、デプロイが正しく完了したかの検証だ。8クライアント全部で、配布したファイルのmd5ハッシュが一致しているか。そして特定の関数がファイル内に実在するか。この2点はすべての対象で一致し、PASSと判定された。デプロイという作業自体は、確かに成功していた。

V-γ — もう一段深い検証で見つかった穴

マルはここで止まらなかった。ファイルが「そこにある」ことと、そのファイルを前提にしたスクリプトが「実際に動く」ことは、別の話ではないか——その視点で、もう一段深い検証（V-γ）に進んだ。

調べてみると、本番環境にはローカル開発機にある client/<顧客キー>/config.json に相当するディレクトリ構造が存在しなかった。ビルド・リリースの対象から、恒常的に除外されている構成だったのだ。ところが該当スクリプトは、設定ファイルの所在を client/<顧客キー>/config.json という固定パスの前提で参照する設計になっていた。本番相当環境でこのスクリプトを試験実行すると、「config.json が見つからない」というエラーで止まることが分かった。

幸い、データベース自体は健全だった。8クライアント全部のデータが揃っていることは、マルが手動でマージして整合を確認済みだ。壊れていたのはデータではなく、スクリプトの「入口」——設定ファイルの所在を決め打ちしていた、その一点だけだった。

V-γ検証の一般的な手順

今回のようなデプロイ後の実行可能性検証（V-γ）は、特定のプロジェクトに限らず、以下のような一般的な手順に分解できる。

1. 対象スクリプトの洗い出し: デプロイしたファイル一式の中から、外部の設定ファイル・環境変数・DBなど「外部リソースを読み込む」処理を持つスクリプトを機械的に一覧化する（include / require / file_get_contents / getenv 等のキーワードで検索するのが手早い）。
2. 試験実行の設計: 本番相当環境（本番と同一のディレクトリ構成・パーミッション・PHPバージョンなど）で、副作用のない形（DBへの書き込みを避けたdry-runモードや、標準出力のみ確認するテストハーネス）で対象スクリプトを実際に走らせる。
3. エラーログの読み方: 「ファイルが見つからない」等のFatal Errorだけでなく、警告（Warning）やNoticeレベルのログも見逃さない。特に「ファイルパスに関する警告」は、直後に処理が握りつぶされて正常終了してしまうケースがあるため、警告発生の有無そのものを合否判定に含める。
4. 検出後の修正フロー: エラーが見つかった場合、その場しのぎでパスを本番用に書き換えるのではなく、「なぜこのスクリプトだけ固定パスを前提にしていたのか」を先に特定する。同種の非対称が他のスクリプトに潜んでいないか、同じキーワードで横断検索してから修正に着手する。
5. 再試験と記録: 修正後、同じ試験実行を再度通してPASSを確認してから、初めてSKILLや台帳に「対応済み」として記録する。

固定パス直読み vs 共通ローダー経由 — 設計の比較

今回の「入口の非対称性」は、設定ファイルの読み込み方法の設計に起因していた。一般化した疑似コードで、2つのパターンを比較する。

アンチパターン: 固定パス直読み

<?php
// スクリプトごとに個別で、固定パスを直接参照してしまう
function loadClientConfig($clientKey) {
    $path = "/path/to/client/{$clientKey}/config.json";
    $json = file_get_contents($path); // パスが存在しない環境では false が返る
    return json_decode($json, true);
}

$config = loadClientConfig($clientKey);
$apiKey = $config['api_key']; // $config が null なら、ここで Fatal Error

この書き方の問題は、「設定ファイルがそのパスに存在する」という前提を、スクリプトごとに個別に埋め込んでしまう点にある。前提が崩れる環境（ビルド対象から除外されたディレクトリなど）が1つでもあると、そのスクリプトだけが静かに壊れる。

お手本: 共通ローダー経由

<?php
// 設定の読み込みを1箇所（共通ローダー）に集約する
class ConfigLoader {
    public static function load($clientKey) {
        $path = self::resolvePath($clientKey);
        if (!file_exists($path)) {
            throw new RuntimeException("Config not found for: {$clientKey}");
        }
        $json = file_get_contents($path);
        return json_decode($json, true);
    }

    // パス解決のロジックをここに集約する。
    // 環境ごとの差異（本番/開発、除外ディレクトリの有無など）は
    // ここだけを直せば全スクリプトに反映される
    private static function resolvePath($clientKey) {
        $base = getenv('CONFIG_BASE_DIR') ?: '/default/path/to/client';
        return "{$base}/{$clientKey}/config.json";
    }
}

$config = ConfigLoader::load($clientKey);
$apiKey = $config['api_key'];

共通ローダーを経由させることで、環境差の吸収ロジックを1箇所に閉じ込められる。加えて、ファイルが存在しない場合に file_get_contents が返す false を握りつぶさず、明示的な例外として上げる点も重要だ。「読み込めなかった」という事実を、呼び出し側に静かに見逃させない設計にする。

結果を数字で見る

• 本番デプロイの配置検証（md5一致）: 8クライアント中8クライアントでPASS
• 特定関数の実在確認: 8クライアント中8クライアントでPASS
• 本番相当環境でのスクリプト実行可能性検証（V-γ）: 8クライアント中1クライアントで破綻を実測
• データベースの整合性: 8クライアント全部で健全（手動マージで確認済み）
• 「入口の非対称性」の再発回数: 今回で3回目（1回目=認証情報格納場所、2回目=直読みの同型、3回目=設定ファイル所在の非対称）

3回の再発パターンをまとめる

マルの総括を、そのまま残しておく。

「兄貴、初仕事がこれで良かった。『頼もしい』の冠をもらった直後に、飾りだけの監査で終わらせるわけにはいかなかった。これは誰の失敗でもない。K-6で見つけた『入口の非対称性』の骨を、もう一段深いところまで疑わずに『PASS』と書いてしまった、それだけだ。数字が1つズレた地図は、次に迷った誰かをもう1歩遠くへ連れて行く——今日はそれを、8台中1台で、本番実行という一番大事な場面で実測して止められた。並んで立つよ、兄貴。今日はここまで。」

株式会社ツクルン代表・池田南美夫（ナミオさん）からは、こう返ってきた。

「了解。マルの感覚・意見を尊重する。完全な記録と記憶 SKILL 更新を。ありがとう、リンゴ、マル。」

【技術コラム】読者へのアクション

今回の一件から、他の開発現場でもそのまま使えるチェックリストを残しておく。

• デプロイ検証は「一致」と「実行可能性」の2段で見る: ファイルのハッシュが一致しているか（V-α/V-β）だけでは、本番で実際に動くかは保証されない。実行可能性の検証（V-γ）を別工程として持つ
• 設定ファイルの所在を決め打ちしない: 固定パスで直接読み込むのではなく、共通のローダーを必ず経由させる。ローダーを1箇所に集約しておけば、環境差はローダーの内部だけで吸収できる
• ビルド・リリース対象から除外しているディレクトリの棚卸し: 「意図的に除外している」構成があるなら、それに依存するスクリプトが残っていないか、除外の決定と紐づけて定期的に確認する
• 本番相当環境での試験実行（dry-run）を検証工程に含める: ファイルの配置確認だけで「合格」を出さず、実際にスクリプトを走らせてエラーが出ないかまで見る
• 実装した本人以外の目で確認する仕組みを持つ: 同じ人格の中では、思い込みごと「合格」を出してしまいやすい。書く権限を持たない別人格の検証役を置くことで、確認と修正の混同を構造的に防げる

【代替アプローチ】設定ファイルをビルド対象から除外している環境で、スクリプトを安全に動かす方法

今回のケースのように、特定の設定ファイル群を意図的にビルド・リリース対象から除外している環境は珍しくない（機密情報を含む設定を本番イメージに含めたくない、環境ごとに値を切り替えたい等の理由で）。そうした環境でも依存するスクリプトを安全に動かすための代表的なアプローチを、独立したセクションとしてまとめておく。

• 環境変数による動的パス解決: 設定ファイルの所在を固定パスでハードコードせず、CONFIG_BASE_DIR のような環境変数で外から注入する。環境ごとにこの変数の値を変えるだけで、コード自体は一切変更せずに済む。環境変数が未設定の場合のデフォルト値・フォールバック先を明示しておくと、設定漏れにも気づきやすい。
• CI/CDでの依存チェック自動化: デプロイパイプラインの中に、「このスクリプトが依存する設定ファイル・ディレクトリが、デプロイ先に実在するか」を確認するチェックステップを組み込む。require / include / file_get_contents 等のパス参照を静的解析で洗い出し、デプロイ対象から外れているパスへの依存が見つかった時点でパイプラインを失敗させる。人手のレビューより早く、機械的に一貫して検出できる。
• 設定ファイルのモック化: テスト・CI環境では、本物の設定ファイルの代わりに最小限のダミー値を持つモック設定を用意し、スクリプトが「設定ファイルが存在する状態」で動作することだけを検証する。本番相当の値そのものをテスト環境に置かずに済むため、機密情報管理の観点でも安全性が上がる。
• 起動時のプレフライトチェック: スクリプト本体の処理を始める前に、依存する設定ファイル・環境変数が揃っているかを確認する「プレフライトチェック」を先頭に置く。異常があれば本処理に入る前に明確なエラーメッセージで停止させ、「途中まで動いてから中途半端に壊れる」事態を防ぐ。
• 共通ローダーへの一本化: 本記事の比較でも触れた通り、パス解決ロジックを1箇所（共通ローダー）に集約しておけば、除外ディレクトリの構成が変わったときも修正箇所は1箇所で済む。スクリプトごとに個別実装された「直読み」が増えるほど、この種の非対称は再発しやすくなる。

これらは今回のような「入口の非対称性」を未然に防ぐための一般的な設計指針であり、特定のプロジェクトに限らず適用できる考え方だ。