用途
该技能用于执行 Next.js 项目健康审计,对项目进行模块化、证据驱动的技术评估,输出可分享的 Markdown 报告。审计覆盖技术栈、架构、状态管理、测试、代码质量、性能、文档与运维、CI/CD、AI Harness 与采用情况等 9 个维度,并计算分区评分与加权总分。主要面向 Next.js 项目的技术健康检查与改进建议。
主要能力
- 环境准备与版本对齐:强制使用 nvm 配置项目所需的 Node.js 版本;从锁文件检测包管理器,优先 pnpm(corepack enable 与 pnpm install --frozen-lockfile),其他包管理器按仓库原有方式冻结安装并记录“未使用 pnpm”发现;在 workspace monorepo 中仅在根目录执行一次冻结安装。
- 验证安装:检查已安装的 next/react 版本,执行非阻塞的 next build 与类型检查,并生成测试覆盖率。
- 仓库清单:识别 Next.js 应用、路由模型(App Router / Pages Router / 混合)、src/ 布局、路由组、并行与拦截路由、proxy.ts 或已弃用的 middleware.ts、instrumentation.ts、输出模式(standalone/export)、Turbopack 与 webpack、monorepo 设置及部署目标线索。
- 配置分析:审查 next.config.*(images、experimental 标志、typescript.ignoreBuildErrors / eslint 红标、headers、output)、tsconfig.json、ESLint(eslint-config-next / @next/eslint-plugin-next)、Prettier 与环境变量约定。
- CI/CD 分析:读取所有 CI 工作流,检查冻结安装、lint、类型检查、测试、next build、.next/cache 缓存与预览部署。
- 测试基础设施:查找并分类测试文件(Vitest/Jest + React Testing Library、Playwright/Cypress E2E),以及 Server Actions、Route Handlers 和异步 Server Components 的测试方式,并结合覆盖率结果。
- 代码质量与 Linter:分析 ESLint、TypeScript 严格性与格式化,收集 Next.js 使用信号('use client' 范围、next/image、next/font、next/script、动态导入、包分析)。
- 数据与状态管理:分析服务端/客户端状态边界、RSC 数据获取、Server Actions 与重验证、缓存模型(use cache / Cache Components 或 fetch-cache)及客户端状态库。
- 文档与运维:审查 README、环境设置、Storybook、架构文档(含缓存与渲染策略)以及面向 agent 的文档。
- AI Harness 与采用分析:分析 CLAUDE.md / AGENTS.md(含受管的 Next.js agent 块)、.claude/rules/、settings.json 权限与 hooks、.claude/agents/、commands/skills(含官方 Next.js skills)及 pre-push git hook,按 10 维度 100 分评分标准判断质量而非仅看是否存在;是否存在基于磁盘判断,是否已提交在维度 10 统一评分。
- 依赖与安全分析:从锁文件解析已安装的 next、react、react-dom 版本,对照实时公告源(OSV、GitHub Advisory Database)检查整个依赖树,使用 endoflife.date 检查已安装 Next.js 大版本的支持状态,运行包管理器 audit,并记录包管理器卫生情况;不从记忆中断言漏洞或补丁版本。
- 报告生成与导出:整合全部分析结果,生成包含执行摘要与总分、9 个分区评分与测试覆盖率行的总览记分卡、9 个详细分区、附加指标、风险与机会(5-8 条)、建议(6-10 条优先级行动)、证据索引附录与评分方法附录的报告;CLI 随后运行 report-format-enforcer.md 校验结构;最终以 Markdown 保存到 ./reports/<YYYY-MM-DD>-<project>-nextjs-health-audit.md。
使用方式
按顺序执行 14 条规则:tool-installer、version-alignment(强制,nvm 失败则停止)、version-validator、test-coverage、repository-inventory、config-analysis、cicd-analysis、testing-analysis、code-quality、state-management-analysis、documentation-analysis、harness-analysis、dependency-security-analysis(实时公告查询,喂入技术栈)、report-generator。执行采用波次并行策略:Wave 0 顺序执行步骤 0 环境准备;Wave 1 并行步骤 1+2(仓库清单 + 配置分析);Wave 2 并行步骤 3+4+5+8(CI/CD + 测试 + 代码质量 + AI Harness);Wave 3 并行步骤 6+7+9(状态管理 + 文档 + 依赖与安全);Wave 4 顺序执行步骤 10+11(报告生成 + 导出)。每个步骤必须单独完整执行,执行前先完整阅读对应 references/*.md 并遵循其指示;每步完成后输出“STEP N COMPLETED: [简要结果摘要]”。步骤失败时记录并尝试恢复,仅在无法恢复时跳过并明确记录。可使用 Agent 工具为每个并行步骤启动子代理,子代理需完整阅读并执行引用文件、返回完整证据。
适用场景
- 对 Next.js 项目进行技术健康检查与成熟度评估。
- 在升级 Next.js 或 React 前了解技术栈、依赖安全与版本支持状态。
- 评估测试覆盖、CI/CD、代码质量、状态管理与文档状况。
- 审查 AI 编程工具链(CLAUDE.md / AGENTS.md、hooks、skills 等)的质量。
- 生成结构化的审计报告用于团队分享或改进规划。
限制
- 仅关注技术层面,不包含运营/治理建议;明确不推荐 CODEOWNERS 或 SECURITY.md 文件,不推荐运行手册、部署流程、监控等运营文档。
- 所有发现必须基于仓库证据;证据缺失时标记为 Unknown 并说明需要什么证据。
- 强制使用 nvm 管理 Node.js 版本,nvm 配置失败则停止执行。
- 必须优先使用 pnpm,不迁移包管理器、不删除/转换/重新生成锁文件。
- 不得从记忆中断言漏洞或补丁版本,安装版本来自锁文件,公告来自实时源。
- 不得跳过、合并或缩写任何步骤;不得用摘要代替执行引用文件。
- 性能部分仅收集 Next.js 使用信号,未提供具体性能测量方法。
- 深层安全分析需运行独立的 /somnio:nextjs-security-audit。
- 未提供具体安装命令、收费模式或平台依赖信息。