effect-v3-to-v4

Effect v3 から v4 への移行

Effect リポジトリに含まれる生成済みの移行リファレンスを使って、Effect v3 → v4 の移行を進めます。名称変更、削除、シグネチャの変更はすべて上流のデータで確認できます。代替を推測してはいけません。

ワークフロー

以下の手順を順番に進めてください。各手順の詳細は、記載されているセクションを参照してください。

1. ローカルのチェックアウトをセットアップして検証する — 2 つのシャロークローンを用意します。既存の .repos/effect がある場合は、信頼する前に検証してください。「Setup: Local Checkouts」を参照してください。
2. MIGRATION.md と ls .repos/effect/migration/ を確認する — 背景とガイドのインデックスを把握します。「Reading Order」を参照してください。
3. package.json を移行する — 統合されたパッケージを削除し、残りの Effect パッケージすべての v4 バージョンをそろえます。型チェックの前に実施してください。そうしないと、存在しなくなったパッケージの未解決インポートが大量に出て、最初の実行結果がノイズに埋もれます。「Repo-Level Changes」を参照してください。
4. プロジェクトの型チェックを実行する（例：tsc --noEmit） — 初期エラーの一覧を取得します。
5. 型チェックが通るまで反復する。 各エラーについて、ルックアップの手順に従って API を特定します — migration/v3-to-v4.md でシンボルを検索し、「Reading Order」に従って調査を進めます — その後、呼び出し箇所を修正します。ファイル単位の修正は、「Delegating to Sub-Agents」に従ってサブエージェントに委任してください。エラーを解決せずに握りつぶしてはいけません。「Hard Prohibitions」を参照してください。
6. 完了する — 型チェックが通ることを確認し、テストを実行して結果を正直に報告します（完了の必須条件ではありません）。最後に概要を記述します。「Done Condition」を参照してください。

Setup: Local Checkouts

移行は、Effect の公式リポジトリをシングルブランチのシャロークローン 2 つに分けて進めます。

git clone --depth 1 --single-branch https://github.com/Effect-TS/effect .repos/effect
git clone --depth 1 --single-branch --branch v3 https://github.com/Effect-TS/effect .repos/effect-v3

• .repos/effect — v4（main）。MIGRATION.md、migration/ ガイド、v4 のソースが含まれています。
• .repos/effect-v3 — v3（v3 ブランチ）。以前のセマンティクスを確認するためだけの参照用です。

各クローンは個別に再実行でき、それぞれ別々に削除できます。1 つのクローンをブランチ間で共有するために git worktree を使わないでください。

既存のチェックアウトは、信頼する前に検証する

./.repos/effect は、古いセットアップ手順に従って、廃止された Effect-TS/effect-smol リポジトリからすでにクローンされている可能性があります。そのチェックアウトは古く、migration/v3-to-v4.md が含まれていません。使用前に検証してください。

git -C .repos/effect remote get-url origin   # must be the canonical Effect-TS/effect repo
node -p "require('./.repos/effect/packages/effect/package.json').version"   # must be 4.x

origin が effect-smol を指している場合、またはバージョンが 4.x でない場合は、そのディレクトリを削除して、上記の手順で再度クローンしてください。

Reading Order

1. 最初に MIGRATION.md を一度確認する（.repos/effect/MIGRATION.md）。
2. すべての API について、最初に migration/v3-to-v4.md を確認する。 生成されたリファレンスには、削除または変更されたすべての API が記載されています。検索して確認してください（後述）。全体を読むのは避けてください。
3. トピックごとのガイド（.repos/effect/migration/*.md）— 対応関係が名称変更ではなく書き換えを示す場合に確認します。たとえば、Context.Tag → Context.Service はシンボルの置き換えではなく、構造上の変更です。最初にすべて読むのではなく、MIGRATION.md のインデックスから必要に応じて参照してください。
4. v4 のソース（.repos/effect/packages/*/src/）— 置き換え先の実際のシグネチャを確認してから、その API に対するコードを記述します。
5. v3 のソース（.repos/effect-v3）— 旧 v3 のセマンティクスが不明な場合に限り、追加で確認します。

リファレンス文書全体を読まない

このスキルで最も重要なルールです。 migration/v3-to-v4.md は約 17,000 行、約 350k トークンあります。一度に読むとコンテキストウィンドウを使い切り、移行も失敗します。

必ず検索し、一致した行とその周辺の文脈だけを読みます。このファイルには 4 つのセクションがあります — Import Map、No Counterpart Imports、Removed Modules、API Reference（モジュールごとに ### `<v3 module path>` という見出しがあります）。項目は - `Old.symbol` -> `New.symbol`: <rationale> の形式の 1 行で検索でき、削除項目は代替案を明記した -> `none` の形式で示されています。

