nextjs

此技能是 Next.js 参考资料集的路由外壳，而非完整的框架手册。

不可妥协的规则：

1. 首先阅读 references/stack.md。
2. 阅读仓库中的 AGENTS.md、CLAUDE.md 和最近的模块映射（如存在）。它们定义了实际的路由系列、本地化、设计/主题、身份验证、传输和测试约定。
3. 在应用具体版本的指导之前，先阅读应用的 package.json、解析后的锁文件，以及该包 node_modules/next/dist/docs/ 下与已安装版本匹配的 Next.js 文档。
4. 除非用户明确要求升级，否则遵循已安装的版本。不要在无关工作中升级、降级或切换发布渠道。
5. 然后仅加载实际任务所需的参考资料。
6. 翻译面向用户的文本，并确保所有后端流量都通过项目共享的 API 传输层。
7. 将较长的 Next.js 指导内容放在 references/ 中，不要内联在此处。

nextjs

输入

• $request：Next.js 页面、组件、路由、缓存或测试任务

目标

通过项目的 App Router 约定处理 Next.js 工作，使实现遵循既定的数据访问、元数据、本地化和渲染边界模式。

步骤 0：阅读技术栈约定

始终从以下文件开始：

• references/stack.md

该文件明确规定了运行时、配置和项目级 Next.js 模式。

对于新应用、版本建议或框架升级，还需阅读：

• references/upgrading.md

成功标准：编辑前明确项目的 Next.js 架构假设。

步骤 1：仅加载相关参考资料

使用路由表选择与任务匹配的参考文件。不要批量加载整个参考资料树。

任务	阅读
新应用、版本选择、从 Next.js 15 升级到 16	references/upgrading.md
文件夹布局、文件约定、项目结构	references/folder-structure.md
路由组、动态路由、并行/拦截路由	references/routing.md
创建或编辑页面或布局	references/page-checklist.md
组件结构、客户端/服务端边界	references/component-anatomy.md
数据获取、API 客户端、fetch 封装	references/api-client-pattern.md
轮询、分页、自动保存、过时的异步响应	references/client-async-state.md
服务端操作、变更、重新验证	references/server-actions.md
缓存、ISR、按需重新验证	references/caching-strategy.md
翻译、语言环境路由、消息文件	references/i18n-conventions.md
错误边界、error.tsx、not-found.tsx	references/error-handling.md
结构化日志、日志级别	references/logging.md
分析、事件跟踪、同意机制	references/tracking.md
身份验证、中间件、会话	references/auth.md
安全标头、CSP、CSRF、速率限制	references/security.md
SEO、元数据、Open Graph、站点地图	references/seo.md
适用于 Agent 的公开页面、信任锚点、404、llms.txt	references/agent-readiness.md
无障碍、ARIA、键盘导航	references/accessibility.md
单元测试、组件测试	references/testing-unit.md
端到端测试、Playwright	references/testing-e2e.md
机器可读输出、JSON-LD、结构化数据	references/machine-readable.md

多个任务？阅读多个文件。参考资料均可独立使用。

成功标准：当前上下文仅包含与任务相关的 Next.js 约定。

第 2 步：使用 Next.js 核心防护措施进行实现

请始终遵守以下规则：

• 对绑定请求的异步 API 使用 await
• 数据访问使用项目的 API 客户端，不要随意调用后端接口或 ORM
• RSC/服务端调用使用项目的服务端领域模块；经批准的交互式客户端使用其 浏览器端领域模块；两者最终都通过共享传输层调用
• 可见字符串必须通过本地化层处理
• 页面和布局优先使用服务端模式，只有叶子组件确实需要客户端模式时才使用
• 元数据和 SEO 要求必须纳入页面工作
• 身份验证和授权必须来自经过验证的后端会话，不得依赖由浏览器控制的 角色或工作区标头

成功标准：此项变更应符合项目的 App Router 架构，而不是通用框架默认做法。

第 3 步：验证受影响的范围

在足以证明行为正确的层级上运行仓库自带的脚本：

• lint、next typegen、类型检查，以及针对性的单元测试/组件测试
• 构建后的生产版 Next.js 服务端，用于检查 HTTP 状态码、标头、原始 HTML、内容协商、重定向和浏览器行为
• 当涉及 Laravel 会话、CSRF、队列、计费、下载、webhook 或其他后端边界时，运行标准的集成 Compose 技术栈

直接调用处理器无法证明生产环境中的 HTTP 行为。使用模拟 Laravel 的前端运行不属于完整的全栈测试。

成功标准：变更后的 Next.js 范围仍能正常运行。

防护措施

• 不要在 SKILL.md 中内联整本 Next.js 手册。
• 不要跳过 references/stack.md。
• 需要 i18n 时，不要硬编码面向用户的字符串。
• 不要绕过项目的 API 客户端和缓存约定。
• 不要在无关工作中替换或迁移项目的身份验证/会话权威来源。
• 不要违反项目锁定的设计约定，添加或移除主题支持。
• 除非任务包含升级，否则不要在较旧项目中使用仅适用于 Next.js 16 的 API。
• 不要降级已声明或解析为 Next.js 16.3.x 的项目。
• 除非用户明确选择该发布渠道，否则不要推荐 next@canary 或其他预发布版本。
• 不要添加 disable-model-invocation；这是一个常规领域技能。

对于公共页面任务，还要加载 agent-readiness.md、page-checklist.md、seo.md、 machine-readable.md 和 testing-e2e.md。适用的原始 HTML、规范标识、 结构化数据、信任页面、HTML/Markdown 404 页面以及实时 HTTP 检查全部通过后，才能将任务视为完成。请将外部搜索引擎和品牌可发现性工作与代码完成情况分开报告。

何时加载参考资料

• references/stack.md 始终加载。

• references/upgrading.md 新应用、版本选择和框架升级。

• 然后仅加载 references/ 下与任务相关的文件

输出约定

报告：

1. 声明的和解析出的 Next.js 版本，以及查阅了哪些已安装文档
2. 加载了哪些 Next.js 参考资料
3. 遵循的仓库架构或项目配置
4. 所做的变更
5. 在每个适用测试层级运行的验证
6. 剩余的部署、实时端点、集成或外部可发现性工作