# Zed モノレポのワークスペース・クレート規則

[zed-industries/zed](https://github.com/zed-industries/zed) のソースコードを読み解くための、ワークスペース構成とクレート分割に関する規則のまとめ。

---

## 1. ワークスペース構成

### 単一ワークスペース

- リポジトリ直下の `Cargo.toml` が `[workspace]` を持ち、`crates/` 以下のすべてのクレート（200個超）を members として束ねる単一ワークスペース。
- `default-members = ["crates/zed"]` が指定されており、ルートで `cargo run` するとエディタ本体が起動する。
- `Cargo.lock` はルートに1つだけ。すべてのクレートで共有される。
- ルートに `rust-toolchain.toml` / `clippy.toml` / `rustfmt.toml` / `.cargo/` を置き、ワークスペース全体に共通設定を効かせる。

### 内部依存は `[workspace.dependencies]` に集約

ルート `Cargo.toml` に **すべての内部クレートを path 指定で列挙** する:

```toml
[workspace.dependencies]
acp_thread       = { path = "crates/acp_thread" }
action_log       = { path = "crates/action_log" }
agent            = { path = "crates/agent" }
agent_ui         = { path = "crates/agent_ui" }
anthropic        = { path = "crates/anthropic" }
# ... 200個以上続く
```

外部クレート（serde, tokio, フォーク版 calloop など）も同じ場所に集約され、バージョンや git rev を一元管理する。

### 各クレートは `.workspace = true` で参照

個々の `crates/<name>/Cargo.toml` ではバージョン番号もパスも書かない:

```toml
[dependencies]
gpui.workspace = true
project.workspace = true
serde.workspace = true
```

これにより:
- バージョン更新やフォーク差し替えがルート1ファイルで完結
- 同じ依存が複数バージョンに分裂する事故が起きない
- 新しいクレートの追加は「フォルダ作成 → ルートに1行追加 → 使う側で `name.workspace = true`」だけ

### `publish = false`

ワークスペース全体で `publish = false`。crates.io には公開されないため、`editor` や `project`、`language` のような一般名詞を平気で使える。

---

## 2. クレート命名規則

### 表記ルール

- **`snake_case` で統一**。ハイフンや CamelCase は使わない。
- **全部小文字**、略語も小文字（`lsp`, `rpc`, `acp`, `aws`, `ui`）。
- **ディレクトリ名 = `package.name` = `[workspace.dependencies]` のキー** で完全一致。grep しやすさを優先。

### 命名パターン

#### 1. コア基盤は1語の名詞

`zed` / `gpui` / `editor` / `project` / `workspace` / `language` / `theme` / `ui` / `lsp` / `rpc` / `audio` / `assets` / `askpass`

#### 2. 機能ファミリーは「共通プレフィックス + サフィックス」

```
agent / agent_ui / agent_ui_v2 / agent_settings / agent_servers
auto_update / auto_update_ui / auto_update_helper
assistant_text_thread / assistant_slash_command / assistant_slash_commands
acp_thread / acp_tools
```

サフィックスの慣習:

| サフィックス | 役割 |
|---|---|
| `_ui` | 機能のビュー/ウィジェット層（コアロジックとは分離） |
| `_settings` | 設定スキーマと読み込み |
| `_servers` | 外部プロセス連携アダプタ |
| `_helper` | 補助バイナリ |
| `_v2` | 既存版と並行する新実装の隔離 |
| `_tools` | デバッグ/開発者向けユーティリティ |

#### 3. 外部プロトコル/ベンダー連携はその名前そのまま

`anthropic` / `bedrock` / `aws_http_client` のように、相手のサービスや仕様の名前をそのまま使う。`acp_*` (Agent Client Protocol) のようにプロトコルの略号を頭に付けて系列化するのも同様。

---

## 3. クレート分割の方針

### `zed` クレートは薄いシェル

`crates/zed/` の中身は最小限:

- `main.rs` — エントリポイント、CLI 引数、シングルインスタンス処理、クラッシュハンドラ、パス初期化
- `zed.rs` — グローバル action ハンドラ登録、`initialize_workspace` でのパネル組み立て
- `build.rs` / `RELEASE_CHANNEL`

`app.run(...)` の中身は **200個以上のクレートの `init(cx)` を正しい順序で呼ぶだけ**:

```rust
settings::init(cx);
theme::init(cx);
client::init(&client, cx);
workspace::init(app_state.clone(), cx);
editor::init(cx);
project_panel::init(cx);
agent_ui::init(fs, client, prompt_builder, languages, cx);
git_ui::init(cx);
// ...
```

`zed` は依存グラフの頂点に立つ唯一のクレートで、機能の置き場所ではなく **配線盤 (wiring)** として存在する。**「どこに置くか迷ったら `zed` 以外のどこかに置く」** が鉄則。

### 境界を切る基準

#### ① レイヤー（下から上への単方向依存）

```
gpui                                       ← UI フレームワーク
  ↓
text / language / fs / rpc / settings /    ← ドメインの基本型
theme / ui
  ↓
project / lsp / git / terminal /           ← サービス層
multi_buffer
  ↓
editor / workspace                         ← 中核機能
  ↓
project_panel / git_ui / agent_ui /        ← 個別機能 (パネル/ビュー)
diagnostics / search / ...
  ↓
zed                                        ← 配線だけ
```

下のレイヤーは上のレイヤーを知らない。逆方向の拡張点は trait（`workspace::Item`、`workspace::Panel` など）として下層が公開し、上層が実装する。

#### ② ロジックと UI の分離

GPUI 依存を上層に閉じ込めるため、ロジックと UI を別クレートに切る:

| ロジック | UI |
|---|---|
| `agent` | `agent_ui` |
| `auto_update` | `auto_update_ui` |
| `git` | `git_ui` |
| `project` | `project_panel` |

UI 側はロジック側を知るが、ロジック側は UI 側を知らない。

#### ③ `Project` と `Workspace` の二分

Zed の設計で最も象徴的な分割:

- **`project`** — worktree、LSP、ファイルシステム、Git といったサービスを束ねる。ヘッドレスでも動く側。
- **`workspace`** — ペイン分割、ドック、パネル、ステータスバーといったウィンドウ表示を束ねる。GPUI に強く依存する側。

これにより `Project` をリモートマシンで走らせ `Workspace` をローカルで走らせる、というリモート開発が素直に成立する。

#### ④ trait 境界 + Fake 実装

下層の重要な抽象は trait で公開し、テストでは Fake を差し込む:

- `fs::Fs` ↔ `FakeFs`
- `git::GitRepository` ↔ Fake 実装
- `language::LanguageRegistry`
- `gpui::Element`、`workspace::Item`/`Panel`

trait が置かれているクレートがそのまま境界になる。「どこまでがプラグイン可能か」がクレート一覧から読み取れる。

#### ⑤ 外部世界との接点ごとにクレートを切る

新規追加で既存クレートを編集しなくて済むように、外部依存ごとに独立させる:

- `lsp` / `dap` / `rpc` (プロトコル層)
- `anthropic` / `bedrock` / `open_ai` (LLM プロバイダごと)
- `aws_http_client` (特定の HTTP クライアント実装)
- `acp_thread` / `acp_tools` (Agent Client Protocol)
- `extension_host` + `extension_api` (拡張機能 WASM サンドボックス境界)

#### ⑥ コンパイル時間最適化

頻繁に編集される `editor` のような大きいクレートを切り離すことで、並列ビルドとインクリメンタルコンパイルの効率を上げる。ルート `Cargo.toml` には単一ファイルクレートに `codegen-units = 1` を効かせる調整も含まれる。

---

## 4. 「core」クレートを作らない

Zed には `core` / `common` / `shared` / `zed_core` といったクレートが**意図的に存在しない**。「コア」になりそうなものは機能軸で水平に分割される:

| ありがちな "core" の中身 | Zed での置き場所 |
|---|---|
| 基本データ型 (Rope, Point, Anchor) | `text` |
| ファイルシステム抽象 | `fs` (`Fs` trait + `FakeFs`) |
| 設定の読み書き | `settings` |
| テーマ・色 | `theme` |
| 共通 UI コンポーネント | `ui` |
| 汎用ユーティリティ関数 | `util` |
| RPC/シリアライズ | `rpc` / `proto` |
| ロギング | `zlog` |
| 言語抽象 | `language` |

### `core` を作らない理由

1. **ビルドグラフの直列化を避ける** — `core` を作るとほぼ全クレートがそこに依存し、1行触るたびに数百クレートが再コンパイルされる。並列ビルドの利点が消える。
2. **"ゴミ捨て場" 化の防止** — `core` や `common` は置き場所に迷ったコードが流れ込む磁石になり、責務が肥大化して循環依存の温床になる。Zed は **「迷ったら新しいクレートを作る」** 方向に振る。
3. **依存方向のドキュメント化** — クレートを細かく分けると `Cargo.toml` を見るだけで何に依存し何に依存していないかが一覧できる。`core` があるとこの情報量がゼロになる。

### 例外的な `util`

`crates/util` は雑多な汎用ヘルパ（`ResultExt`, paths, debouncer 等）が入る "ややコアっぽい" クレートだが:

- 名前は `core` ではなく `util` (補助関数の入れ物の慣習)
- GPUI にも `editor` にも依存しない、完全な下層
- trait や中核データ型は置かない (それは `text` や `fs` の役目)

責務を「補助関数集」に限定することでゴミ捨て場化を防いでいる。

---

## 5. まとめ

Zed のクレート分割の優先順位:

1. **`zed` には何も入れない** — 機能は必ず別クレートに押し出し、`zed` は init 呼び出しと CLI と main だけを持つ
2. **下から上への単方向依存** — 上層が必要な拡張点は trait で下層に公開する
3. **ロジック / UI を分ける** — `xxx` と `xxx_ui` のペア、GPUI 依存を上層に閉じ込める
4. **`Project` と `Workspace` を分ける** — ヘッドレス/リモート実行可能性のため
5. **外部世界 (プロトコル・ベンダー・拡張) ごとにクレートを切る** — 新規追加を「ファイル追加だけ」で済ませる
6. **Fake が置けるところに trait を置く** — テスト境界 = アーキテクチャ境界
7. **`core` を作らない** — 万能箱の代わりに責務を限定した小さな箱を用意する

クレート数の多さは管理コストではなく、**境界を守るためのコスト払い**である。