具体的な手順：

# Look up a specific v3 symbol
rg -n 'AnthropicTokenizer\.layer' .repos/effect/migration/v3-to-v4.md

# Read a whole module's section via its heading
rg -n -A 40 '^### `@effect/platform/FileSystem`' .repos/effect/migration/v3-to-v4.md

# Resolve a v3 import path in the Import Map
rg -n '^@effect/platform/FileSystem ' .repos/effect/migration/v3-to-v4.md

# List every module section for a package
rg -n '^### `@effect/cluster/' .repos/effect/migration/v3-to-v4.md

API は、遭遇したときに一度に 1 つずつ検索してください。Import Map で見つからなくても、そこで調査を打ち切らないでください。何もないと結論づける前に、Removed Modules と No Counterpart Imports の各セクションも確認してください。

リポジトリレベルの変更

API ごとに忠実に参照するだけでは、依然として壊れた package.json になります。これらは最初にまとめて処理してください。

• パッケージの統合。 @effect/platform、@effect/rpc、@effect/cluster などはコアの effect パッケージに統合されました。これらを package.json から削除し、Import Map に従ってインポートを書き換えてください。別パッケージのまま残るもの（@effect/platform-*、@effect/sql-*、@effect/ai-*、@effect/opentelemetry、@effect/atom-*、@effect/vitest、…）は依存関係として残してください。統合された v3 パッケージ（@effect/sql や @effect/cli を含む）は、npm の latest タグがまだ 0.x を指しています。すべてを latest に更新するのではなく、これらを削除してください。
• バージョンの統一。 現在の安定版 latest である 4.x リリースを対象にしてください。v4 では Effect エコシステムのパッケージはすべて同じバージョン番号を共有するため、残る effect / @effect/* の依存関係はすべて、同じ対応するバージョンを指定する必要があります。
• モジュールパスと安定性。 GA のインポートでは、effect/http、effect/rpc、effect/ai/LanguageModel などのパスを使います。安定性はインポートパスのセグメントではなく、JSDoc タグで宣言されます。@stability unstable の API はマイナーリリースで破壊的変更が行われる可能性があり、@stability experimental の API はパッチリリースで破壊的変更が行われる可能性があります。 effect/unstable/<module> のインポートを使用していたベータ版または RC を対象とするコードを移行する場合は、unstable セグメントを削除してください（例：effect/unstable/http → effect/http）。以前のパスとの互換性を保つエクスポートはありません。モジュールの移動によって、その API が安定化するわけではありません。

サブエージェントへの委任

ファイルごとの移行作業は多くのコンテキストを必要とするため、メインセッションのコンテキストを移行全体を通して維持できるよう、サブエージェントで行ってください。

• ファイル（またはモジュール）ごとにサブエージェントを起動し、そのファイル内で解決する v3 のシンボルを具体的に伝えてください。
• サブエージェントは編集内容と使用したマッピングを返します。メインセッションではエラーの一覧と進行中のサマリーを保持してください。
• サブエージェントにも、同じ参照手順（参照順序、rg のレシピ）と厳格な禁止事項が適用されます。
• サブエージェントでも参照ドキュメント全体を読むことはありません。サブエージェントのコンテキストが枯渇すると、そのファイルの移行が無駄になります。

厳格な禁止事項

• v3 形式の互換レイヤーを再導入しないでください。 古い名前を再エクスポートする v3-compat.ts を作成すると、型エラーが消え、コードベースがバージョン間に永久に固定されます。呼び出し箇所を v4 API に移行してください。
• 移行後の型エラーを抑えるために、any や as キャストを使わないでください。 そのようなエラーは通常、置き換え後の形が異なることを示しています。キャストすると、その情報が失われます。参照ドキュメントまたは v4 のソースに戻ってください。
• 存在しない API を作らないでください。 置き換え先はすべて、参照ドキュメント、トピックガイド、または v4 のソースを根拠として示せる必要があります。

完了条件

プロジェクトが v4 に対して型チェックに通ること。 v4 への移行は本質的に型レベルの作業です。未解決のインポートや変更されたシグネチャは、型チェックでのみ明らかになります。プロジェクトの型チェック（例：tsc --noEmit）を実行し、エラーがなくなるまで続けてください。

テストスイートの実行も推奨され、その結果は正直に報告する必要があります。ただし、完了の条件ではありません。移行中のリポジトリでは、無関係な理由でテストを実行できないことがよくあります。テストを通すためにテストを弱めないでください。

最終サマリーには、型チェックの結果、テスト結果（またはテストを実行しなかった理由）、構築した置き換えのすべて、そして橋渡しせずに報告した未解決事項を記載してください。