审查 React 代码变更时：用结构化评审发现架构…

在合并 PR、实现新功能后或需要验证 React 组件架构时，对 React 应用进行系统性代码评审并输出分级问题报告。

适用场景

解决思路

1. 识别范围：确定待审查的 React 组件和 hooks。使用 glob 发现 .tsx/.jsx 文件，使用 grep 识别组件定义、hook 使用和 context provider。
2. 分析组件架构：验证组件组合是否正确——检查单一职责、合适大小和可复用性。查找大于 200 行、props 超过 7 个或混合关注点的组件。
3. 审查 Hook 用法：验证 hooks 使用是否正确——检查 useEffect/useMemo/useCallback 的依赖数组，验证 useEffect 中的清理函数，识别因缺失或错误 memoization 导致的不必要重渲染。
4. 评估状态管理：评估 state 放在哪里——检查是否合理就近放置、是否存在不必要的状态提升、Context 与外部 store 的使用是否合适。验证服务端状态使用 TanStack Query、SWR 或类似库，而不是手写 useEffect + useState 模式。
5. 检查可访问性：审查语义 HTML 用法、ARIA 属性、键盘导航、焦点管理和屏幕阅读器兼容性。验证交互元素可访问，表单输入有正确 label。
6. 评估性能：查找不必要重渲染、昂贵组件缺少 React.memo、useCallback/useMemo 使用不当、缺少代码分割、过大的 bundle 导入。
7. 审查 TypeScript 集成：检查 props 类型定义、事件处理器类型、泛型组件模式、utility types 的正确使用。验证在可以使用具体类型的地方没有使用 any。
8. 生成评审报告：生成结构化报告，包含按严重程度分类的问题（Critical、Warning、Suggestion）、正面观察，以及带代码示例的优先建议。
9. 按输出格式组织评审结果第 1 部分 Summary：简要概述，包含总体质量评分（1-10）和关键观察。
10. 按输出格式组织评审结果第 2 部分 Critical Issues (Must Fix)：导致 bug、安全漏洞或功能损坏的问题。
11. 按输出格式组织评审结果第 3 部分 Warnings (Should Fix)：违反最佳实践、导致性能问题或降低可维护性的问题。
12. 按输出格式组织评审结果第 4 部分 Suggestions (Consider Improving)：代码组织、可访问性或开发者体验方面的改进建议。
13. 按输出格式组织评审结果第 5 部分 Positive Observations：值得肯定的良好实现模式和实践。
14. 按输出格式组织评审结果第 6 部分 Recommendations：按优先级排列的后续步骤，并针对影响最大的改进提供代码示例。
15. 遵循最佳实践：保持组件职责聚焦——单一职责，少于 200 行。
16. 遵循最佳实践：将 state 与使用它的组件就近放置。
17. 遵循最佳实践：使用自定义 hooks 从组件中提取可复用逻辑。
18. 遵循最佳实践：仅在测量到重渲染成本值得时才应用 React.memo。
19. 遵循最佳实践：服务端状态使用 TanStack Query 或 SWR，而不是 useEffect + useState。
20. 遵循最佳实践：当订阅外部资源时，始终在 useEffect 中包含清理函数。
21. 遵循最佳实践：优先写语义 HTML，仅在原生语义不足时添加 ARIA。
22. 遵循最佳实践：使用 TypeScript strict mode，避免在组件 props 中使用 any。
23. 遵循最佳实践：实现 error boundaries 以优雅处理失败。
24. 遵循最佳实践：优先使用组合，而不是复杂的条件渲染。
25. 约束：尊重项目的 React 版本——避免为旧版本建议 React 19 特性。
26. 约束：除非项目已经标准化采用某个状态管理库，否则不要强制使用特定状态管理库。
27. 约束：Memoization 并不总是有益——仅当重渲染影响可测量时才建议使用。
28. 约束：可访问性建议应以 WCAG 2.1 AA 为基线。
29. 约束：聚焦高置信度问题——避免对主观风格选择产生误报。
30. 约束：不要在没有明确、可衡量收益的情况下建议重写可工作的组件。
31. 通过 agent 系统调用时，委托给 react-software-architect-review agent 进行深度架构分析。
32. 参考 references/ 目录中的评审清单和模式文档：references/hooks-patterns.md、references/component-architecture.md、references/accessibility.md。

适用边界 · 注意事项

• 项目使用旧版 React 时，不适用建议 React 19 新特性（如 use、useOptimistic、useFormStatus、Actions）。
• 项目未标准化使用某个状态管理库时，不适用强制指定具体状态管理库；未测量到重渲染影响时，不适用建议 memoization。
• 没有明确、可衡量收益时，不适用建议重写可工作的组件；对主观风格选择不适用，应聚焦高置信度问题并避免误报。