diff --git a/CHANGELOG.md b/CHANGELOG.md
index c8080fc..b131b03 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,11 @@
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-08-23
+
+プロジェクト設定を `project.yml` へ移行する破壊的変更を含みます。プラグイン側の
+プロジェクト定義も本バージョンに合わせた更新が必要です (`requires.devbase: ">=3.0.0"`)。
+
 ### Changed
 - **1 プロジェクト = 1 コンテナ = 複数リポジトリ**に対応しました。プロジェクトが開発対象と
   するリポジトリは `projects/<name>/project.yml` の `repos` 配列で指定し、すべてが同じ
@@ -223,5 +228,6 @@ OSS 化に伴う初回リリース。devbase は本バージョンより `devbas
 ### Removed
 - 「公式レジストリ」固定の概念を廃止。各レジストリは対等な扱いとなる。
 
-[Unreleased]: https://github.com/devbasex/devbase/compare/v2.2.0...HEAD
+[Unreleased]: https://github.com/devbasex/devbase/compare/v3.0.0...HEAD
+[3.0.0]: https://github.com/devbasex/devbase/compare/v2.2.0...v3.0.0
 [2.2.0]: https://github.com/devbasex/devbase/releases/tag/v2.2.0
diff --git a/docs/developer/architecture.md b/docs/developer/architecture.md
index 963f3bb..c3af02e 100644
--- a/docs/developer/architecture.md
+++ b/docs/developer/architecture.md
@@ -1,6 +1,6 @@
 # devbase アーキテクチャ概要
 
-devbase v2.2.0 のアーキテクチャ設計と内部構造について説明する。
+devbase v3.0.0 のアーキテクチャ設計と内部構造について説明する。
 
 ## 全体構成
 
diff --git a/docs/plugin-dev/plugin-yml-reference.md b/docs/plugin-dev/plugin-yml-reference.md
index 7e70c94..88b52fd 100644
--- a/docs/plugin-dev/plugin-yml-reference.md
+++ b/docs/plugin-dev/plugin-yml-reference.md
@@ -1,7 +1,7 @@
 # plugin.yml リファレンス
 
-`plugin.yml` はPluginリポジトリのルートに配置する設定ファイルです。
-Pluginのメタ情報とプロジェクト一覧を定義します。
+`plugin.yml` は Plugin ディレクトリのルートに配置する設定ファイルです。
+Plugin のメタ情報（名前・バージョン・必要な devbase 本体のバージョンなど）を定義します。
 
 ---
 
@@ -10,10 +10,13 @@ Pluginのメタ情報とプロジェクト一覧を定義します。
 ```mermaid
 flowchart TB
     subgraph repo["Pluginリポジトリ"]
-        PY["plugin.yml"]
-        subgraph projects["projects/"]
-            P1["my-project-a/"]
-            P2["my-project-b/"]
+        RY["registry.yml<br/>(リポジトリが持つPlugin一覧)"]
+        subgraph plugin["my-plugin/"]
+            PY["plugin.yml<br/>(Pluginのメタ情報)"]
+            subgraph projects["projects/"]
+                P1["my-project-a/"]
+                P2["my-project-b/"]
+            end
         end
     end
     subgraph devbase["devbaseルート"]
@@ -26,7 +29,7 @@ flowchart TB
             S2["my-project-b → plugins/my-plugin/projects/my-project-b"]
         end
     end
-    PY -->|"devbase plugin install"| PS
+    RY -->|"devbase plugin install"| PS
     repo -->|clone| IP
     IP -->|symlink| S1
     IP -->|symlink| S2
@@ -37,45 +40,29 @@ flowchart TB
 ## 基本構造
 
 ```yaml
-plugins:
-  - name: my-plugin
-    version: 1.0.0
-    description: "プラグインの説明"
-    projects:
-      - name: my-project-a
-        description: "プロジェクトAの説明"
-        path: projects/my-project-a
-      - name: my-project-b
-        description: "プロジェクトBの説明"
-        path: projects/my-project-b
+name: my-plugin
+version: "1.0.0"
+description: "プラグインの説明"
+requires:
+  devbase: ">=3.0.0"
+priority: 0
 ```
 
