sanity-studio-upgrade

Sanity Studio のアップグレード計画

現在のリポジトリにある Sanity Studio のアップグレード計画を作成します。

この計画の価値は差し引きにあります。2 つのバージョン間のすべての破壊的変更をまとめたリストはすでにあり、これはチェンジログと呼ばれています。アップグレードの途中にいる人にとって、これは役に立ちません。このスキルでは、このリポジトリに適用される変更をはるかに短くまとめたリストと、人間にしか答えられない質問を提示します。

出力の信頼性を左右する 3 つのルール

1. バージョン番号を記憶だけで記載しないでください。調べて、実在することを確認してください。

パッケージのバージョンは毎週変わります。レポートに記載するバージョンはすべて、現在の状態についてはリポジトリのロックファイルから、アップグレード先についてはレジストリへのライブクエリから取得する必要があります。調べられない場合は、推測せず、その旨をレポートに記載してください。古い「最新」バージョンを示す計画は、読者がそれに基づいて作業してしまうため、計画がないよりも悪いものです。

さらに悪質な失敗として、あるパッケージが別のパッケージと同じバージョン番号を使うと思い込んだ結果、実際には一度も公開されていないバージョン番号を記載してしまうことがあります。その場合、インストールに失敗します。「バージョンが連動している」または「コアと一致する」と説明するバージョンは、必ず事前に実在確認をしてください。

API 名にも同じことが当てはまります。記憶に頼ったエクスポート名、インポートのサブパス、関数シグネチャは推測であり、読者がエディターに貼り付けることになる推測です。パッケージの README または exports マップから確認するか、コードスニペット自体にインラインの // VERIFY: コメントを付けてください。plugins.md のセクション 6 と report-template.md のセクション 8 を参照してください。

2. 読み取って報告してください。変更はしないでください。

ファイルを調べ、読み取り専用のシェルコマンドを実行し、レジストリに問い合わせてください。package.json、設定ファイル、ソースコードは編集しないでください。変更する内容を決めるのは読者です。コードを編集するプランナーは無効化されます。ユーザーから後でアップグレードの実行を明示的に依頼された場合は、それはユーザーの同意を得た別の作業です。

このルールの曖昧な解釈によって、問題のないコマンドまでエージェントがためらわないよう、実際の境界を明確にします。

• 禁止：リポジトリ内のファイルへの書き込み、リポジトリへのインストール、ロックファイルの変更。pnpm install、npm install、npm ci、および --no-install を付けない npx はすべて禁止です。
• 問題なし：ファイルの読み取り、および npm view、チェンジログの取得、またはリポジトリの外にある一時ディレクトリへの npm pack といったネットワーク経由の読み取り。その後、一時ディレクトリは削除してください。
• 読者に推奨するが、自分では実行しないこと：依存関係の予測を確定するには pnpm install --lockfile-only を実行します。これは、実行したときに何が起きるかとともに、読者が実行するコマンドとしてレポートに記載してください。ロックファイルを書き換えるため、自分では実行しないでください。

このスキルが何かを書き込むのは、型宣言を調べるために tarball を展開するときだけです。プロジェクトの外で行う方法については、plugins.md のセクション 6 を参照してください。

3. 確認できたことと推論したことを分けてください。

各調査結果は、次の 3 つの分類のいずれかに入ります。適用が確認済み（リポジトリ内に条件を見つけた）、人間による回答が必要（コードからは判断できない）、または該当なし（完全に省略する）。確認できなかった項目をレポートに加えて水増ししないでください。網羅的に見えるレポートより、正直で簡潔なレポートのほうが優れています。

見落としやすいため、明確に述べておくべき点があります。**読み取り専用のプランナーには依存関係リゾルバーがないため、変更後の依存関係ツリーの内容は把握できません。**重複排除に関する予測は、調査結果としてではなく、確認用のコマンドを添えた予想としてレポートに記載してください。package-coupling.md を参照してください。

検証ルール一覧

これらはリファレンスファイル内で番号によって参照されるため、各ファイルで繰り返すのではなく、ここにまとめて記載します。ここまでの内容が R1 から R4 で、残りはそれらに反する具体的な事例です。

	ルール	該当箇所
