Directory Structure Guide

プロジェクトの標準ディレクトリ構成および各ディレクトリ・ファイルの役割と配置規則を定義します。

Overview

本プロジェクトテンプレートでは、アプリケーションコード（apps/）、ドメインデータ（data/）、デプロイ構成（deploy/）、ビルド成果物（dist/）、各種ドキュメント（docs/）、テスト（tests/）、および実行スクリプト（scripts/ / tools/）の対応関係を明確に分離・整理して管理します。

<root>/
├── README.md                           # プロジェクト概要、セットアップ・使用方法
├── GEMINI.md                           # AIエージェント共通指示・ルール定義
├── GEMINI.local.md                     # 個人用AI指示書
├── GEMINI.project.md                   # プロジェクト固有のAI指示書
├── .agents/                            # AI開発用ハーネス・各種カスタムスキル群
│   └── skills/                         # review-document などの開発支援スキル
├── .claude/                            # Claude Code 用設定・ハーネス
├── docs/                               # 全体設計書・各コンポーネント設計書
│   ├── usecases/                       # ユースケース定義 (USECASE-XXX.md) 及び総合台帳 (index.md)
│   ├── concept.md                      # 全体コンセプト概要
│   ├── architecture.md                 # 全体基本設計・システム構成・技術選定
│   ├── security.md                     # 全体セキュリティ方針・ガイド
│   ├── plan.md                         # 全体計画書
│   ├── tools.md                        # 開発ツール利用ガイド (各プロジェクトで作成)
│   ├── raw/                            # 不変ファイル・正本資料 (人間管理)
│   ├── wiki/                           # AI文書・ナレッジ
│   │   └── reviews/                    # レビューレポート蓄積領域
│   ├── decision-records/               # 意思決定記録 (DR-XXX.md) 及び台帳 (index.md)
│   ├── backlog/                        # 全体バックログ・ロードマップ
│   │   ├── phase.md                    # フェーズ別実装ステータス台帳（ビュー）
│   │   ├── usecase.md                  # ユースケース・feature 実装ステータス台帳
│   │   ├── roadmaps/                   # 実装ロードマップ
│   │   └── implementations/            # 実装計画（各コンポーネントから集約、<AppID>-<ID>.md）
│   ├── development/                    # プロジェクト固有の開発資料・開発ガイド
│   ├── guide/                          # aidev-template 専用開発ガイド・テンプレート群
│   │   ├── directory-structure.md     # ディレクトリ構成と役割ガイド
│   │   ├── document-development-guide.md    # 開発プロセスガイド (DDD/SDD基本原則、設計・開発フェーズ反復、実装ロードマップ等)
│   │   ├── document-design-guide.md   # 設計ガイド (concept, architecture, specs, design等)
│   │   ├── document-implementation-guide.md # バックログガイド (backlog以下のwbs, tasks, issues等)
│   │   ├── document-status-guide.md   # ドキュメントステータス・ライフサイクルガイド
│   │   ├── commit-message.md          # コミットメッセージ作成ガイド
│   │   ├── concept-guide.md           # concept.md 作成ガイド
│   │   ├── architecture-guide.md      # architecture.md 作成ガイド
│   │   ├── specification-guide.md     # 機能仕様書 (SPEC-XXX.md) 作成ガイド
│   │   ├── usecase-guide.md           # ユースケース定義書 (USECASE-XXX.md) 作成ガイド
│   │   ├── design-guide.md            # 詳細設計書 (design.md) 作成ガイド
│   │   ├── decision-record-guide.md   # 意思決定記録 (DR-XXX.md) 作成ガイド
│   │   ├── plan-guide.md              # 全体計画書 (plan.md) 作成ガイド
│   │   ├── backlog-phase-guide.md     # フェーズ台帳 (phase.md) 作成ガイド
│   │   ├── backlog-roadmap-guide.md   # 実装ロードマップ作成ガイド
│   │   ├── backlog-implementation-guide.md # 実装計画作成ガイド
│   │   ├── backlog-task-guide.md      # 実装タスク詳細ファイル作成ガイド
│   │   ├── backlog-issue-guide.md     # 課題ファイル作成ガイド
│   │   ├── backlog-todo-guide.md      # TODOファイル作成ガイド
│   │   └── tools-guide.md             # tools.md 作成ガイド
│   └── [<group>/]<component>/          # 各コンポーネント固有ドキュメント (apps/ に対応)
│       ├── requirements.md             # コンポーネント要件定義
│       ├── schema.md                   # DB・データモデル設計
│       ├── design.md                   # コンポーネント詳細設計
│       ├── test-specification.md       # テスト仕様書
│       ├── specs/                      # 機能・入出力・API仕様書ディレクトリ (api/, services/, _common/)
│       ├── models/                     # 個別物理モデル仕様
│       ├── raw/                        # コンポーネント不変ファイル・正本資料
│       ├── wiki/                       # コンポーネントAI文書・ナレッジ
│       └── backlog/                    # コンポーネントバックログ・進捗管理
│           ├── wbs.md                  # WBS (実装タスク・TODO・issues 台帳)
│           ├── spec.md                 # 仕様実装ステータス台帳
│           ├── tasks/                  # 実装タスク詳細ファイル
│           ├── todos/                  # TODO管理ファイル
│           └── issues/                 # 課題管理ファイル
├── apps/                               # アプリケーションソースコード
│   └── [<group>/]<component>/          # 各コンポーネントの実装コード
├── data/                               # ドメインデータ・データセット・コンテンツ層 (配下構造は任意)
├── deploy/                             # デプロイ構成・インフラ設定・環境定義 (配下構造は任意)
├── dist/                               # ビルド成果物・パブリッシュ用静的出力 (**非追跡対象** / 配下構造は任意)
├── tests/                              # テスト関連コード・検証用ファイル
│   └── [<group>/]<component>/          # コンポーネント固有のテスト
│       └── checklists/                 # 機能検証用テストチェックリスト
├── scripts/                            # 各種処理のエントリーポイントスクリプト群（tools/ を使用）
└── tools/                              # scripts/ からのみ参照される内部ツール・ヘルパーモジュール群

