sanity-best-practices

sanity-best-practices 技能概覽

sanity-best-practices 技能能做什麼

sanity-best-practices 是一套專為 Sanity 設計的指引包，讓你在動手之前，就先把建模、查詢、Studio 與整合模式選對。當你想把 Sanity 實作做得更乾淨、減少可避免的重構，並更快從粗略想法走到可上線的 schema 或前端程式碼時，這個技能特別有用。

適合誰使用

如果你正在處理 Sanity 程式碼庫，並且需要 schemas、GROQ、TypeGen、Visual Editing、Portable Text、localization、migrations、Functions、Blueprints，或像 Next.js、Nuxt、Astro、Remix、SvelteKit、Angular、Hydrogen、App SDK 這類框架整合的協助，就應該使用這個 sanity-best-practices skill。它很適合前端工程師、內容平台建置者，以及正在檢視既有 Sanity 設定的團隊。

為什麼值得安裝

它的核心價值在於決策品質：可以幫你避開那些不夠 Sanity 專精的通用提示，例如何時該用 defineQuery、如何把查詢結構做成型別安全，或某個功能應該放在 Studio 還是前端。如果你需要的是一份 sanity-best-practices guide，能幫你用更少假設把東西做對，那這個技能會比泛泛的「幫我處理 Sanity」提示更實用。

如何使用 sanity-best-practices 技能

先安裝，再打開正確的檔案

先在你的 skills toolchain 中走 sanity-best-practices install 流程，接著先讀 SKILL.md 以確認範圍。之後只讀符合你任務的主題檔案；這個倉庫是以聚焦的參考頁面來組織，不是一份長篇手冊。對多數任務來說，最先應該讀的是 references/get-started.md、references/schema.md、references/groq.md、references/typegen.md，以及相關的框架檔案。

把模糊任務轉成可用輸入

這個技能最吃得開的，是你提供明確目標，而不只是技術名稱。不要只說「幫我改善 Sanity 設定」，而是說：「請檢視這個 Next.js + Sanity page builder schema，並針對 TypeGen、GROQ 和 Visual Editing 提出最佳實務修改建議。」若是 sanity-best-practices usage 類型的需求，請附上框架、Sanity 版本、目前檔案，以及失敗模式：型別壞掉、查詢太慢、預覽不一致，或內容建模很彆扭。

依任務讀倉庫，不要靠習慣亂翻

請依照工作內容選對參考檔：

• references/schema.md：內容模型、defineType、defineField
• references/groq.md：查詢結構與查詢安全
• references/visual-editing.md：預覽與 Presentation 設定
• references/typegen.md：typed schemas 與 typed queries
• references/nextjs.md、references/astro.md、references/nuxt.md，或其他框架檔案：整合細節
• references/functions.md 與 references/blueprints.md：事件驅動自動化與基礎架構

用能暴露限制條件的提示格式

好的提示通常會包含：你在做什麼、要檢視哪個檔案、使用哪個框架，以及哪些東西不能改。範例：「請審查這個 post schema 在 localization 與 Portable Text 最佳實務上的問題。請維持公開 API 穩定，盡量保留現有欄位名稱，並說明任何破壞性變更。」這種具體程度，能讓技能產出真正可執行的 sanity-best-practices usage 結果，而不是空泛建議。

sanity-best-practices 技能 FAQ

這個技能只適合新 Sanity 專案嗎？

不是。sanity-best-practices 對於修正既有專案同樣有用，特別是當你需要降低 schema drift、提升查詢可維護性，或讓前端行為和 Studio 對齊時。

這和一般提示有什麼不同？

一般提示通常是把問題獨立拿出來回答。這個技能會提供一條以 Sanity 為中心的工作流程與參考路徑，讓結果反映的是 schemas、GROQ、預覽、TypeGen 與框架整合的最佳實務，而不是泛用的 JavaScript 建議。

對新手友善嗎？

如果你已經知道自己是在 Sanity 環境中工作，那答案是友善的。它本身不是入門教學課，但它會直接把你帶到正確的主題檔，而不是讓你自己猜應該套用哪個 Sanity 功能。

什麼情況下不該用它？

如果你的問題不是 Sanity 特有，或你只是想做一個不涉及建模、查詢或整合判斷的小幅單次修改，就不必用。當你需要的是一段與 Sanity 內容流無關的純前端除錯時，它也不是合適選項。

如何改進 sanity-best-practices 技能

把真正需要做的取捨講清楚

最好的結果，來自你直接說出實際取捨：「這個欄位應該用 reference 還是 inline object？」或「這個查詢應該放在前端，還是先在 schema 中正規化？」這比泛泛地要求整理更有效，因為技能就能針對架構做優化，而不是只修語法。

提供程式碼目前的實際樣子

請貼出你要審查的 schema、query 或整合片段，並附上足夠的上下文，讓它看得出內容如何在系統中流動。若是 sanity-best-practices for Frontend Development，請一併提供框架、rendering mode，以及你需要的是 preview、SSR、static build 還是 live updates。

要求下一輪改進，不只要第一版答案

第一輪回覆後，請再要求它針對單一目標收斂：type safety、editor experience、query performance，或內容編輯清晰度。常見失誤包括 schema 過度正規化、GROQ filter 定義不夠明確，以及前端程式碼和 Studio 假設不一致。最快的改善方式，通常是加上限制條件，並要求提供一個移除較多複雜度的修正版。

用倉庫證據來對齊方向

拿不準時，請把後續問題錨定在相關參考檔路徑上，例如 references/localization.md、references/migration.md，或 references/page-builder.md。這能讓 sanity-best-practices skill 一直維持在倉庫預期的模式上，也讓最後產出的內容更容易落地實作。