R1	バージョンを記憶だけで述べないでください。現在の状態はロックファイルから、目標バージョンはレジストリへのリアルタイム照会から取得してください。	version-lookup.md §1
R2	読み取って報告してください。リポジトリの内容を変更したり、何かをインストールしたり、ロックファイルを書き換えたりしないでください。	上記、および plugins.md §6
R3	検証済みの情報と推論を区別してください。変更後の依存関係ツリーに何が含まれるかを断言しないでください。プランナーには依存関係を解決する機能がありません。	package-coupling.md §6、plugins.md §5
R4	推奨するバージョンは、報告に記載する前に実際に公開済みであることを必ず確認してください。	version-lookup.md §3
R5	「X は Y を必要とする」と記載する場合は、その要件を読み取ったマニフェストと、その時点でインストールするバージョンを必ず明記してください。要件はメジャーバージョンをまたいで引き継がれません。	version-lookup.md §6
R6	バージョン範囲は読み取るのではなく、評価してください。||、<、または1つの節に比較演算子が2つ含まれているものは、まず semver.satisfies で評価してください。	version-lookup.md §6
R7	エクスポート一覧に名前があっても、実際に使用できるエクスポートとは限りません。宣言された型と @deprecated タグの有無を確認してください。never は削除済みを意味します。	plugins.md §6

R6 と R7 が設けられたのは、どちらもすでに自信満々の誤った具体的な助言につながったためです。問題なかった Node バージョンを非対応と報告した例と、「すでに満たされている」として必要なコード変更を記載した例です。これらの確認は簡単に実行でき、行わなくてもエラーが表面化しません。

対象範囲：v3 以降

このスキルでは、Studio v3 以降へのアップグレードを計画します。Studio v2 は対象外であり、そこで処理を必ず停止してください。

理由は、v2 が難しいからではありません。v2 から v3 への移行は、依存関係のアップグレードではなく、Studio の設定とプラグイン層の再構築だからです。設定形式が変更され、v2 のプラグインやオーバーライドの基盤だった「parts」システムは廃止され、パッケージは統合され、v2 時代のプラグインエコシステムの多くは移植されていません。この移行境界について生成される計画は、このスキルでは検証できない、自信ありげな具体論の羅列となり、何週間も作業に費やそうとしている人に渡されることになります。これは最悪の出力です。

v2 を検出したら、計画を立てずに停止して報告してください。 検出方法と報告内容はステップ 1 で説明します。v2 のプロジェクト用に計画ファイルを作成しないでください。

手順

ステップ 1：現状を確認し、バージョンの下限をチェックする

references/detect.md を読み、その指示に従ってください。読むべきファイル、実行するコマンド、記録すべき情報が記載されています。

最もよくある間違いは、package.json からバージョンを読むことです。キャレット範囲はインストール済みのバージョンではありません。ロックファイルから解決済みのバージョンを取得してください。

2 番目によくある間違いは、間違ったロックファイルを読むことです。リポジトリに複数のインストールがあり、それぞれの内容が異なる場合があります。計画の対象となるツリーを決め、そのツリーからすべてのバージョン情報を取得し、レポートのヘッダーにそのツリーを明記してください。

このリポジトリに Sanity Studio がない場合は、その旨を伝えて終了してください。

その後、ほかの作業に着手する前に、下限を確認してください。 解決済みの sanity のメジャーバージョンが 3 未満の場合、または sanity パッケージがなく、プロジェクトが @sanity/base や @sanity/desk-tool などの v2 時代のパッケージに依存している場合、または sanity.json はあるものの sanity.config.* がない場合、このプロジェクトは v2 です。そこで作業を止め、読者に次のことを伝えてください。

1. 検出した内容と、その根拠
2. このスキルが v3 以降を対象としていること、および v2 から v3 への移行がバージョンアップではなく、設定とプラグイン層の書き直しであるため、別種のプロジェクトである理由
3. 適切な出発点は公式の v2 から v3 への移行ガイドであり、二次情報としてあなたから受け取るのではなく、Sanity のドキュメントサイトで探すべきであること
4. 多くのプラグインは移植されていないため、v2 時代のプラグインはそれぞれ互換性を確認する必要があること
5. v3 に移行したら、このスキルを再度実行すれば残りの範囲を計画でき、その作業は大幅に小さくなること