+Plugin が提供するプロジェクトは `projects/` 配下のディレクトリから**自動的に検出**されます。
+`plugin.yml` にプロジェクトを列挙する必要はありません。
+
 ---
 
 ## フィールド一覧
 
-### トップレベル
-
-| フィールド | 型 | 必須 | 説明 |
-|-----------|-----|------|------|
-| `plugins` | array | Yes | Plugin定義のリスト |
-
-### Plugin定義 (`plugins[*]`)
-
-| フィールド | 型 | 必須 | 説明 |
-|-----------|-----|------|------|
-| `name` | string | Yes | Plugin名 |
-| `version` | string | Yes | セマンティックバージョン |
-| `description` | string | No | Pluginの説明 |
-| `projects` | array | Yes | プロジェクト定義のリスト |
-
-### プロジェクト定義 (`plugins[*].projects[*]`)
-
-| フィールド | 型 | 必須 | 説明 |
-|-----------|-----|------|------|
-| `name` | string | Yes | プロジェクト名 |
-| `description` | string | No | プロジェクトの説明 |
-| `path` | string | Yes | リポジトリルートからの相対パス |
+| フィールド | 型 | 必須 | 既定値 | 説明 |
+|-----------|-----|------|--------|------|
+| `name` | string | Yes | ディレクトリ名 | Plugin名 |
+| `version` | string | No | `0.1.0` | セマンティックバージョン |
+| `description` | string | No | `""` | Pluginの説明 |
+| `requires` | map | No | なし | 動作要件。現在は `devbase` キーのみ |
+| `requires.devbase` | string | No | なし | 必要な devbase 本体の最低バージョン（例: `">=3.0.0"`） |
+| `priority` | int | No | `0` | プロジェクト名が他Pluginと衝突したときの優先度。大きいほうが `projects/<name>` を取る |
 
 ---
 
@@ -83,9 +70,10 @@ plugins:
 
 ### `name`（Plugin名）
 
-Pluginを一意に識別する名前です。
+Pluginを一意に識別する名前です。省略するとディレクトリ名が使われますが、
+`registry.yml` の `plugins[*].name` と食い違うと追跡しにくいため明示してください。
 
-**バリデーションルール:**
+**命名規則（推奨）:**
 
 - 使用可能文字: 英小文字、数字、ハイフン（`a-z`, `0-9`, `-`）
 - 先頭はアルファベット
@@ -110,8 +98,8 @@ name: a             # 2文字未満
 **フォーマット:** `MAJOR.MINOR.PATCH`
 
 ```yaml
-version: 1.0.0
-version: 2.3.1
+version: "1.0.0"
+version: "2.3.1"
 ```
 
 | 要素 | 意味 | インクリメントするとき |
@@ -122,41 +110,68 @@ version: 2.3.1
 
 ### `description`
 
-Pluginまたはプロジェクトの説明文です。
+Pluginの説明文です。
 `devbase plugin list` で一覧表示されるため、簡潔に記述してください。
 
 ```yaml
 description: "EC事業部のマイクロサービス群"
 ```
 
-### `projects`
+### `requires`
 
-Pluginに含まれるプロジェクトの一覧です。
-1つのPluginに複数のプロジェクトを含めることができます。
+この Plugin が動作するために必要な devbase 側の条件を書きます。
+現在使えるキーは `devbase`（本体の最低バージョン）だけです。
 
-### `projects[*].name`（プロジェクト名）
+```yaml
+requires:
+  devbase: ">=3.0.0"
+```
 
-プロジェクトを一意に識別する名前です。
-インストール時に `projects/<name>/` としてシンボリックリンクが作成されます。
+| 値 | 意味 |
+|----|------|
+| `">=3.0.0"` | devbase 3.0.0 以上が必要 |
+| 省略 | バージョン要件なし（どの版でも導入を試みる） |
 
