Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Directory Structure Guide

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

Structure

<root>/
├── README.md                           # プロジェクト概要、セットアップ・使用方法
├── GEMINI.md                           # 【同期対象】AIエージェント共通指示・ルール定義
├── GEMINI-ja.md                        # 【同期対象】AIエージェント共通指示・ルール定義 (日本語版)
├── GEMINI.local.md                     # 個人用AI指示書
├── GEMINI.project.md                   # プロジェクト固有のAI指示書
├── .agents/                            # AI開発用ハーネス・各種カスタムスキル群
│   ├── skills/                         # 【同期対象】review-document-status などの開発支援スキル
│   ├── agents/                         # 【同期対象】サブエージェント定義群
│   ├── hooks/                          # 【同期対象】フック処理スクリプト群
│   ├── hooks.gemini.json.sample        # 【同期対象】フック設定サンプル
│   ├── settings.gemini.json.sample     # 【同期対象】エージェント設定サンプル
│   └── statusline.gemini.ps1           # 【同期対象】ステータスライン表示スクリプト
├── .claude/                            # Claude Code 用設定・ハーネス
├── .local/                             # 【非追跡対象】ローカル専用作業・記憶領域
│   ├── artifacts/                      # 一時成果物（画像・変換出力等）
│   ├── memory/                         # 失敗・教訓・ナレッジ蓄積 (write-memory)
│   ├── worklog/                        # 作業日報・残作業管理 (write-worklog)
│   ├── workplan/                       # 作業計画ノート・手順管理 (write-workplan)
│   └── workspace/                      # 一時作業領域・タスク・提案書 (<workspace>)
├── .mise/                              # 【同期対象】mise 構成タスクおよびテンプレート用スクリプト群
│   ├── config.toml                     # テンプレート共通タスク定義
│   ├── scripts/                        # config.toml から呼び出される実行スクリプト群
│   └── tools/                          # config.toml / scripts から参照される内部ツール・モジュール群
├── docs/                               # 【同期対象】全体設計書・各コンポーネント設計書
│   ├── usecases/                       # ユースケース定義 (USECASE-XXX.md)
│   ├── concept.md                      # 全体コンセプト概要
│   ├── architecture.md                 # 全体基本設計・システム構成・技術選定
│   ├── security.md                     # 全体セキュリティ方針・ガイド
│   ├── plan.md                         # 全体計画書
│   ├── tools.md                        # 開発ツール利用ガイド (各プロジェクトで作成)
│   ├── documents.md                    # 文書インデックスおよび各ドキュメントへの誘導ガイド
│   ├── actions.md                      # アクションインデックスおよび状況別作業手順ガイド
│   ├── raw/                            # 不変ファイル・正本資料 (人間管理)
│   ├── wiki/                           # AI文書・ナレッジ
│   │   └── reviews/                    # レビューレポート蓄積領域
│   ├── decision-records/               # 意思決定記録 (DR-XXX.md) 及び台帳 (index.md)
│   ├── backlog/                        # 全体バックログ・スライス計画
│   │   ├── phase.md                    # フェーズ別実装ステータス台帳（ビュー）
│   │   ├── usecase.md                  # ユースケース・feature 実装ステータス台帳
│   │   ├── slices/                     # 実装スライス
│   │   └── 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-slice-guide.md     # 実装スライス作成ガイド
│   │   ├── backlog-implementation-guide.md # 実装計画作成ガイド
│   │   ├── backlog-task-guide.md      # 実装タスク詳細ファイル作成ガイド
│   │   ├── backlog-issue-guide.md     # 課題ファイル作成ガイド
│   │   ├── backlog-todo-guide.md      # TODOファイル作成ガイド
│   │   ├── tools-guide.md             # tools.md 作成ガイド
│   │   ├── local-guide.md             # .local/ 役割・運用ガイド
│   │   └── testing-guide.md           # テスト分類・配置規則および汎用検証チェックリスト作成ガイド
│   └── [<group>/]<component>/          # 各コンポーネント固有ドキュメント (apps/ に対応)
│       ├── requirements.md             # コンポーネント要件定義
│       ├── schema.md                   # DB・データモデル設計
│       ├── design.md                   # コンポーネント詳細設計
│       ├── specs/                      # 仕様書ディレクトリ (予約: index.md, index.link.tsv, id-seq-no.tsv, AGENTS.md, incremental/)
│       ├── models/                     # 個別物理モデル仕様
│       ├── raw/                        # コンポーネント不変ファイル・正本資料
│       ├── wiki/                       # コンポーネントAI文書・ナレッジ
│       └── backlog/                    # コンポーネントバックログ・進捗管理
│           ├── status.tsv              # 仕様ステータス台帳 (KVTsv形式)
│           ├── wbs.md                  # WBS (実装タスク・TODO・issues 台帳・自動生成)
│           ├── spec.md                 # 機能仕様実装ステータス台帳 (自動生成)
│           ├── tasks/                  # 実装タスク詳細ファイル (<SPEC-I-ID>.md をフラットに配置)
│           ├── todos/                  # TODO管理ファイル
│           └── issues/                 # 課題管理ファイル
├── apps/                               # アプリケーションソースコード
│   └── [<group>/]<component>/          # 各コンポーネントの実装コード
├── data/                               # ドメインデータ・データセット・コンテンツ層 (配下構造は任意)
├── deploy/                             # デプロイ構成・インフラ設定・環境定義 (配下構造は任意)
├── dist/                               # 【非追跡対象】ビルド成果物・パブリッシュ用静的出力 (配下構造は任意)
├── tests/                              # テスト関連コード・検証用ファイル
│   ├── [<group>/]<component>/          # コンポーネントテスト（統合テスト・<test:appid>）
│   ├── performance/                    # パフォーマンス・負荷テスト
│   ├── security/                       # セキュリティ・脆弱性テスト
│   └── checklists/                     # 汎用検証チェックリスト（台帳およびテスト仕様書）
│       ├── checklist-<name>.md         # テスト仕様台帳
│       └── <name>/                     # 個別テスト仕様書ディレクトリ
│           └── <TESTSPEC-ID>.md        # テスト仕様書
├── scripts/                            # 各種処理のエントリーポイントスクリプト群（tools/ を使用）
└── tools/                              # scripts/ からのみ参照される内部ツール・ヘルパーモジュール群