Directory Details

Root Level Files

• README.md: プロジェクト概要、セットアップ・構築手順、主要コマンド等を記載します。

• GEMINI.md: AIエージェント（Gemini/Antigravity）共通の行動原則・ルールを定義します。

• GEMINI.local.md: 開発者個人用のローカルAI指示書です。

• GEMINI.project.md: プロジェクト固有の追加AIルール・ガイドラインを記載します。

docs/

プロジェクト全体の設計書およびコンポーネント別の仕様書・進捗管理ファイルを格納します。

Root Documents in docs/

• docs/usecases/: ユースケース定義文書（USECASE-XXX.md）および総合台帳（index.md）を配置するディレクトリ。

• docs/concept.md: プロジェクト全体のコンセプト・ビジョン定義。

• docs/architecture.md: システム全体の基本設計・構成図・技術選定。

• docs/security.md: プロジェクトのセキュリティ方針・対策ガイドライン。

• docs/plan.md: プロジェクト全体の戦略・マイルストーン・フェーズ計画（plan-guide.md 参照）。

• docs/tools.md: プロジェクト固有の開発ツール（tools/ および各種実行環境）の利用ガイド（各プロジェクト側で必要に応じて作成）。

• docs/backlog/phase.md: 全体計画に基づくフェーズ別ユースケース・仕様実装ステータス総合台帳（backlog-phase-guide.md 参照）。

• docs/backlog/usecase.md: 全ユースケース配下の feature 実装ステータス（TODO | WIP | DONE）を一括管理する台帳ファイル。

• docs/backlog/roadmaps/: 実装ロードマップ資料を配置するディレクトリ（ 非追跡対象 ）。

• docs/backlog/implementations/: 各ソフトウェアコンポーネントの実装計画を集約配置するディレクトリ（ 非追跡対象 ）。ファイル名の衝突を防ぐため、ファイル名先頭に <AppID>- を付与します。

• docs/decision-records/: アーキテクチャや技術選定等の意思決定記録（DR-XXX.md）および総合台帳（index.md）を配置するディレクトリ。