-**バリデーションルール:**
+**devbase 3.0.0 以降のPluginは `">=3.0.0"` を指定してください。**
+プロジェクト設定を `projects/<name>/project.yml` で記述する形式は devbase 3.0.0 で導入されたもので、
+2.x 系の devbase は `project.yml` を読めません。要件を書かないまま 2.x へ導入されると、
+インストールは成功するのに `devbase up` の段階で初めて失敗します。
 
-- Plugin名と同様の命名規則
-- devbase全体で一意であること（他のPluginのプロジェクト名と重複不可）
+> `requires.devbase` を上げるのは、**Plugin が `project.yml` 形式へ移行したタイミング**です。
+> 本体の版数と一緒に自動では上がりません。
 
-### `projects[*].path`
+### `priority`
 
-リポジトリルートからの相対パスで、プロジェクトディレクトリの位置を指定します。
+同じ名前のプロジェクトを複数のPluginが提供したときに、どちらが `projects/<name>` の
+シンボリックリンクを取るかを決める整数です（既定 `0`、大きいほうが勝ち）。
+負けた側は `projects/<name>.<owner>--<repo>` の形でリンクされ、どちらも利用できます。
 
 ```yaml
-path: projects/my-project
+priority: 10
 ```
 
-**注意事項:**
+### プロジェクトの検出
+
+`plugin.yml` にプロジェクト一覧は書きません。Plugin ディレクトリ直下の `projects/` にある
+ディレクトリ（`.` で始まるものを除く）がそのままプロジェクトとして扱われ、インストール時に
+devbase ルートの `projects/<name>/` へシンボリックリンクが作成されます。
+
+```
+my-plugin/
+├── plugin.yml
+└── projects/
+    ├── my-project-a/    -> projects/my-project-a として公開される
+    │   ├── compose.yml
+    │   ├── project.yml
+    │   └── env
+    └── my-project-b/
+        ├── compose.yml
+        ├── project.yml
+        └── env
+```
 
-- パスの先頭に `/` を付けない（相対パスで記述する）
-- 指定したディレクトリに `compose.yml` が存在すること
-- 慣例として `projects/` ディレクトリ配下に配置する
+各プロジェクトディレクトリの中身は
+[クイックスタート](quickstart.md) と [project.yml リファレンス](../user/project-yml.md) を参照してください。
 
 ---
 
@@ -167,14 +182,11 @@ path: projects/my-project
 最もシンプルな構成です。
 
 ```yaml
-plugins:
-  - name: my-api
-    version: 1.0.0
-    description: "APIサーバー開発環境"
-    projects:
-      - name: my-api
-        description: "APIサーバー"
-        path: projects/my-api
+name: my-api
+version: "1.0.0"
+description: "APIサーバー開発環境"
+requires:
+  devbase: ">=3.0.0"
 ```
 
 ディレクトリ構造:
@@ -185,6 +197,7 @@ my-api/
 └── projects/
     └── my-api/
         ├── compose.yml
+        ├── project.yml
         └── env
 ```
 
@@ -193,20 +206,11 @@ my-api/
 関連するプロジェクトをまとめて管理する場合に使います。
 
 ```yaml
-plugins:
-  - name: ecommerce
-    version: 2.1.0
-    description: "ECサイト開発環境一式"
-    projects:
-      - name: ec-frontend
-        description: "フロントエンド（Next.js）"
-        path: projects/ec-frontend
-      - name: ec-backend
-        description: "バックエンドAPI（Go）"
-        path: projects/ec-backend
-      - name: ec-admin
-        description: "管理画面（Laravel）"
-        path: projects/ec-admin
+name: ecommerce
+version: "2.1.0"
+description: "ECサイト開発環境一式"
+requires:
+  devbase: ">=3.0.0"
 ```
 
 ディレクトリ構造:
@@ -217,37 +221,47 @@ ecommerce/
 └── projects/
     ├── ec-frontend/
     │   ├── compose.yml
+    │   ├── project.yml
     │   └── env
     ├── ec-backend/
     │   ├── compose.yml
+    │   ├── project.yml
     │   └── env
     └── ec-admin/
         ├── compose.yml
+        ├── project.yml
         └── env
 ```
 
 ### 1リポジトリに複数Pluginを含む場合
 
