代码质量审查 Code Audit

目标

全面提升代码质量、开发效率和可维护性，帮助团队快速理解和维护代码库。

审查维度

1. Next.js 和 Server Actions 最佳实践

检查是否充分利用 Next.js 15 和 Server Actions 特性：

•✅ Server Actions 替代传统 API 路由（仅限非流式场景）
•✅ 使用 'use server' 指令
•✅ 避免在 Server Actions 中使用客户端 API
•✅ 合理使用 revalidatePath 和 revalidateTag
•✅ Server Components vs Client Components 选择正确
•✅ 避免不必要的 'use client'
•✅ 利用流式渲染和 Suspense
•✅ 使用 Server Actions 进行表单提交
•❌ 避免：API 路由做简单 CRUD（应用 Server Actions）
•❌ 避免：在服务端组件中使用 useState、useEffect
•
⚠️ 保留 Route Handler 的场景：
- •流式响应（SSE/ReadableStream）如 AI 生成
- •大文件上传/下载
- •Webhooks 回调
- •需要自定义 Response Headers 的场景

2. 代码重复和复用性

识别需要抽离复用的代码：

•查找重复的业务逻辑（相似度 > 70%）
•检查是否有重复的数据验证逻辑（应使用 Zod schemas）
•识别重复的 UI 组件（应抽离到 components/）
•检查重复的数据库查询（应抽离到 lib/db）
•查找重复的错误处理模式
•检查是否有工具函数可以复用

3. 代码逻辑和结构清晰度

评估代码可读性和维护性：

•函数职责单一性（是否做太多事）
•变量命名是否清晰表意
•逻辑嵌套深度（超过 3 层需要重构）
•文件长度（超过 600 行需要拆分）
•函数长度（超过 150 行需要拆分）
•是否有魔法数字或硬编码值
•类型定义是否完整（公共 API 和核心业务逻辑应避免 any，临时转换和复杂第三方库返回值可酌情使用）
•导入语句是否有序分组

4. 文档和注释

检查复杂功能的文档完整性：

•复杂业务逻辑是否有 README 或注释
•关键算法是否有说明
•API 接口是否有 JSDoc
•复杂的状态管理是否有文档
•非显而易见的 hack 是否有解释
•项目结构是否有说明文档

5. 第三方库和技术栈

检查依赖是否最新和合理：

•查找过时的依赖包（检查 package.json）
•检查是否使用过时的 API（如 React 旧生命周期）
•评估库的选择是否合理（是否有更好的替代）

6. 性能和效率

识别低效的实现方法：

•不必要的重复渲染
•缺少 useMemo、useCallback 的计算密集操作
•数据库查询 N+1 问题
•未优化的图片加载
•大型列表未使用虚拟滚动
•同步操作阻塞主线程
•未使用的导入和死代码

7. 类型安全和错误处理

检查健壮性：

•TypeScript 类型覆盖率
•是否有足够的错误处理
•边界情况是否考虑
•用户输入是否验证
•API 调用是否有错误处理

8. 前端组件一致性

确保 UI 和交互模式统一：

•
UI 组件使用一致性：
- •按钮：是否统一使用 shadcn/ui <Button>
- •表单：是否统一使用 react-hook-form + Zod
- •对话框：是否统一使用 <Dialog> 或 <AlertDialog>
- •输入框：是否统一使用 <Input> / <Textarea>
•
样式模式一致性：
- •Tailwind 类名使用模式（如间距、颜色）
- •响应式断点使用一致（sm/md/lg/xl）
- •布局模式（flex/grid）使用规范
•
状态管理一致性：
- •全局状态：是否统一使用 zustand
- •表单状态：是否统一使用 react-hook-form
- •服务端状态：避免重复的 useState + useEffect 获取数据
•
用户反馈一致性：
- •成功/错误提示：是否统一使用 sonner toast
- •加载状态：Loading spinner 或 skeleton 是否一致
- •错误处理：错误边界和错误展示是否统一
•
交互模式一致性：
- •删除操作：是否都有确认对话框
- •表单提交：是否都显示 loading 状态
- •数据刷新：是否使用一致的刷新机制

9. 无效逻辑和业务代码质量

清理冗余代码，优化业务逻辑：