役に立つ対応をしてください。理由を説明し、次に進む先を示して作業を止めるのは適切な回答です。拒否するのは適切ではありません。ただし、部分的な計画を提示して曖昧にしたり、v2 から v3 への作業量を見積もったりしないでください。

sanity.json と sanity.config.* の両方がある場合は、解決済みの sanity のバージョンを正式な情報として扱ってください。それ以外は v3 以降のプロジェクトに古い sanity.json が残っている場合、作業を止める理由ではなく、クリーンアップ項目として触れてください。

ステップ 2：対象範囲を決める

必要なバージョンは 2 つです。移行元（解決済みのインストール済みバージョン）と、移行先（ターゲット）です。

現在のバージョンと変更履歴を確実に確認する方法については、references/version-lookup.md を読んでください。

ターゲットは latest です。 これを推奨し、その理由も説明してください。短い範囲で移行しても、すべての作業を終えた時点ですでに後れを取っていることになります。さらに重要なのは、プラグインの現行バージョンは現行のコアに合わせているため、古いコアと現行のプラグインを組み合わせると、最新リリースにする場合より依存関係ツリーが悪化することが多い点です。ターゲットの公開日と、制約がある場合に備えた 1 行の代替案をレポートに記載してください。ただし、これは情報開示であり、推奨を弱めるものではありません。また、推奨を変えるものでもありません。読者が実際に提示した制約がある場合に限り、推奨から外れてもかまいません。その場合は、指定したバージョンの見直し日も記載してください。

レポートでは対象範囲を明示してください。v3 のプロジェクトと v5.31 のプロジェクトでは作業内容がまったく異なるため、読者はどちらなのかを知る必要があります。

ステップ 3：移行範囲に含まれる境界だけを読み込む

まず references/boundaries.md を読んでください。カバーする範囲、両端の取得ルール、対象範囲で必要となる境界ファイルを示した表をまとめた短いインデックスです。

その後、該当するファイルだけを読んでください。 境界の内容はメジャーバージョンごとに別ファイルに分かれているため、1 つの境界を越える範囲なら、すべてのファイルではなく 1 つのファイルだけを読み込みます。v6 に移行する v5.31 のプロジェクトで読むのは、インデックス、boundary.v6.md、deprecations.md だけです。それ以外は読みません。v4 と v5 のファイルはコンテキストを消費し、該当しない指摘を招くことになります。

各 boundary.v*.md には、そのメジャーバージョンへの移行時にまたぐ変更点に加えて、そのメジャーバージョン系列内で発生した未告知の変更も記載されています。境界を越える移行では、その上の系列のどこかに着地し、両方の変更点が必要になるためです。

次に references/package-coupling.md を読んでください。これはすべての対象範囲に適用されます。

ステップ 4：リファレンスでカバーされていない範囲を取得する

references/boundaries.md では、対象バージョン内でカバーされる範囲に2 つの境界が定められており、どちらも守る必要があります。

範囲のうち上限より上または下限より下に該当する部分については、変更履歴を取得してください。プロジェクトの開始バージョンが下限より下の場合、取得は 2 回必要です。現在のバージョンからその下限までと、上限から対象バージョンまでです。キュレーション済みの中間部分は、そのまま使用します。

下限も上限と同じくらい重要で、見落とされても気づきにくいものです。下限がなければ、ファイルが調査していない範囲まで信頼し、該当するものはないと報告してしまいます。それは検証済みの調査結果のように見えますが、実際には未調査の空白です。範囲が宣言された境界内にあるか、自分で取得して実際の内容を確認したのでない限り、その範囲に問題がないとは決して述べないでください。

最後の条件は、単なる念押しではありません。下限より下には上流の変更履歴がまったく存在しないため、取得してもほとんど何も返されません。取得結果が空でも、その範囲に問題がないという意味にはなりません。 boundaries.md には、どの範囲が該当するかと、代わりに何を報告すべきかが記載されています。そこで沈黙を「該当するものはない」と報告することが、このスキルが自信満々に誤った情報を伝える最も簡単な原因です。

