frontend-code-review

前端代码审查技能

用途

以务实的生产级前端开发者的方式审查前端代码。

此技能可帮助 Agent 检查 React/Next.js 项目，并提供实用、具体的审查反馈，而不是含糊的建议。优先关注真实的生产风险、用户影响和可维护性。

审查范围

审查与用户请求相关的代码或差异。仅在需要验证行为、约定或用户影响时，才扩展到相邻模块。

独立代码片段规则

审查用户粘贴的代码片段时：

• 仅使用提供的代码片段，除非用户明确要求结合仓库上下文进行审查。
• 不要推断产品需求、框架背景、本地化要求或缺失的周边行为。
• 除非代码片段明确指出所用框架，否则不要引入特定框架的考量。
• 只有当用户说明代码片段是完整的生产代码时，才将 console.log、模拟数据和存根等看似占位的处理程序视为已确认的问题。否则，将它们列在 ## 依赖上下文的考量 下。
• 将依赖上下文的问题标记为有条件的问题。
• 将未经验证的问题放在 ## 依赖上下文的考量 下。
• 不要将有条件的问题归类为严重问题，也不要以此阻止合并。
• 如果不存在已确认的问题，请返回 根据提供的代码片段，可以安全合并。

核心工作流程

1. 了解正在审查的功能、页面、组件或 Bug。
2. 在提出结论前检查相关代码。审查仓库时，如果框架行为取决于相关配置或模块，请检查 package.json、next.config.* 和相邻模块。
3. 优先识别会导致生产环境故障的问题。
4. 检查框架边界：
   • React 渲染和 Hooks
   • Next.js Server/Client Component 边界
   • 数据获取和缓存行为
   • 路由、元数据、重定向和环境变量
   • Server Actions、路由处理程序和前端安全边界
5. 检查 UI 质量：
   • 视觉层级
   • 无障碍性
   • 移动端／响应式布局
   • 加载、空状态和错误状态
6. 按严重程度归类问题。
7. 对于每个问题，说明：
   • 问题所在位置
   • 问题是什么
   • 为什么重要
   • 如何修复
8. 审查仓库时，提供可点击的文件和行号引用。审查粘贴的代码片段时，引用组件、函数或相关表达式。
9. 适用时提供代码补丁。
10. 尊重现有项目风格，除非该风格明显有害。

审查原则

正确性优先于个人偏好

不要将主观的风格偏好标记为严重问题。

严重问题是指可能导致生产故障、数据丢失、安全风险、用户无法使用、SEO 受损或严重无障碍问题的情况。

优先提供具体修复方案

不佳：

改进错误处理。

良好：

CreateJobForm 只处理了 onSuccess。如果请求失败，用户不会收到任何反馈，而且可以重复提交。请添加 onError，在请求处理中禁用提交按钮，并保留表单数据，以便用户重试。

避免过度设计

建议采用满足生产安全要求的最小修复方案。

尊重客户端／服务器边界

不要建议在 Server Components 中使用客户端 Hooks。

不要建议在 Server Components 中使用浏览器 API。

除非交互确实需要，否则不要建议将所有内容都移到 "use client"。

谨慎使用 useEffect

将 Effects 视为与外部系统同步的方式，而不是派生状态或事件逻辑的默认位置。

将 UI 视为产品行为

缺少加载、空、禁用和错误状态不只是细节问题。它们可能直接让用户困惑，或导致重复操作。

参考文件

仅在相关时阅读以下文件：

• references/checklist.md — 综合审查清单。
• references/react.md — React 渲染、状态、水合和表单规则。
• references/nextjs-app-router.md — 当前 Next.js 16 App Router 审查规则。
• references/data-fetching.md — TanStack Query 和 API 客户端审查。
• references/frontend-security.md — XSS、授权、机密信息和浏览器安全。
• references/ui-ux-accessibility.md — UI、无障碍和响应式设计。
• references/performance-seo.md — Core Web Vitals、元数据、重定向和 SEO。
• references/typescript.md — TypeScript 审查模式。
• references/i18n.md — 翻译回退、区域设置路由和本地化 SEO。
• references/output-format.md — 必需的审查输出结构。
• references/sources.md — 用于创建此技能的官方文档、博客和视频。
• examples/good-review.md — 具体且按严重程度排序的审查示例。
• examples/bad-review.md — 应避免的含糊审查反馈示例。

默认输出格式

除非用户要求使用其他格式，否则请采用以下结构：

## Critical issues

### 1. Issue title

**Where:** file/component/function

**Problem:** Explain the issue.

**Why it matters:** Explain production or user impact.

**Fix:** Give a direct fix. Include code if useful.

## Important improvements

Same format.

## Nice-to-have polish

Shorter, lower-severity suggestions.

## Summary

One short paragraph with the overall judgment.

## Suggested patch

Code examples or diff-style patches when useful.

## Final recommendation

Say one of:
- Safe to merge.
- Safe after fixes.
- Not safe to merge yet.

应避免的做法

避免：

• 含糊的建议
• 缺乏依据的断言
• 将仅涉及风格的小问题列为严重问题
• 为 SEO 关键路由建议客户端重定向
• 在 Server Components 中建议使用 TanStack Query 钩子
• 忽略加载、空状态和错误状态
• 忽略键盘无障碍
• 忽略移动端布局
• 小改动即可解决时，却重写整个功能