• docs/development/: 各プロジェクト固有の開発資料・開発ガイドライン・環境構築手順・ノウハウ等を配置するディレクトリ。

• docs/guide/: aidev-template 専用 の開発運用ガイド・各種マニュアルおよびテンプレートを配置（document-development-guide.md、document-design-guide.md、document-implementation-guide.md、各ドキュメント作成用 XXX-guide.md、commit-message.md 等）。

• raw/: 人間が手動で管理する不変の正本資料・原稿ファイルを格納するディレクトリ（<root>/docs/raw/ および <root>/docs/[<group>/]<component>/raw/ に配置可能）。

• wiki/: AIによるAIのための「AI文書」を格納するディレクトリ（<root>/docs/wiki/ および <root>/docs/[<group>/]<component>/wiki/ に配置可能。※ 追跡対象にするかは任意）。docs/raw/、ソースコード、AIナレッジ、外部情報等を元に生成されます（wiki/reviews/ には review-document スキルによるレビューレポートを蓄積）。非wikiファイルでデータを使用する場合は、wikiファイルではなく必ず docs/raw/ 等の正本データを直接参照・使用してください。

Component Documents in docs/[<group>/]<component>/

apps/[<group>/]<component>/ に対応する各ソフトウェアコンポーネントごとの詳細設計書を配置します（<group> は省略可）。

※ ここでの <component> は「ソフトウェアコンポーネント」（アプリケーション、ライブラリ、フレームワーク、データストア、ツール等）を意味します。React コンポーネント等との誤解を防ぐため原則「ソフトウェアコンポーネント」と表記しますが、コンテキストから明らかな場合は「コンポーネント」と省略可能です。

• requirements.md: コンポーネントごとの要件定義書。

• schema.md: DBスキーマ・テーブル設計・データモデル。

• design.md: コンポーネントの詳細設計書。

• test-specification.md: テストケースおよびテスト仕様定義。

• specs/: 個別の機能仕様書・入出力仕様書を納めるディレクトリ。

• models/: 個別の物理モデル仕様書。

• backlog/: コンポーネントのバックログ管理ディレクトリ。

  • wbs.md: WBS（実装タスク・TODO・issues 台帳）。

  • spec.md: 仕様実装ステータス台帳。

  • tasks/: 具体的な実装タスク詳細ファイル。

  • todos/: TODO管理項目。

  • issues/: 課題・障害管理ファイル。

apps/

実際のアプリケーションソースコードを配置します。

• apps/[<group>/]<component>/: コンポーネント単位の実装コードです。docs/[<group>/]<component>/ と1対1で対応します。

data/

システムや各ソフトウェアコンポーネントが運用・利用するドメインデータ、データセット、マスターデータ、コンテンツ、静的リソースデータを格納します。アプリケーション実装コード（apps/）やプロジェクト設計書（docs/）から明確に分離します。

• 直下の内部構造は用途やプロジェクト構成に応じて任意とします。

• 特定のコンポーネント内部で閉じたデータは apps/[<group>/]<component>/ 内で管理することも可能です。

deploy/

デプロイ用スクリプト、環境構成定義、インフラ構成マニフェスト（Docker, Kubernetes, Terraform, Wrangler等）を格納します。

• 直下の内部構造は用途や環境構成に応じて任意とします。

dist/

ソースコードやドキュメントからビルド・コンパイル・自動生成された配布物、パブリッシュ用静的エクスポート成果物（HTML/CSS/JS/バイナリ等）を出力します（ 非追跡対象 ）。

• 直下の内部構造は用途や出力構成に応じて任意とします。

tests/

テストコードおよび検証用チェックリストを配置します。

• tests/[<group>/]<component>/checklists/: 機能検証用テストチェックリストを格納します。

scripts/ and tools/

自動化処理および実行環境です。

• scripts/: ビルド・デプロイ・データ処理等の各種実行エントリーポイントスクリプト群です。

• tools/: scripts/ からのみ呼び出される内部ツール・ライブラリ・ヘルパーモジュールを格納します。