sanity-best-practices

sanity-best-practices skill の概要

sanity-best-practices skill で何ができるか

sanity-best-practices skill は、Sanity で実装を始める前に、どのモデリング、クエリ、Studio、統合パターンを選ぶべきかを判断するための、Sanity 専用の実践ガイドです。雑な思いつきから本番投入可能な schema や frontend コードまで、より短い距離で到達したいとき、不要なリファクタを減らしたいとき、そして Sanity 実装をすっきり仕上げたいときに特に役立ちます。

どんな人に向いているか

schemas、GROQ、TypeGen、Visual Editing、Portable Text、localization、migrations、Functions、Blueprints、あるいは Next.js、Nuxt、Astro、Remix、SvelteKit、Angular、Hydrogen、App SDK のような framework 統合について助けが必要な Sanity コードベースで作業しているなら、この sanity-best-practices skill を使ってください。frontend エンジニア、content platform を作る人、既存の Sanity 構成をレビューするチームに特に向いています。

インストールする価値がある理由

最大の価値は、判断の質が上がることです。defineQuery をいつ使うべきか、型安全性を意識した query の組み立て方、あるいはどの機能を Studio 側に置き、どれを frontend に持たせるべきかといった Sanity 固有の制約を見落としがちな、漠然としたプロンプトを避けられます。sanity-best-practices guide として、前提を置きすぎずに実装を進めたいなら、単なる「Sanity について教えて」よりもこの skill のほうが実用的です。

sanity-best-practices skill の使い方

まずインストールして、正しいファイルを開く

skills ツールチェーンで sanity-best-practices install の流れを実行したら、最初に SKILL.md を読んで範囲を確認します。その後は、課題に合う topic file だけを読むのが基本です。この repository は 1 本の長いマニュアルではなく、用途別の reference page として整理されています。多くの作業では、最初に読むべきなのは references/get-started.md、references/schema.md、references/groq.md、references/typegen.md、そして該当する framework ファイルです。

漠然とした依頼を、使える入力に変える

この skill は、技術名だけでなく、具体的なゴールを渡したときに最もよく機能します。「Sanity の設定を改善して」ではなく、「この Next.js + Sanity の page builder schema をレビューして、TypeGen、GROQ、Visual Editing の観点から best-practice の改善案を出して」と伝えてください。sanity-best-practices usage を依頼するときは、framework、Sanity のバージョン、対象ファイル、そして壊れた型、遅い query、preview の不一致、content modeling の違和感といった失敗モードまで含めると精度が上がります。

ふだんの癖ではなく、作業単位で repository を読む

作業に合う reference file を使い分けてください。

• content model、defineType、defineField は references/schema.md
• query の構造と query safety は references/groq.md
• preview と Presentation の設定は references/visual-editing.md
• typed schema と typed query は references/typegen.md
• 統合の詳細は references/nextjs.md、references/astro.md、references/nuxt.md、または他の framework ファイル
• event-driven automation と infrastructure は references/functions.md と references/blueprints.md

制約が見える prompt 形式にする

強い prompt には通常、何を作っているか、どのファイルをレビューしたいか、どの framework を使っているか、そして何を変えてはいけないかが入っています。例: 「この post schema を localization と Portable Text の best practice の観点で監査してください。公開 API は安定させ、可能なら既存の field 名は維持し、破壊的変更がある場合は必ず説明してください。」この程度まで具体化すると、skill は generic advice ではなく、実際に使える sanity-best-practices usage の出力を返しやすくなります。

sanity-best-practices skill FAQ

この skill は新しい Sanity プロジェクト専用ですか？

いいえ。sanity-best-practices skill は、既存プロジェクトの修正にも同じくらい有効です。特に schema drift を減らしたい、query の保守性を上げたい、あるいは frontend を Studio の挙動に合わせたい場合に役立ちます。

通常の prompt と何が違いますか？

通常の prompt は、たいてい単独の回答を求めます。この skill は Sanity 中心の workflow と reference path を与えるので、結果が generic な JavaScript アドバイスではなく、schema、GROQ、preview、TypeGen、framework integration の best practices に沿いやすくなります。

初心者でも使えますか？

はい、すでに Sanity で作業していることが分かっているなら使えます。これ自体が初心者向けの導入講座ではありませんが、どの Sanity 機能が適切かを推測させられるのではなく、正しい topic file に案内してくれるので混乱はかなり減ります。

使わないほうがいいのはどんなときですか？

問題が Sanity 固有ではない場合や、modeling、query、integration の判断が不要な小さな単発修正だけなら外してください。また、Sanity の content flow と無関係な pure frontend debugging には向いていません。

sanity-best-practices skill の改善方法

本当に必要な判断をそのまま伝える

最良の結果は、実際のトレードオフを明示したときに出ます。「この field は reference にすべきか、それとも inline object にすべきか？」や「この query は frontend に置くべきか、それとも schema 側で正規化すべきか？」のように聞いてください。単なる整理ではなく、アーキテクチャを最適化してほしいと伝えたほうが、この skill は syntax ではなく設計に集中できます。

現在のコードの形を含める

レビューしたい schema、query、integration snippet を貼り、content がシステム内でどう流れるかを見られるだけの周辺情報も一緒に渡してください。sanity-best-practices for Frontend Development では、framework、rendering mode、preview、SSR、static build、live updates のどれが必要かまで含めると精度が上がります。

最初の答えだけで終わらせず、次の改善を頼む

最初の提案を受けたら、次は 1 つの成果に絞って詰めてください。たとえば type safety、editor experience、query performance、content authoring の分かりやすさです。よくある失敗は、過度に正規化された schema、条件が足りない GROQ filter、そして Studio の前提と合っていない frontend code です。最短で改善するには、制約を追加して、より要素の少ない改訂版を求めるのが効果的です。

repository の証拠を使って整合性を保つ

迷ったら、references/localization.md、references/migration.md、references/page-builder.md など、該当する reference file path を根拠に follow-up を組み立ててください。そうすると sanity-best-practices skill を repository 本来のパターンに沿わせやすくなり、最終成果物も実装しやすくなります。