specsfy-specialist-nextjs

Name: specsfy-specialist-nextjs
Author: promovaweb

github.com/promovaweb开发87191 次安装1 周前更新

关于 specsfy-specialist-nextjs

面向 Next.js 项目的开发技能，适用于处理路由、渲染边界、缓存、安全与部署问题。它强调先确认版本和运行环境，再依据可验证的构建与运行结果调整实现。

复制下面的命令，在终端中运行。

$npx skills add https://github.com/promovaweb/specsfy --skill specsfy-specialist-nextjs

安装后在 Claude Code 中输入/specsfy-specialist-nextjs确认已加载。

附带文件agents/openai.yamlreferences/standards.md

当项目依赖 next/next.config，且任务涉及路由、布局、Server/Client Component、Server Action、route handler、缓存、中间件、metadata 或部署时使用。
诊断数据瀑布、hydration 不匹配，或缓存提供过时数据/跨用户数据时也使用。
对于不依赖框架的 hooks、状态或组件组合，不要使用此项；此时使用 $specsfy-specialist-react，只有涉及 server/client 边界时再回到这里。
当路由暴露 mutation、上传或敏感数据时，与 $specsfy-specialist-application-security 配合使用；当症状是 Web Vitals 或 TTFB 超出 SLO 时，与 $specsfy-specialist-performance-engineering 配合使用。

确认 Next.js 版本、路由器（App 或 Pages）、运行时（Node 或 Edge）、部署目标和启用的实验性标志——缓存和 Server Components 的语义会随版本变化。
梳理已更改的路由：layout、loading、error、not-found，以及数据（server）与交互（client）之间的边界位置。
默认使用 Server 组件；只有确实需要 hook、事件或浏览器 API 时，才在相应的叶子组件上标记 "use client"——切勿为了方便而标记整个 layout 或页面。
明确为每个数据源定义缓存、重新验证和标签；将默认行为视为已安装版本的契约，而不是想当然。
在每个 Server Action 和 route handler 中验证输入并检查授权，视其为公开的 HTTP 端点——因为它确实如此。
规划 metadata、流式传输（loading.js/Suspense）、图片/字体，以及错误恢复路径（error.js、not-found.js）。
执行 lint、typecheck、测试、生产构建，并在目标 adapter/host 的实际运行时中检查结果，而不只是运行 next dev。

不要为了“解决” hook 错误而将整个组件树移到 "use client"；应将交互隔离在正确的叶子组件中。
切勿在 Client Component 中导入密钥、数据库客户端或仅限 server 使用的模块——打包器可能会将其包含在发送到浏览器的 JS 中。
尽可能在靠近数据使用方的位置获取数据；测量并消除可避免的顺序瀑布（彼此不必要地依赖的请求）。
将缓存视为每条路由的明确契约：声明每个数据源是静态、按时间重新验证、按标签重新验证，还是动态——切勿未经检查已安装的版本就沿用默认值。
任何影响已缓存数据的 mutation 发生后，立即重新验证（revalidatePath/revalidateTag）；否则 UI 会显示过时状态。
以保护公开端点的同等严谨程度保护每个 Server Action：进行身份验证、按对象授权并验证 payload——客户端可以绕过预期的 UI 流程，直接调用它。
仅将 middleware 用于简短且与路由运行时兼容的逻辑（Edge 的 API 受限）；较重的逻辑应放在 route handler 或应用层。
记录任何与特定 host/adapter 行为（headers、流式传输、时间限制）的耦合，而不是让其隐而不宣。

仅仅因为某个子组件需要交互性，就在 layout.tsx 或 page.tsx 顶部添加 "use client"——这会将整个子树移到客户端，并失去 Server Components 的优势。
在多个嵌套组件中重复获取相同数据，却不使用缓存或去重，导致网络瀑布图中出现明显的串行请求级联。
通过 Server Action 修改数据，却不重新验证对应的 path/tag——UI 看起来像是“坏了”，因为它会一直显示旧缓存，直到下一次完整刷新。
在 Client Component 中依赖没有公开前缀（NEXT_PUBLIC_）的环境变量——该变量不会出现在浏览器 bundle 中。
把 Server Action 当作“只能通过 UI 访问”的功能而跳过授权——它和其他 HTTP 路由一样，可以被直接调用。

完整运行 next build（以及项目的 lint/typecheck），并阅读其输出的路由报告（静态 ○、动态 λ、ISR）；检查结果是否符合工作流第 4 步中声明的意图。
在每个已修改的路由中测试 loading、error、not-found、重定向和授权，包括不经客户端导航直接通过 URL 访问的情况。
验证缓存命中/未命中和失效：修改数据，检查路由是否重新验证，并确认不同用户/会话之间不会因缓存键作用域不当而泄露数据。
当路由对性能敏感时，在更改前后测量客户端 bundle、图像、字体和 Web Vitals（LCP、INP、CLS）。
没有证据时，不得宣称路由“采用 server-first 分区”或“缓存正确”；没有证据的绝对化表述是禁止的。