该技能是一个 Next.js 架构约束工具,绑定在 hypercore 仓库的 hyper-architecture-nextjs 目录下,用于对已有 Next.js 项目进行架构审查、实施指导或代码评审。
用途方面,技能的核心目标是在 Next.js 项目中保证架构安全,使其符合官方文档与明确标注的仓库本地约定。它覆盖 App Router 工作、App Router 迁移、Server/Client 边界、缓存与新鲜度、Server Actions、Route Handlers、Proxy、环境与平台安全、服务/DAL 边界、客户端 Hook 编排、Drizzle/数据库放置以及嵌套共享文件夹组织。
主要能力方面,技能会先确认仓库是 Next.js 项目并识别 App Router、Pages Router 或混合模式,然后按触及面只加载对应规则文件,包括 routes、project-structure、execution-model、data-fetching、server-actions、route-handlers、services、hooks、db、platform、validation 等主题。检查围绕六类关卡展开:路由与文件约定、Server/Client 边界、数据获取与缓存新鲜度、Server Actions、Route Handlers 与 Proxy、平台与环境。发现结果以 BLOCKED 或 WARNING 标记,并对触及文件中的安全、密钥、鉴权和边界问题立即阻断。技能还会引用带日期的官方文档快照来判断版本敏感行为。
使用方式方面,用户提出审查、修改或扩展 Next.js 项目的请求时触发,例如审计 App Router 功能的 Server/Client 边界与缓存正确性、将表单改用 Server Actions、为 Webhook 添加 Route Handler、在 Next.js 16.4 的 cacheComponents 基础上检查数据获取规则、按嵌套共享目录整理 src/lib/auth/session.ts 与 src/services/billing/mutations.ts、添加 Drizzle schema 与迁移且不让数据库访问泄漏到客户端 Hook、将表单拆分为客户端 Hook、Server Actions 和服务端专用服务/DAL。技能每次请求执行一次约束检查,包含关卡判断、编辑与验证;只有用户再次请求或报告失败时才进行第二轮,且只重跑与触及面相关的检查。验证可运行 bash skills/hyper-architecture-nextjs/scripts/validate-hyper-architecture-nextjs-skill.sh,要求 bash 3.2+ 与 jq 1.6+,输出 JSON 摘要,失败时返回非零退出码。
适用场景方面,适用于已有 Next.js 项目的架构实施与评审,尤其是 App Router 相关工作与迁移。明确不适用于通用 React 架构、Remix 或 TanStack Start 项目、仅文档摘要,以及不触及架构边界的纯文案修改;对于仅使用 Pages Router 且未要求迁移的项目,只应用共享的 Next.js 平台、环境与服务端/客户端安全检查,不强制 App Router 专属文件约定。
限制方面,技能不运行优化循环,单次请求仅执行一遍;不会默认对未触及的遗留偏差判定失败,但触及文件中的安全、密钥、鉴权和边界问题会立即阻断;恢复触及文件合规如果需要大范围迁移,则会拒绝并说明原因。默认所有面向用户的交付物、报告、计划和验证说明使用韩语,除非用户明确要求其他语言。技能的官方行为依据带日期的文档快照,当出现 API 漂移时会注明日期与来源。该技能的完整规则还涉及文件约定、组件边界、缓存组件、Server Action 校验、Route Handler 缓存意图、Proxy matcher、环境变量加载等内容,具体细节需参照其规则文件。