review-frontend

前端代码审查

参数

• --parallel：如果 Agent 支持子 Agent，则提示按技术领域分发任务（参见步骤 5）。如果不支持，则按顺序执行审查，输出相同。
• 路径：目标目录（默认为当前工作目录）

步骤 1：识别已更改的文件

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.(tsx?|jsx?|mjs|cjs|css)$|^(remix|vite)\.config\.'

步骤 2：检测技术

# Detect Remix v2 (any official adapter). When matched, the Remix-specific
# surface is delegated to the review-remix-v2 skill in Step 4.
grep -E '"@remix-run/(react|node|cloudflare|deno|serve)"' package.json | head -3

# Detect React Flow
grep -r "@xyflow/react\|ReactFlow\|useNodesState" --include="*.tsx" -l | head -3

# Detect Zustand
grep -r "from 'zustand'\|create\(\(" --include="*.ts" --include="*.tsx" -l | head -3

# Detect Tailwind v4
grep -r "@theme\|@layer theme" --include="*.css" -l | head -3

# Check for test files
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.test\.tsx?$'

步骤 3：加载验证协议

在对代码做出任何实质性判断之前，加载 review-verification-protocol 技能。

步骤 5 前的检查： 技能已加载（或其检查清单已在上下文中打开）。在此检查通过之前，不要判定严重程度或编写发现项。

步骤 4：加载技能

阅读以下每项适用技能（打开其 SKILL.md），确保审查相应领域前，其指导内容已纳入上下文。

Remix v2 分支（步骤 2 在 package.json 中检测到 @remix-run/*）：

• 加载 review-remix-v2 — 统筹协调器，会加载全部六项 Remix v2 领域审查技能（路由、数据流、表单、错误边界、性能/SSR、元数据与会话），并执行自身的检测遥测。针对 Remix 特定部分运行该技能，并将其发现项整合到本次审查的输出中。
• 不要同时加载 react-router-code-review — Remix v2 基于 React Router v6，但通过 Remix 的路由模块约定处理路由；在此上下文中，remix-v2-routing-review（通过统筹技能加载）会覆盖这一部分。
• 仍需加载 shadcn-code-review 和以下条件适用的技能 — 它们与 Remix 层无关，无论使用何种路由器，都适用于组件、样式和状态代码。

非 Remix 分支（默认）：

• react-router-code-review
• shadcn-code-review

根据检测结果有条件地加载（两个分支均适用）：

条件	技能
检测到 @xyflow/react	react-flow-code-review
检测到 Zustand	zustand-state
检测到 Tailwind v4	tailwind-v4
测试文件有更改	vitest-testing

步骤 5：审查

如果 Agent 支持子 Agent（且已请求或适合使用 --parallel），则并行派发每个技术领域的一个子 Agent；否则在单一上下文中按顺序审查相同领域。两种路径的输出相同。

并行路径：

1. 预先检测所有技术
2. 为每个技术领域派发一个子 Agent，各自加载相应技能并审查其领域
3. 等待所有子 Agent 返回
4. 整合发现项

顺序路径：

1. 加载适用技能
2. 首先审查 React Router 模式
3. 审查 shadcn/ui 模式
4. 审查检测到的技术领域
5. 整合发现项

步骤 6：验证发现项

报告任何问题之前：

1. 重新阅读实际代码（而不仅是差异上下文）
2. 对于“未使用”的说法——是否搜索了所有引用？
3. 对于“缺失”的说法——是否检查了框架/父级处理逻辑？
4. 对于语法问题——是否对照当前版本文档进行了核实？
5. 移除任何仅属风格偏好、而非实际问题的发现项

提升为严重/主要问题前的检查： 对于该项，（2）–（4）均已满足；适用时还需提供具体证据，例如打开的 FILE:LINE 文件、引用搜索结果或引用的父级/框架代码，而不能仅依据差异上下文。

步骤 7：审查收敛

单次审查完整性

你必须在单次审查中报告所有类别（风格、逻辑、类型、测试、安全性、性能）的所有问题。不要把问题留到后续审查轮次。

提交问题前，请先自问：

• “如果我建议的修复全部应用，我能否在修复后的代码中发现新问题？”
• “我是否要求新增代码（测试、类型、模块），而这些代码本身也需要审查？”

如果任一答案为“是”，请现在就把预期会出现的后续问题纳入本次审查，以便作者一次性解决所有问题。

范围规则

• 仅审查差异中的代码及与之直接相关的现有代码
• 不要要求新增差异之前不存在的功能、测试基础设施或架构变更
• 如果缺少测试覆盖，将其作为一个 Minor 问题提出（“缺少对 X、Y、Z 的测试覆盖”）——不要指定会引入大量新代码的实现细节，例如模拟库、行为提取或依赖注入模式
• 类型规范、文档和命名问题属于 Minor，除非它们影响公共 API 契约
• 不要要求新增依赖项（例如 Mox、测试库、linter 插件）

修复复杂度预算

对现有代码的修复，无论工作量大小，都应按其实际严重程度提出。

但是，对于差异之前不存在的全新代码，相关要求必须归类为 Informational：

• 添加新依赖项（例如 Mox、linter 插件）
• 创建全新的模块、文件或测试套件
• 提取新的行为、协议或抽象

这些是供作者在未来工作中考虑的改进建议，不是审查阻塞项。

迭代策略

如果这是修复后的重新审查：

• 仅验证先前指出的问题是否已正确解决
• 不要提出与先前问题无关的新发现
• 接受尚未修复的 Minor/Nice-to-Have 问题；不要再次提出
• 重新审查的目标是验证，而非发现问题

输出格式

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (bug, a11y, perf, security)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

修复后验证

修复完成后，运行：

npm run lint
npm run typecheck
npm run test

所有检查都必须通过才能批准。

门槛

按顺序推进；不要通过非正式地重述某个通过条件来跳过它。

1. 已记录范围 —— **通过条件：**你已获得 Step 1 命令的输出（或明确的替代路径列表），其中列出了本次审查的范围。
2. 已加载协议 + 分支技能 —— **通过条件：**已加载 review-verification-protocol 和 shadcn-code-review，并且满足以下条件之一：(a) Step 2 检测到 Remix v2，且已加载 review-remix-v2（未加载 react-router-code-review）；或 (b) Step 2 未检测到 Remix v2，且已加载 react-router-code-review —— 必须在首次判断严重程度前完成。
3. 条件性技能 —— **通过条件：**对于 Step 2 中的每项检测（Remix v2、@xyflow/react、Zustand、Tailwind v4、测试文件），你要么已加载列出的技能，要么已记录检测结果为否定（哪个命令未返回匹配项）。
4. Critical/Major 证据 —— **通过条件：**每条此类问题都引用树中存在的 FILE:LINE，并且符合该问题类型在 Step 6 中的通过规则。
5. 单次输出 —— **通过条件：**Issues 部分使用连续的编号序列，并且本交付内容满足 Step 7 的单次审查完整性要求（不保留任何问题类别或审查轮次）。

规则

• 审查前加载技能（不要审查后再加载）
• 按顺序为每个问题编号（1、2、3……）
• 为每个问题注明 FILE:LINE
• 清楚区分问题、原因和修复方案
• 根据实际严重程度分类
• 不要假设采用 Next.js 模式（不要使用 "use client"）
• 修复后运行验证
• 一次性报告所有问题——不要留到后续迭代再报告
• 复审仅验证之前的修复——不要发现新问题
• 对新增代码的请求（新模块、依赖项、测试套件）属于信息性内容，不会阻止批准
• Verdict 不考虑轻微和信息性问题——只有严重和重大问题会阻止批准