-`plugins` 配列に複数のPlugin定義を記述します。
-チーム横断で1つのリポジトリを共有する場合に使えます。
+`plugin.yml` は Plugin ごとに 1 ファイルです。1 つのリポジトリで複数の Plugin を配布する場合は、
+Plugin ごとにディレクトリを分けてそれぞれに `plugin.yml` を置き、リポジトリルートの
+`registry.yml` に一覧を記述します。
+
+```
+my-registry/
+├── registry.yml
+├── team-alpha/
+│   ├── plugin.yml
+│   └── projects/alpha-service/
+└── team-beta/
+    ├── plugin.yml
+    └── projects/beta-service/
+```
+
+`registry.yml`:
 
 ```yaml
+name: my-registry
+description: "社内レジストリ"
 plugins:
   - name: team-alpha
-    version: 1.0.0
+    path: team-alpha
     description: "Alphaチームのプロジェクト"
-    projects:
-      - name: alpha-service
-        description: "Alphaチームのサービス"
-        path: projects/alpha-service
-
   - name: team-beta
-    version: 1.2.0
+    path: team-beta
     description: "Betaチームのプロジェクト"
-    projects:
-      - name: beta-service
-        description: "Betaチームのサービス"
-        path: projects/beta-service
 ```
 
 ---
@@ -258,7 +272,7 @@ devbaseには似た名前の2つのファイルがあります。混同しない
 
 | 項目 | plugin.yml | plugins.yml |
 |------|-----------|-------------|
-| 配置場所 | Pluginリポジトリのルート | devbaseルートディレクトリ |
+| 配置場所 | Pluginディレクトリのルート | devbaseルートディレクトリ |
 | 管理者 | Plugin開発者 | devbase（自動管理） |
 | 用途 | Pluginの定義・メタ情報 | インストール済みPluginのレジストリ |
 | Git管理 | Plugin側のリポジトリで管理 | devbase側のリポジトリで管理 |
@@ -290,17 +304,16 @@ plugins:
 
 ## バリデーション
 
-`plugin.yml` は `devbase plugin install` 実行時に自動的にバリデーションされます。
+`devbase plugin install` はリポジトリを clone したあと `registry.yml` と `plugin.yml` を読み込みます。
 
 ### よくあるエラーと対処
 
 | エラーメッセージ | 原因 | 対処 |
 |----------------|------|------|
-| `Invalid plugin name` | 命名規則違反 | 英小文字・数字・ハイフンのみ使用 |
-| `Invalid version format` | SemVer形式でない | `MAJOR.MINOR.PATCH` 形式に修正 |
-| `Project directory not found` | pathが不正 | ディレクトリの存在を確認 |
-| `compose.yml not found` | compose.ymlが未配置 | 指定ディレクトリに配置 |
-| `Duplicate project name` | プロジェクト名が重複 | 一意な名前に変更 |
+| `Failed to parse .../plugin.yml` | YAML の構文エラー | インデント・引用符を確認 |
+| `No registry.yml found in repository` | リポジトリルートに `registry.yml` が無い | リポジトリルートに配置する |
+| `Plugin '<name>' not found in <repo>` | `registry.yml` に該当 Plugin の記載が無い | `plugins[*].name` を確認 |
+| `Plugin directory not found: <path>` | `registry.yml` の `path` が実在しない | `path` とディレクトリ名を突き合わせる |
 
 ---
 
diff --git a/docs/plugin-dev/quickstart.md b/docs/plugin-dev/quickstart.md
index 52c102a..db45c53 100644
--- a/docs/plugin-dev/quickstart.md
+++ b/docs/plugin-dev/quickstart.md
@@ -6,7 +6,7 @@ devbase用のPluginを作成し、公開するまでの手順を解説します
 
 ## 前提条件
 