マイナーリリースで、破壊的変更と明記されずにリリースされた破壊的変更に特に注意してください。40 回分ものマイナーリリースのノートを読む人はほとんどいないため、こうした変更は人々を驚かせます。リファレンスに記載されているのは既知の例です。ほかにもあると考えてください。

ステップ 5：適用可能性をテストする

候補となる変更ごとに、リポジトリ内で該当する条件を確認してください。コードから判断できない場合は、調査結果ではなく、人に確認する質問のセクションに記載します。

違いの例：

• 「カスタム認証プロバイダーが、組み込みプロバイダーに追加されるのではなく置き換えるようになった」→ 設定内に auth ブロックがあるか grep します。あるか、ないかです。判断可能です。
• 「デフォルトの検索戦略が変更され、結果が変わります」→ それが重要かどうかは、エディターでの検索方法によって異なります。判断できません。質問してください。

実際に評価できる条件を優先してください。grep -r "data-slate" は実際のテストです。「複雑なカスタムコンポーネントはありますか？」はそうではありません。

ステップ 6：依存関係グラフを解決する

references/package-coupling.md を適用してください。実際にアップグレードが失敗する原因のほとんどはここにあり、プロジェクトがどのパッケージに直接依存しているかによって決まるため、変更履歴からは分かりません。