•
无效代码检测：
- •永远不会执行的代码（unreachable code）
- •未使用的函数、变量、类型定义
- •未使用的导入（import）
- •注释掉的大段代码块（超过 10 行）
- •TODO/FIXME 注释从未处理
•
无效逻辑检测：
- •永远为 true/false 的条件判断
- •重复的 if 条件
- •空的 try-catch 块
- •空的函数或组件
- •无用的三元表达式（condition ? true : false）
•
业务代码质量：
- •业务逻辑是否误放在前端组件（应该在 Server Actions）
- •硬编码的业务规则（应该用配置或常量）
- •业务流程是否清晰（复杂流程缺少状态机或流程图）
- •关键业务逻辑是否有注释说明
- •业务验证逻辑是否使用 Zod schemas
- •是否有过时的业务逻辑（功能已废弃但代码未删除）

使用方式

方式 1: 审查单个文件

code

请用 /code-audit 审查 actions/delivery.ts

方式 2: 审查整个功能模块

code

请用 /code-audit 审查投放管理相关的所有文件

方式 3: 审查最近的改动

code

请用 /code-audit 审查我最近修改的文件

方式 4: 全项目扫描

code

请用 /code-audit 对整个项目做一次全面审查

审查流程

当用户调用此 Skill 时，按以下步骤执行：

步骤 1: 确定审查范围

•如果用户指定了文件/目录，直接使用
•如果用户说"最近的改动"，运行 git diff --name-only HEAD~1
•如果用户说"整个项目"，使用 Glob 扫描所有 .ts 和 .tsx 文件
•如果用户说某个功能模块，使用 Grep 查找相关文件

步骤 2: 收集项目规范

•读取 /Users/v/Desktop/code/xhs_ad_agent/Claude.md 了解项目规范
•检查 package.json 了解依赖版本
•检查 tsconfig.json 了解 TypeScript 配置

步骤 3: 逐文件分析

对每个文件执行：

•
读取文件内容 (使用 Read 工具)
•
Next.js 最佳实践检查:
- •是否有 API 路由应该改用 Server Actions（排除流式、文件处理、Webhooks）
- •Server Components 是否误用了客户端 hooks
- •是否正确使用 revalidatePath
- •Route Handler 的使用是否合理（流式响应必须用 Route Handler）
•
代码重复检查:
- •在项目中搜索相似的代码片段
- •标记可以抽离的公共逻辑
•
结构清晰度检查:
- •计算函数行数、嵌套深度
- •检查变量命名质量
- •评估文件组织结构
•
文档检查:
- •复杂函数是否有注释
- •业务逻辑是否清晰
•
性能检查:
- •查找潜在的性能问题
- •识别可优化的代码
•
类型安全检查:
- •检查公共 API 和函数签名是否滥用 any（临时转换、复杂第三方库返回值可接受）
- •检查错误处理
•
前端组件一致性检查（针对 .tsx 组件文件）:
- •UI 组件是否统一使用 shadcn/ui（Button、Input、Dialog 等）
- •表单是否统一使用 react-hook-form
- •Toast 通知是否统一使用 sonner
- •状态管理模式是否一致
- •加载和错误状态展示是否统一
•
无效逻辑检测:
- •查找未使用的导入（import）
- •检测注释掉的代码块
- •检查 TODO/FIXME 标记
- •业务逻辑是否误放在组件中（应该在 Server Actions）
- •硬编码的业务规则

步骤 4: 依赖检查

•使用 Bash 运行 pnpm outdated 查找过时依赖
•使用 WebSearch 查询关键依赖的最新最佳实践

步骤 5: 生成审查报告

以结构化 Markdown 格式输出：

markdown

# 代码审查报告

## 📊 总体评分
- Next.js 最佳实践: ⭐⭐⭐⭐ (8/10)
- 代码复用性: ⭐⭐⭐ (6/10)
- 代码清晰度: ⭐⭐⭐⭐ (7/10)
- 文档完整性: ⭐⭐ (4/10)
- 依赖更新度: ⭐⭐⭐⭐ (8/10)
- 性能优化: ⭐⭐⭐ (6/10)
- 组件一致性: ⭐⭐⭐ (6/10)
- 代码整洁度: ⭐⭐⭐⭐ (7/10)

## 🔴 严重问题 (需要立即修复)

