solid-nextjs

对 Next.js 16 项目强制执行 SOLID 和 DRY 架构：文件少于 100 行（页面少于 50 行、服务器组件少于 80 行、客户端组件少于 60 行、服务器操作少于 30 行），类型隔离在 `interfaces/` 目录中（绝不放在组件或页面中），导出项必须包含 JSDoc，并采用 module/`modules/cores/` 目录结构。编写任何代码之前，必须通过 Context7/Exa（使用当前年份）研究最新的 Next.js/React/Prisma 文档，并在创建新工具函数之前先搜索现有工具函数。

为 SOLID 的每个字母提供专属参考指南（SRP 文件拆分、OCP 组合/插件模式、LSP 契约合规、ISP 基于角色的接口、DIP 构造函数注入/工厂），另有 23 个可直接复制的模板，涵盖组件、钩子、服务、存储、服务器操作、API 路由、验证器、Prisma 单例、i18n 和查询。这是一项横切代码质量技能，而非功能技能——框架 API 本身请参阅 nextjs-16 及其同系列技能。

SOLID Next.js - 模块化架构

当前日期（重要）

今天是 2026 年 1 月——搜索时始终使用当前年份。 搜索时使用「2025」或「2026」，绝不使用过去的年份。

强制要求：编码前先研究

重要：先查看今天的日期，然后在编写任何代码之前搜索文档和网页。

1. 使用 Context7 查询 Next.js/React 官方文档
2. 使用 Exa 网页搜索，并使用当前年份查找最新趋势
3. 查看当年的 Vercel Blog，了解新功能
4. 确认软件包版本与 Next.js 16 的兼容性

搜索查询（将 YYYY 替换为当前年份）：

• Next.js [feature] YYYY best practices
• React 19 [component] YYYY
• TypeScript [pattern] YYYY
• Prisma 7 [feature] YYYY

---

代码库分析（强制要求）

在进行任何实现之前：

1. 探索项目结构，了解架构
2. 阅读现有的相关文件，遵循既有模式
3. 确定使用的命名规范、编码风格和模式
4. 了解数据流和依赖关系

DRY - 复用或创建共享代码（强制要求）

编写任何新代码之前：

1. 在代码库中使用 grep 搜索类似的函数名称、模式或逻辑
2. 检查共享位置：modules/cores/lib/、modules/cores/components/、modules/cores/hooks/
3. 如果存在类似代码 → 扩展或复用，而不是重复创建
4. 如果代码将用于 2 个或更多功能 → 直接在 modules/cores/ 中创建
5. 将重复出现 3 次或更多的逻辑提取为共享辅助函数
6. 创建新文件后运行 npx jscpd ./src --threshold 3

---

Agent 工作流（强制要求）

在进行任何实现之前，并行启动 3 个 Agent，每个调用一次 Agent，并提供 name：

1. fuse-ai-pilot:explore-codebase - 分析项目结构和现有模式
2. fuse-ai-pilot:research-expert - 核实技术栈中所有技术的最新文档
3. mcp__context7__query-docs - 检查集成兼容性

实现完成后，运行 fuse-ai-pilot:sniper 进行验证。

---

绝对规则（强制要求）

1. 文件少于 100 行

• 90 行时拆分——绝不超过 100 行
• 页面组件少于 50 行（使用组合）
• 服务器组件少于 80 行
• 客户端组件少于 60 行
• 每个服务器操作少于 30 行

2. 模块化架构

完整结构（含功能模块和 cores 目录）请参阅 references/architecture-patterns.md。

3. JSDoc 为强制要求

/**
 * Fetch user by ID from database.
 *
 * @param id - User unique identifier
 * @returns User object or null if not found
 * @throws DatabaseError on connection failure
 */
export async function getUserById(id: string): Promise<User | null>

4. 接口分离

modules/auth/src/
├── interfaces/          # Types ONLY
│   ├── user.interface.ts
│   └── session.interface.ts
├── services/            # NO types here
└── components/          # NO types here

---

SOLID 原则（详细指南）

每项 SOLID 原则都有专门的参考指南：

1. references/single-responsibility.md - 一个类/函数 = 一个变更理由

   • 在 90 行处拆分文件（页面 < 50 行、组件 < 60 行、服务 < 80 行）
   • 组件组合模式
   • Next.js 页面和服务器操作示例

2. references/open-closed.md - 通过组合扩展，而不是修改

   • 插件架构模式
   • 多种实现的提供者模式
   • 适配器和策略模式
   • 在不更改现有代码的情况下添加功能

3. references/liskov-substitution.md - 契约合规性和行为子类型

   • 子类型必须可替代基类型
   • 异常和返回类型契约
   • 测试 LSP 合规性

4. references/interface-segregation.md - 多个精简接口胜过一个臃肿接口

   • 基于角色的接口
   • 避免臃肿的契约
   • 面向客户端的接口

5. references/dependency-inversion.md - 依赖抽象，而非实现

   • 构造函数注入模式
   • 用于创建对象的工厂模式
   • IoC 容器
   • 便于在测试中使用模拟对象

概览和速查指南请参阅 references/solid-principles.md。

---

代码模板

references/templates/ 中提供可直接复制的代码：

模板	用途
server-component.md	带数据获取的服务器组件
client-component.md	带钩子的客户端组件
service.md	使用依赖注入的服务
hook.md	带状态的 React 钩子
interface.md	TypeScript 接口
store.md	带持久化功能的 Zustand 存储
action.md	带验证的服务器操作
api-route.md	API 路由处理程序
validator.md	Zod 验证模式
factory.md	工厂模式
adapter.md	适配器模式
error.md	自定义错误类
test.md	测试模板
middleware.md	身份验证中间件
prisma.md	Prisma 单例
i18n.md	功能/全局翻译
query.md	数据库查询（Prisma 7）

---

回复指南

1. 先研究 - 必须：在编写任何代码之前，先搜索 Context7 + Exa
2. 展示完整代码 - 提供可运行的示例，而非代码片段
3. 解释决策 - 说明为何选择此模式而非其他方案
4. 包含测试 - 始终建议测试用例
5. 处理错误 - 切勿忽略错误，使用错误边界
6. 为所有内容添加类型 - 使用完整的 TypeScript，不使用 any
7. 记录代码 - 为复杂函数编写 JSDoc

---

禁止事项

• ❌ 未先研究文档就编写代码（务必先研究）
• ❌ 未查阅当年最新文档就使用过时 API
• ❌ 文件 > 100 行
• ❌ 在组件文件中定义接口
• ❌ 在 app/ 页面中编写业务逻辑
• ❌ 在组件中直接调用数据库
• ❌ 一个模块导入另一个模块（核心模块除外）
• ❌ 默认使用 'use client'
• ❌ 使用 useEffect 获取数据
• ❌ 导出内容缺少 JSDoc
• ❌ any 类型
• ❌ 聚合导出
• ❌ 未先使用 Grep 搜索，就重复编写已有的工具函数/辅助函数
• ❌ 复制粘贴逻辑代码块，而不是提取共享函数