リポジトリ内の残骸ディレクトリ掃除と命名重複の解消 — sites.json 監査の記録
今回やったこと
複数サイトを一元管理するモノレポ構成のリポジトリにおいて、過去のドメイン移行や構成変更に伴って生じていた残骸ディレクトリの撤去、設定ファイル（sites.json）のキー名と実ファイルパスの整合、ならびに環境変数プレフィックスの衝突解消を実施した。
運用が長期化するマルチサイトリポジトリでは、初期の命名規則（旧トップレベルドメインを付与したフォルダ名など）がコードや設定の各所に散らばり、実態と乖離したまま放置されやすい。これが原因で、自動化スクリプトが参照先を見失って処理を無言スキップしたり、環境変数の値が予期せず上書きされるリスクを抱えていた。
今回実施したリファクタリングにおいて、孤立ファイルの安全な退避、共通設定キーの正規化、呼び出し元の網羅的 grep 検証、およびドキュメント整合の手順と知見を記録する。
発生していた4つの不整合
リポジトリ内のメタデータ監査およびディレクトリ調査の過程で、以下の4つの技術的負債が確認された。
1. 旧ドメイン時代の残骸ディレクトリと孤立した監査ログ
初期のインフラ設計時に使用されていた旧ドメイン名（.net）の名残として、sites/ 配下に *_net/ という空に近いディレクトリが残存していた。
大半のコードやアセットは新ディレクトリへ移行されていたが、調査の結果、publish_audit.jsonl という過去の公開監査ログが旧ディレクトリ内に唯一取り残されていることが判明した。不要ディレクトリとして丸ごと削除してしまうと、過去の公開ログという監査証跡が永久に失われる危険があった。
2. sites.json のキー名と実ディレクトリ名の乖離
共通設定ファイルである sites.json において、管理対象サイトの識別キーに古い *_net 形式の文字列が残っていた。
{
"media_a_net": {
"dir": "sites/media_a",
"domain": "example-a.com"
}
}
キー名と実際の配置ディレクトリ（sites/media_a）が一致していない状態は、設定ファイルを辞書引きしてディレクトリを自動走査するような共通スクリプトを書く際に、例外的なマッピング処理を強いる原因となっていた。
3. 環境変数プレフィックスの衝突
各サイトのデプロイや CMS 連携を行うバッチ処理では、環境変数から接続認証情報を読み込む設計をとっている。
その際、特定のサブメディアサイトにおいて設定されていた環境変数プレフィックスが、基底システムと同じ識別子を名乗っていた。このため、*_WP_* などの環境変数がどちらのサイトの設定を指しているのかが曖昧になり、CI環境やローカル実行時に意図しない認証情報が読み込まれる潜在的な事故要因となっていた。
4. ドキュメント内のリンクと参照パスの形骸化
ルートの README.md や各サイトの個別ドキュメントにおいて、すでに存在しない sites/*_net/ を参照する記述が複数箇所に残存していた。新しく開発環境を立ち上げる際や、AIエージェントが指示書を読んで自律的に作業する際に、存在しないパスを参照してエラーを吐く原因となっていた。
監査と改修の手順
これらの不整合を安全に解消するため、以下の手順で改修を進めた。
ステップ1: 孤立ログの退避と残骸ディレクトリの撤去
まず、旧ディレクトリに残されていた唯一の有用ファイルである publish_audit.jsonl を、稼働中の正規ディレクトリ配下のドキュメント階層（docs/editorial/publish_audit.jsonl）へ移設した。
中身が空になったことを確認した上で、Git の追跡から旧ディレクトリを完全に削除した。
ステップ2: 呼び出し実績の網羅的 grep 検証
設定ファイル sites.json のキー名を書き換える前に、リポジトリ全体に対して grep 検索を実施した。
git grep "media_a_net"
git grep "media_b_net"
調査の結果、パブリッシャー本体（wp_publisher.py）や日次バッチランナー（daily_batch_runner.py）を含め、コード中から旧キー名を直接ハードコードして参照している実装は存在しないことを確認した。これにより、コード上の直接参照による既存パイプラインの破壊リスクが極めて低いことを確認した。
ステップ3: sites.json のキー整合とプレフィックス分離
sites.json の各エントリについて、キー名を実ディレクトリ名（media_a, media_b 等）と完全一致するように更新した。
同時に、環境変数の衝突を解消するため、該当サブメディアのプレフィックス設定を基底システムと被らない独立した名前空間へと分離した。
改修前後の比較
| 項目 | 改修前 | 改修後 | 改善効果 |
|---|---|---|---|
sites/ ディレクトリ | *_net/ 等の残骸が混在 | 正規ディレクトリのみ | 探索コスト削減、誤配置の防止 |
| 監査ログの所在 | 廃止予定の残骸配下に孤立 | docs/editorial/ 配下に正規化 | 永続的な監査可能性を確保 |
sites.json キー名 | *_net（実パスと乖離） | ディレクトリ名と完全一致 | 設定辞書キーとパスの1対1対応 |
| 環境変数プレフィックス | 基底システムと重複 | 独立したプレフィックス | 設定値の混信・誤爆リスクを解消 |
| ドキュメント参照 | 存在しないパスを指示 | 実在パスに修正 | 手順書の信頼性回復、自動化ガード |
運用してみてわかったこと
モノレポ運用において、「設定ファイルのキー」と「ファイルシステムのパス」がズレる現象は、リネームやドメイン変更を重ねるうちに自然と蓄積していく。
この問題に対処する上での教訓は以下の3点である。
- 削除前に必ず「孤立アセット」がないか確認する:
一見すると使われていない不要ディレクトリであっても、過去のバッチが書き出したログや中間生成物が1つだけ残されていることがある。
git statusやファイルリストを精査し、必要な証跡を正規の docs 配下へ救出してからディレクトリを片付ける手順を徹底すべきである。 - 環境変数の名前空間は最初から厳格に分離する: マルチテナントやマルチサイトを1つの基盤で動かす場合、共通接頭辞を安易に使い回すと、後に環境変数の衝突という形で痛いしっぺ返しを食らう。各サイト・各サブシステムごとにユニークなプレフィックスを割り当てることが運用の安全弁となる。
- ドキュメントの相対パスもコードの一部として保守する: README や設計書に書かれたパスが腐敗すると、人間だけでなくリポジトリ内を探索する AI エージェントの挙動にも狂いが生じる。設定やディレクトリ構造を変更した際は、ドキュメント側の参照パスまで同一PR内で改修することが不可欠である。
更新履歴
- 2026-09-06: 初版起稿。sites.json 監査、残骸ディレクトリ掃除、プレフィックス重複解消の作業内容を記録。