ディレクトリ設計とは — 実務で使えるベストプラクティスと設計ガイド
エバープレイ編集部はじめに — ディレクトリ設計の意義
ディレクトリ設計とは、ファイルシステム上やプロジェクト内でファイルやフォルダをどのように分類・命名し、階層化して配置するかを定める設計作業です。単に見た目を整えるだけでなく、運用性、保守性、セキュリティ、バックアップ、パフォーマンス、開発効率などに大きな影響を及ぼします。特に規模の大きなシステムや複数人の開発チーム、長期運用を前提とするサービスでは、初期設計の影響が長期間残ります。
基本概念と設計目標
良いディレクトリ設計の目標は主に次のような点です。
- 可読性：誰が見ても意味が分かる構造にする。
- 拡張性：将来の機能追加やサービス拡張に耐えうる構造にする。
- 運用性：バックアップ、ローテーション、監査、復旧が容易であること。
- 一貫性：命名規則・配置ルールをチームで統一すること。
- セキュリティ：アクセス制御や分離（機密データと一般データの分離）を確保すること。
- パフォーマンス：ディレクトリの深さやファイル数がI/Oに与える影響を考慮すること。
設計原則（具体的なガイドライン）
以下は実務で使いやすい具体的な指針です。
- 命名規則を定める：英数字、ハイフン/アンダースコアの使い分け、全体を小文字に統一するなど。可搬性を考え特殊文字や空白は避ける。
- 意味で分ける：機能別（config、logs、data、bin）、環境別（dev、staging、prod）、用途別（raw、processed、archive）に分割する。
- 階層の深さは適度に：深すぎるとパス管理が煩雑に、浅すぎると同一ディレクトリに大量ファイルが集まりパフォーマンス低下の原因に。平均的には3〜6階層が扱いやすい。
- 幅（兄弟ノード数）を制御：一つのディレクトリ内に数万〜数百万ファイルが存在するとファイルシステム性能が落ちるケースがある。ハッシュ分割や日付/IDで分割する。
- 環境毎の分離：設定やシークレットはコードリポジトリと分離し、環境別に管理（例：config/prod、config/dev ではなく外部設定や環境変数を利用）。
- 一貫した権限モデル：ユーザー/サービス単位のアクセス制御、必要最小権限を実装。
- 移行と互換性を意識する：将来のマイグレーション（オンプレ→クラウド、ストレージ交換など）を想定して論理名と物理名を分離する。
代表的なディレクトリパターン例
用途別に典型的な構成を紹介します。これらは状況に応じて組み合わせることが多いです。
1) Webアプリケーション（モノリス）
- /app — アプリケーションコード
- /config — 設定ファイル（ただしシークレットは別）
- /public — ドキュメントルート、静的資産
- /logs — ログ出力先（ローテーション設定あり）
- /tmp — 一時ファイル（クリアポリシーを運用）
- /data — 永続データ（ユーザアップロード等）
2) マイクロサービス環境
各サービスごとに独立したレポジトリとデプロイ単位を持つため、サービス単位でのディレクトリ設計と共通ライブラリの配置がポイントになります。
- /services/<サービス名>/src
- /services/<サービス名>/config
- /libraries — 共有ライブラリ
- /deploy — デプロイ用マニフェストやIaC（Terraform、Kubernetesマニフェスト等）
3) データ基盤（データレイク／ETL）
- /raw — 取得直後の生データ（書き込み専用、不変）
- /staged — 前処理済みの中間データ
- /processed — 集計や分析に使う仕上げデータ
- /archive — 長期保存
- /jobs — バッチジョブ、スケジュール定義
セキュリティ・権限設計
ディレクトリ設計は権限設計とセットです。原則は最小権限、職務分離（SoD）、監査ログの確保です。OSレベルならUNIXパーミッションやACL、WindowsならNTFSのアクセス制御を適切に設定し、重要データやシークレットは暗号化・分離します。コンテナやクラウド環境ではボリュームのマウントポリシーやIAMロールによりアクセスを厳格化します。
パフォーマンスとスケーラビリティの考慮点
ファイルシステムによっては同一ディレクトリ内のファイル数が性能に影響します。大量ファイルを扱う場合は、ハッシュで複数階層に分割する、日付でパーティションする、オブジェクトストレージ（S3等）を利用して論理パスを付与する方法があります。バックアップやレプリケーションの単位（ファイル単位/ブロック単位）も設計に影響します。
運用上の注意点（バックアップ・ログ・ローテーション）
- ログは専用ディレクトリへ、ログローテーション（logrotate等）を必ず設定する。
- バックアップポリシーを設計し、復旧手順をドキュメント化する（RTO/RPOを明確化）。
- 容量監視とアラートを設置し、ディスクが満杯になる前に運用対応する。
- 不要データをアーカイブまたは削除するライフサイクルを定義する。
移行とテンプレート化
新規プロジェクトやサービス追加時の手戻りを防ぐために、ディレクトリ設計をテンプレート化しておくと有効です。IaCやスクリプトで初期ディレクトリを自動作成し、READMEやLINTルールで検証することでルールの定着を図ります。移行時にはマッピングテーブルを作成して論理名と物理名を変換できるようにしておくと安全です。
よくある失敗例と対策
- 混在した命名規則：複数チームで別ルールを使う → ガイドラインとCIチェックを導入。
- ログや一時ファイルの放置でディスク枯渇 → 自動ローテーションと削除ポリシー。
- シークレットを平文で格納 → シークレットマネージャ／KMSの導入。
- 1ディレクトリに大量ファイル → ハッシュ分割やオブジェクトストレージへ移行。
チェックリスト（導入前に確認する項目）
- 命名規則が文書化されているか
- 環境（dev/stg/prod）や機密度で適切に分離されているか
- バックアップ・復旧手順が明記されているか
- アクセス制御と監査ログは整備されているか
- 大量ファイル対策やパフォーマンス要件が考慮されているか
- テンプレートや自動生成スクリプトが用意されているか
まとめ
ディレクトリ設計は単なるフォルダ整理ではなく、システムの品質や運用性に直結する重要な設計活動です。初期に明確な方針を立て、命名規則、権限モデル、ライフサイクルを決め、テンプレート化や自動化でルールを守る仕組みを作ることが長期的なコスト削減と安定運用につながります。
参考文献
- Filesystem Hierarchy Standard (FHS) — Linux Foundation
- Naming Files, Paths, and Namespaces — Microsoft Docs
- The Twelve-Factor App — 12factor.net
- SELinux Project — セキュリティ制御について（参考）
- Organizing Data in Amazon S3 — AWS Blog（オブジェクトストレージでの設計例）
投稿者プロフィール