### 1. actions/delivery.ts:145-180
**问题**: 大量重复的投放状态检查逻辑
**影响**: 维护困难，容易出现不一致
**建议**: 抽离到 `lib/utils/delivery-status.ts`
```typescript
// 建议创建
export function validateDeliveryStatus(status: DeliveryStatus) {
  // 统一的状态验证逻辑
}

2. components/works/WorkList.tsx:89

问题: 使用 'use client' 但实际可以是 Server Component 影响: 增加客户端 bundle 大小，降低性能建议: 移除 'use client'，将交互逻辑抽离到子组件

3. components/accounts/AccountForm.tsx:45-120

问题: 业务逻辑直接写在组件中，未使用 Server Actions 影响: 难以复用，测试困难，违反项目规范建议: 将业务逻辑抽离到 actions/account.ts

typescript

// 应该创建
'use server'
export async function updateAccountSettings(data: AccountSettings) {
  // 业务逻辑
}

🟡 中等问题 (建议优化)

1. actions/account.ts:230-280

问题: 函数过长 (50+ 行)，职责不单一建议: 拆分为多个小函数

2. 组件一致性问题

问题: 发现 3 处使用了不一致的 UI 组件

•components/works/DeleteButton.tsx:12 - 自定义按钮而非 shadcn/ui Button
•app/(dashboard)/leads/page.tsx:89 - 使用原生 <button> 而非 <Button>
•components/image/UploadDialog.tsx:34 - 自定义 Dialog 样式建议: 统一使用 shadcn/ui 组件保持一致性

3. 无效代码清理

问题: 发现多处无效代码

•lib/utils/deprecated.ts:全文 - 整个文件已废弃但未删除
•actions/creation.ts:245-267 - 注释掉的代码块 (23 行)
•components/layout/Header.tsx:12,34,56 - 3 处 console.log 调试语句建议: 立即删除无效代码，保持代码库整洁

🟢 低优先级建议

1. 依赖更新

•next: 15.5.7 → 15.6.0 (最新版本)
•react: 19.0.0 ✅ (已是最新)
•@anthropic-ai/sdk: 0.71.2 → 0.72.0

2. 代码风格

•建议使用 Prettier 统一代码格式
•考虑添加 ESLint 规则检查未使用的导入

💡 最佳实践建议

•

Server Actions 重构

•将 app/api/creation/stream/route.ts 改为 Server Action
•示例代码：

typescript

// actions/creation.ts
'use server'
export async function generateCreation(params: CreationParams) {
  // ...
}

•
抽离公共逻辑
- •创建 lib/validators/ 存放 Zod schemas
- •创建 lib/constants/ 存放常量定义
•
添加文档
- •为 actions/delivery.ts 添加 README
- •说明投放状态机和业务流程
•
性能优化
- •图片使用 Next.js Image 组件
- •大列表使用虚拟滚动

📝 需要添加文档的模块

• 投放管理流程 (actions/delivery.ts)
• 创作生成逻辑 (actions/creation.ts)
• 小红书 API 集成 (lib/xhs/)

🎯 下一步行动建议

•立即处理 2 个严重问题
•本周处理 5 个中等问题
•计划重构会议讨论架构优化
•为核心模块补充文档

code


## 特殊检查项（针对此项目）

基于项目的 `Claude.md` 规范：
- **必须使用 Server Actions**: 检查是否有新的 API 路由应该用 Server Actions
- **代码简洁性**: Next.js 15 特性是否充分利用

## 输出格式要求

1. **使用 Markdown 表格**展示问题清单
2. **包含文件路径和行号**，方便定位
3. **给出具体的代码示例**，而非空泛建议
4. **按优先级排序**问题
5. **总结可量化的改进指标**

## 示例对话

**用户**: "用 /code-audit 审查 actions/delivery.ts"

**助手**:
1. 读取 `actions/delivery.ts`
2. 读取 `Claude.md` 了解项目规范
3. 分析文件中的代码模式
4. 在项目中搜索类似代码片段
5. 生成详细的审查报告，包含：
   - 具体问题和行号
   - 重复代码位置
   - 优化建议和示例代码
   - 是否符合 Next.js 最佳实践

---

**用户**: "全面审查整个项目"

**助手**:
1. 扫描所有 `.ts` 和 `.tsx` 文件
2. 运行 `pnpm outdated` 检查依赖
3. 分析每个核心模块
4. 生成综合报告，包含：
   - 项目整体健康度评分
   - Top 10 需要改进的问题
   - 依赖更新建议
   - 架构优化方向
   - 文档缺失清单

## 注意事项

- 审查时考虑项目的实际业务场景，避免过度工程
- 给出的建议要具体可操作，附带代码示例
- 识别技术债务时，要评估修复的收益和成本
- 尊重现有的代码风格，除非明显不合理
- 对于复杂的重构建议，先与团队讨论再执行