SuperAPI AI 工具集

nextjs-best-practices

编程与开发

查看项目

更新于 11-09 21:09

技能介绍

用途

nextjs-best-practices 是一个面向 Next.js 代码库的微级别代码质量审计技能。它针对 App Router 架构、服务端与客户端组件边界、数据获取与缓存、Server Actions 与 Route Handlers、渲染性能、测试质量以及 TypeScript 标准等维度执行系统化分析,并生成结构化的 Markdown 审计报告。

主要能力

  • 版本感知分析:从锁文件中解析实际安装的 Next.js 版本,并依据该版本文档进行判断,不依赖对其它版本的记忆。文档来源优先级为 node_modules/next/dist/docs/、.next-docs/、https://nextjs.org/docs(含版本化前缀与 Markdown 变体)。
  • 多维度审计:覆盖 App Router 文件约定、布局、路由组、loading/error/not-found 边界、Metadata API、Server Component 默认与 'use client' 推至叶子组件、server-only/client-only 标记、可序列化 props、水合风险、并行获取与瀑布、Suspense 流式、缓存与重新验证、Server Actions 与 Route Handlers 的输入验证、授权、重验证与错误处理、next/image、next/font、next/script、动态导入、静态与动态渲染、测试框架覆盖、TypeScript 严格模式与类型化路由等。
  • 证据驱动报告:所有发现均基于实际代码检查,以 path:line 形式引用证据,明确区分违规、建议与合规代码;无法由代码证据证明的事项标记为“Unknown”并说明所需证据。
  • 编排与子代理调度:在 Claude Code 会话中,由编排器按三波次调度子代理:第一波为项目扫描与 TypeScript 扫描(cheap 层级),第二波为各维度分析器(mid 层级),第三波为报告撰写器(frontier 层级)。每个波次验证产物存在后推进,缺失则重试一次并记录跳过依赖项。
  • 报告生成:按模板生成最终 Markdown 报告,文件名固定为 <YYYY-MM-DD>-<project>-nextjs-best-practices.md,项目名从 git origin 远程 URL 推导为 kebab-case,无远程时使用主检出目录名,非 git 仓库时使用当前目录名。报告末尾必须包含报告元数据块,其中 Generated by 行固定为 Somnio CLI v3.3.2。
  • 可选 Drive 上传:仅在用户明确要求时(如 /nextjs-best-practices upload、口头请求或 somnio run nextjs-best-practices --upload),在最终报告写好后从主会话读取 references/drive-upload.md 并执行上传;子代理不具备 Google Drive MCP 工具。

使用方式

该技能可通过两种方式调用:在 Claude Code 会话中由编排器 agents/orchestrator.md 作为单一入口,或通过 somnio run 命令运行。通过 somnio run 时,CLI 会计算完整报告路径并在提示中传入,应原样使用该路径,不要重新计算。审计按步骤顺序执行:步骤 1 至 7 分别对应 App Router 架构、服务端与客户端组件、数据获取与缓存、Server Actions 与 Route Handlers、渲染性能、测试质量、TypeScript 标准分析,步骤 8 为报告生成。各步骤需阅读并遵循 references/ 目录下对应的指令文件。报告生成步骤需遵循 references/best-practices-format-enforcer.md 与 references/best-practices-generator.md,并使用 assets/report-template.md 模板。

适用场景

适用于需要对 Next.js 项目进行代码质量审查、识别版本相关的最佳实践违规、评估组件边界与数据获取模式、检查 Server Actions 安全性、审视渲染性能与测试覆盖、以及评估 TypeScript 严格性的开发团队或代码审查流程。也可作为 CI 或本地审计的补充工具。

限制

  • 安全相关的漏洞版本号判断不属于本技能范围,应使用 nextjs-security-audit 技能。
  • 该技能自身不提供对 Next.js 安全漏洞的断言,不引用记忆中的漏洞版本号。
  • 无法由代码证据证明的内容将标记为“Unknown”,不进行推测。
  • 报告元数据中的 Generated by 版本号固定为模板中的 Somnio CLI v3.3.2,不得修改或省略。
  • 可选 Drive 上传仅在用户明确请求时执行,否则不上传任何内容。
  • 该技能为审计报告生成工具,具体收费、价格、平台兼容性等商业信息暂未提供。
  • 关于具体支持的操作系统、依赖安装方式、是否需要网络访问等运行环境细节,资料中暂未提供。