sanity-best-practices

sanity-best-practices 技能概览

sanity-best-practices 技能能做什么

sanity-best-practices 是一套面向 Sanity 的指导包，帮助你在开始构建之前先选对建模、查询、Studio 和集成模式。它最适合想要把 Sanity 实现做得更干净、减少不必要重构，并更快从粗略想法推进到可上线的 schema 或前端代码的场景。

适合谁使用

如果你正在维护一个 Sanity 代码库，并且需要在 schema、GROQ、TypeGen、Visual Editing、Portable Text、本地化、迁移、Functions、Blueprints，或者 Next.js、Nuxt、Astro、Remix、SvelteKit、Angular、Hydrogen、App SDK 这类框架集成上获得帮助，就应该使用这个 sanity-best-practices skill。它非常适合前端工程师、内容平台搭建者，以及正在复盘现有 Sanity 方案的团队。

为什么值得安装

它的核心价值在于提升决策质量：能帮你避开那些不懂 Sanity 约束的通用提问，比如什么时候该用 defineQuery，怎样组织查询才能保持类型安全，或者某个功能应该放在 Studio 里还是前端里。如果你需要一个 sanity-best-practices guide，帮助你在更少假设的前提下构建，这个 skill 会比笼统的“帮我处理 Sanity”提示更有用。

如何使用 sanity-best-practices 技能

先安装，再打开正确的文件

先在你的 skills 工具链里走 sanity-best-practices install 流程，然后从 SKILL.md 开始确认适用范围。接着只阅读与你任务匹配的主题文件；这个仓库按聚焦型参考页来组织，不是一本从头看到尾的长手册。对大多数任务来说，最值得先看的通常是 references/get-started.md、references/schema.md、references/groq.md、references/typegen.md，以及对应的框架文件。

把模糊任务变成可执行输入

这个 skill 最适合接收具体目标，而不是只说技术名词。不要只说“帮我改进 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：类型化 schema 和类型化查询
• references/nextjs.md、references/astro.md、references/nuxt.md，或其他框架文件：集成细节
• references/functions.md 和 references/blueprints.md：事件驱动自动化与基础设施

用能暴露约束的提示格式

高质量提示通常会包含：你在做什么、希望审查哪个文件、使用什么框架，以及哪些内容不能改。比如：“请审计这个 post schema 的本地化和 Portable Text 最佳实践。保持公共 API 稳定，尽量保留现有字段名，并说明任何破坏性变更。”这种具体程度能帮助 skill 输出可直接执行的 sanity-best-practices usage 结果，而不是泛泛建议。

sanity-best-practices 技能常见问题

这个技能只适合新 Sanity 项目吗？

不。sanity-best-practices 在修复现有项目时同样很有价值，尤其是当你需要减少 schema 漂移、提升查询可维护性，或者让前端行为与 Studio 保持一致时。

它和普通提示有什么不同？

普通提示通常只是在孤立地要一个答案。这个 skill 会给你一条以 Sanity 为中心的工作流和参考路径，因此产出的内容会更符合 schema、GROQ、预览、TypeGen 和框架集成的最佳实践，而不是停留在通用 JavaScript 建议层面。

它适合新手吗？

如果你已经知道自己是在 Sanity 里工作，那答案是肯定的。它本身不是入门课程，但它会把你导向正确的主题文件，减少你猜测该用哪个 Sanity 功能的混乱感。

什么情况下不该用它？

如果你的问题不是 Sanity 相关，或者你只需要一个不涉及建模、查询或集成决策的小修改，就可以跳过它。对于与 Sanity 内容流无关的纯前端调试，它也不是最合适的选择。

如何改进 sanity-best-practices 技能

把你真正需要做的决策说清楚

最好的结果来自于把真实取舍说出来：“这个字段应该用 reference 还是 inline object？”或者“这个查询应该放在前端，还是在 schema 里归一化？”这比要求全面清理更有效，因为这样 skill 才能按架构目标优化，而不只是修语法。

带上代码当前的真实形态

把你希望审查的 schema、query 或集成片段贴出来，同时提供足够的上下文，让人能看懂内容是怎么在系统里流动的。如果是 sanity-best-practices for Frontend Development，请说明框架、渲染模式，以及你需要的是 preview、SSR、静态构建还是实时更新。

要求下一轮迭代，而不只是第一版答案

拿到第一轮结果后，可以继续要求它针对一个目标收紧：类型安全、编辑体验、查询性能，或者内容作者的理解清晰度。常见问题包括 schema 过度归一化、GROQ filter 过于宽泛，以及前端代码和 Studio 假设不一致。最快的改进方式通常是增加约束，并要求给出一个更少组件、更少分叉的修订版。

用仓库证据保持一致性

拿不准时，就用相关参考文件路径来锚定后续问题，比如 references/localization.md、references/migration.md 或 references/page-builder.md。这样可以让 sanity-best-practices skill 始终贴合仓库预期模式，也让最终结果更容易落地实现。