最も重要なルールは、プロジェクトが直接依存している @sanity/* パッケージについて、対象となる sanity リリースがどのバージョンに依存しているかを確認し、そのバージョンに合わせることです。パッケージ自体の latest を選んではいけません。@sanity/ui のような共有パッケージに対して latest を選ぶと、依存関係ツリー内に 2 つのメジャーバージョンが混在し、重複したコンテキストエラーや、無関係なバグのように見えるスタイルのないコンポーネントが発生します。

ステップ 6b：プラグインを評価する

references/plugins.md を読み、プロジェクトにプラグインがあれば（ほとんどの場合そうです）、その指示に従ってください。

プラグインは Studio 自体よりも多くのアップグレードを阻むため、プラグイン専用の確認工程とレポートのセクションを設けます。次の 3 点を必ず反映してください。公開元だけで互換性を推測せず、すべてのプラグインの互換性を確認すること。互換性がないものについては、所有者によって判断を変えるのではなく、対応の進め方を決めること。そして、作成するスニペットのAPI の形状は、バージョンの確認とは別に、パッケージに照らして確認すること。互換性のあるバージョンでも、推奨しようとしているエクスポート名が変更されている場合があります。

ステップ 7：レポートを作成する

references/report-template.md に厳密に従ってください。ユーザーが別のパスを指定しない限り、リポジトリのルートにある SANITY-UPGRADE-PLAN.md に書き込みます。

ターミナルに出力するだけでなく、ファイルに書き込んでください。この計画は通常、この場にいない人にも共有する必要があります。リード、レビュアー、サポートエンジニアなどです。ファイルならプルリクエストに追加したり、スレッドに貼り付けたりできますが、ターミナル出力ではできません。

明示すべき判断事項

一度に飛び越えるのではなく、順序を提案します。 複数のメジャーバージョンを1つのコミットで飛び越えると、失敗の原因を特定できなくなります。各メジャーバージョンの最終リリースを中間地点として提案し、その理由も説明してください。変更のセットをそれぞれ切り分けられます。

ただし、中間地点に到達できなければ、実際の中間地点とは言えません。各地点でプラグインのバージョンを解決する必要があります。最近のメジャーバージョンのみを対象とするピア依存関係を持つプラグインがあると、中間地点にはインストールできない可能性があるからです。中間地点を解決できない場合は、検証済みの順序として示すのではなく、暫定的なものとして明記してください。仮定上の地点を増やすより、検証済みの地点を少なくするほうがよいです。

中間地点を省く場合は、その代償を明記します。 省略するのが適切なことはよくあります。該当する変更がNodeの最低バージョンだけという境界に、わざわざコミットを1つ割く価値はありません。また、メジャーバージョンを無理に重複させなければ到達できない地点なら、省略したほうがよいでしょう。しかし、その結果、1回のアップグレードで2つの境界を同時に越えることになります。それを防ぐために、この順序を立てているのです。省略する根拠を示しながら、その影響に触れない計画では、その判断に代償がないかのように見えてしまいます。

両方を伝えてください。中間地点を省いた理由と、まとめて越える境界のどちらが原因でも失敗が起こり得るため、デバッグでは計画を読むのではなく二分探索が必要になることです。1文で説明できます。読者は、その代償を理解したうえで判断できます。

作業規模は正直に見積もります。 プロジェクト内で @sanity/ui をインポートするファイルが2つあり、独自の認証機能もないなら、アップグレードは小規模だと伝えてください。入念に見せるために作業範囲を膨らませても、読者の時間を無駄にするだけです。同様に、プロジェクトが sanity/_internal からインポートしている場合や、独自コンポーネントが多数ある場合は、簡単に見える計画を作るのではなく、アップグレードは大規模だと伝えてください。

流し読みされても役立つ計画にします。 実際に流し読みされるでしょう。複数の境界を越える計画は数千語に及ぶことがあり、読む人は文書の確認に午後を費やすのではなく、これから1週間かけて作業に取り組もうとしています。そこで、計画の冒頭に全体像をひと目で把握できるようにまとめ、その下は作業の進行に合わせて参照する資料とし、調査結果は変更が生じたリリースごとではなく、読者が行う作業ごとにまとめます。避けるべき具体的な失敗は、見落とすと問題になる変更が、見た目だけの変更2つの間に、同じ視覚的な強さで均一な表に並んでいることです。長さが問題なのではありません。重要度が平坦なことが問題です。

作業を担うエンジニアに向けて書き、チームではなくコードベースの状態を説明します。 この計画は通常、顧客側の担当者が読みます。現状を生み出した判断に関わっていない人であることも少なくありません。事実が裏付ける範囲で、根拠の明確さ、具体性、深刻度をそのまま保ってください。実際のブロッカーやコストを和らげて伝えるのは不親切ですし、エンジニアには見抜かれます。省くべきなのは、暗黙の非難です。「デプロイパイプラインはロックファイルではなく、キャレット範囲からビルドしています」と「設定した人が間違えました」は、同じ事実を伝えていますが、次の行動につながるのは前者だけです。「あなた」は、次にすべきことを説明するときにだけ使います。また、アップグレードの範囲内にとどめてください。使用されていない依存関係はアップグレードに関する指摘ではありませんし、一般的なコードレビューに話が逸れる計画では、作業を妨げない事柄に読者の注意を使わせてしまいます。

確認できなかったことを明記します。 モノレポでは、リポジトリ外のベースファイルを継承する tsconfig.json、Reactをホイストするワークスペースのルート、別のディレクトリにあるCI設定など、見えないものがあります。必要な事実を確認できなかった場合は、人への質問のセクションに具体的に記載してください。「tsconfigがこのリポジトリ外のファイルを継承しているため、moduleResolution を確認できませんでした」は役立ちます。何も言わずに省略するのは避けてください。

ロードマップを約束しないでください。 非推奨のAPIが復活するのか、削除されるのかを尋ねられた場合は、現在ドキュメントに記載されている状態を説明するだけにとどめてください。将来のリリースについて推測してはいけません。

参照ファイル

ファイル	読むタイミング
references/detect.md	常に、ステップ 1 で
references/version-lookup.md	常に、ステップ 2 とステップ 4 で
references/boundaries.md	常に、ステップ 3 で。インデックス：対象範囲と、読むべき境界ファイル
references/boundary.v4.md	ステップ 3 で、対象範囲が v4 にまたがる場合、または v4 内にある場合
references/boundary.v5.md	ステップ 3 で、対象範囲が v5 にまたがる場合、または v5 内にある場合
references/boundary.v6.md	ステップ 3 で、対象範囲が v6 にまたがる場合、または v6 内にある場合
references/deprecations.md	ステップ 3 で、常に。短く、境界には紐づいていません
references/package-coupling.md	常に、ステップ 6 で
references/plugins.md	ステップ 6b で、プロジェクトにプラグインがある場合
references/report-template.md	ステップ 7 で