Directory Details

Root Level Files

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

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

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

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

.local/

AIエージェントおよび開発者のローカル専用作業領域および記憶領域です（ 非追跡対象 / 詳細は local-guide.md 参照）。

  • .local/workspace/: 一時作業領域（<workspace>）。一時タスク（tasks.toml）や改善提案書（*-proposal.md）の作成場所。

  • .local/memory/: 会話や作業で得られた知見・失敗・教訓の蓄積領域（write-memory スキル連携）。

  • .local/worklog/: セッションごとの作業日報および残作業（todo.md）の管理領域（write-worklog スキル連携）。

  • .local/workplan/: 具体的な作業手順（STEP-<ID>）、作業記録、作業メモの一時管理領域（write-workplan スキル連携）。

  • .local/artifacts/: 一時的な生成成果物（画像・変換出力等）の保管領域。

  • .local/docs/ / .local/resources/: ローカル検証専用の非追跡ドキュメントおよびリソースデータ。

  • .local/logs/: ツールやスクリプトの実行ログ保管領域。

.mise/

aidev-template 基盤の共通タスク設定および実行用スクリプト群を管理します。

  • .mise/config.toml: テンプレート共通のタスク定義ファイルです。

  • .mise/scripts/: .mise/config.toml から呼び出される各種処理のエントリーポイントスクリプト群です。

  • .mise/tools/: .mise/scripts/ やテンプレートタスクからのみ参照される内部ツール・ライブラリ・ヘルパーモジュール群です。

docs/

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

Root Documents in docs/

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

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

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

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

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

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

  • docs/documents.md: プロジェクト共通のドキュメント体系、設計書、ガイドライン、台帳の役割および各ドキュメントへの誘導手順をまとめた文書インデックス。

  • docs/actions.md: 開発状況や作業目的に応じて実行すべきアクション、関連スキル、参照先ガイド、および具体的な実行フローをまとめたアクションインデックス。

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

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

  • docs/backlog/slices/: 実装スライス資料を配置するディレクトリ（ 追跡対象 ）。

  • 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-status スキルによるレビューレポートを蓄積）。非wikiファイルでデータを使用する場合は、wikiファイルではなく必ず docs/raw/ 等の正本データを直接参照・使用してください。

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

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

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

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

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

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

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

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

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

    • status.tsv: 機能仕様および増分仕様のステータス管理台帳（KVTsv形式）。

    • wbs.md: WBS（実装タスク・TODO・issues 台帳・自動生成ビュー）。

    • spec.md: 機能仕様実装ステータス台帳（自動生成ビュー）。

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

    • todos/: TODO管理項目。

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

apps/

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

  • apps/[<group>/]<component>/: コンポーネント単位の実装コードです（省略記法 <src:<appid>>）。docs/[<group>/]<component>/（<doc:<appid>>）および tests/[<group>/]<component>/（<test:<appid>>）と1対1で対応します。

Note

各ソフトウェアコンポーネント（AppID）とディレクトリパス（BaseDir）のマッピング、および省略パス記法（<src:<appid>>, <doc:<appid>>, <test:<appid>>）は GEMINI.project.md にて一括定義されます。

data/

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

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

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

deploy/

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

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

dist/

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

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

tests/

テストコードおよび検証用チェックリストを配置します（詳細は testing-guide.md 参照）。単体テストは各ソフトウェアコンポーネントのソースコード内（apps/ 配下等）に配置します。

  • tests/[<group>/]<component>/: コンポーネントが別のコンポーネントを利用するコンポーネントテスト（統合テスト・<test:appid>）を配置します。

  • tests/performance/: システムの負荷やパフォーマンスに関するテストを配置します。

  • tests/security/: セキュリティ検証や脆弱性テストを配置します。

  • tests/checklists/: パフォーマンスおよびセキュリティ以外の汎用的な検証チェックリストを配置します。

    • checklist-<name>.md: テスト対象機能群やサブシステム（<name>）に対応するテスト仕様台帳。

    • <name>/<TESTSPEC-ID>.md: 個別の検証シナリオやテスト項目を管理するテスト仕様書。

scripts/ and tools/

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

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

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

Important

テンプレートタスクにおける配置規則: .mise/config.toml から使用するツール・スクリプトは .mise/scripts/ および .mise/tools/ に配置します。<root>/scripts/ および <root>/tools/ は使用しません。