-- devbase 2.2.0 以上がインストール済み
+- devbase 3.0.0 以上がインストール済み
 - Git がインストール済み
 - Docker / Docker Compose が利用可能
 
@@ -23,20 +23,23 @@ git init
 
 ### 1.2 plugin.yml の配置
 
-リポジトリのルートに `plugin.yml` を作成します。
-このファイルはPluginのメタ情報とプロジェクト一覧を定義します。
+リポジトリのルート（Plugin ディレクトリのルート）に `plugin.yml` を作成します。
+このファイルは Plugin のメタ情報を定義します。
 
 ```yaml
-plugins:
-  - name: my-plugin
-    version: 1.0.0
-    description: "サンプルプラグイン"
-    projects:
-      - name: my-project
-        description: "サンプルプロジェクト"
-        path: projects/my-project
+name: my-plugin
+version: "1.0.0"
+description: "サンプルプラグイン"
+requires:
+  devbase: ">=3.0.0"
+priority: 0
 ```
 
+**ポイント:**
+
+- プロジェクトは `projects/` 配下のディレクトリから自動的に検出されます。`plugin.yml` に一覧を書く必要はありません。
+- `requires.devbase` には **この Plugin が動作する devbase 本体の最低バージョン**を書きます。`project.yml` 形式のプロジェクト定義は devbase 3.0.0 以降でしか読めないため、`project.yml` を持つ Plugin（= 本手順で作るもの）は必ず `">=3.0.0"` を指定してください。
+
 > **補足:** `plugin.yml` のフォーマット詳細は [plugin.yml リファレンス](plugin-yml-reference.md) を参照してください。
 
 ---
diff --git a/docs/user/env-export-import.md b/docs/user/env-export-import.md
index 8eb9ce2..5997562 100644
--- a/docs/user/env-export-import.md
+++ b/docs/user/env-export-import.md
@@ -74,7 +74,7 @@ env/projects/<name>/.env
 ```yaml
 version: 1
 created_at: '2026-05-21T10:00:00+09:00'
-devbase_version: 2.2.0
+devbase_version: 3.0.0
 files:
   - path: env/global.env
     sha256: <64 文字 hex>
diff --git a/lib/devbase/__init__.py b/lib/devbase/__init__.py
index 24ca405..9eaa5dd 100644
--- a/lib/devbase/__init__.py
+++ b/lib/devbase/__init__.py
@@ -1,4 +1,4 @@
 """devbase - Docker-based Development Environment Manager"""
 
-__version__ = "2.2.0"
+__version__ = "3.0.0"
 __author__ = "devbase team"
diff --git a/lib/devbase/cli.py b/lib/devbase/cli.py
index 1371120..747b8d1 100644
--- a/lib/devbase/cli.py
+++ b/lib/devbase/cli.py
@@ -14,7 +14,7 @@
 try:
     from . import __version__
 except ImportError:
-    __version__ = "2.2.0"
+    __version__ = "3.0.0"
 
 logger = get_logger("devbase.cli")
 
diff --git a/lib/devbase/commands/status.py b/lib/devbase/commands/status.py
index 55d8bb2..65d104e 100644
--- a/lib/devbase/commands/status.py
+++ b/lib/devbase/commands/status.py
@@ -10,7 +10,7 @@
 try:
     from devbase import __version__
 except ImportError:
-    __version__ = "2.2.0"
+    __version__ = "3.0.0"
 
 logger = get_logger(__name__)
 
diff --git a/pyproject.toml b/pyproject.toml
index 7a03a1e..8af0bd1 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "devbase"
-version = "2.2.0"
+version = "3.0.0"
 description = "Docker-based Development Environment Manager"
 requires-python = ">=3.10"
 dependencies = [
diff --git a/uv.lock b/uv.lock
index 3e2a11d..b33e944 100644
--- a/uv.lock
+++ b/uv.lock
@@ -41,7 +41,7 @@ wheels = [
 
 [[package]]
 name = "devbase"
-version = "2.2.0"
+version = "3.0.0"
 source = { virtual = "." }
 dependencies = [
     { name = "boto3" },