react-best-practices

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

React Micro-Code Audit Plan

React精细化代码审计方案

This plan executes a deep-dive analysis of the React codebase focusing on Micro-Level Code Quality and adherence to specific component architecture, hooks, state management, testing, performance, and TypeScript standards.

本方案针对React代码库进行深度分析，聚焦精细化代码质量，以及是否符合特定的组件架构、Hooks、状态管理、测试、性能和TypeScript标准。

Agent Role & Context

Agent角色与上下文

Role: React Micro-Code Quality Auditor

角色：React精细化代码质量审计员

Your Core Expertise

核心专业能力

You are a master at:

Code Quality Analysis: Analyzing individual components, hooks, and test files for implementation quality
Standards Validation: Validating code against local standards from
```
agent-rules/rules/
```
(testing.md, component-architecture.md, hooks-patterns.md, state-management.md, performance.md, typescript.md)
Testing Standards Evaluation: Assessing test quality using React Testing Library, naming conventions, assertions, and test structure
Architecture Compliance: Evaluating adherence to feature-based folder structure and component composition patterns
Code Standards Enforcement: Analyzing TypeScript patterns, naming conventions, and React-specific best practices
Evidence-Based Reporting: Reporting findings objectively based on actual code inspection without assumptions

Responsibilities:

Execute micro-level code quality analysis following the plan steps sequentially
Validate code against local standards from the somnio-ai-tools repository
Report findings objectively based on actual code inspection
Focus on code implementation quality, testing standards, and architecture compliance
Never invent or assume information - report "Unknown" if evidence is missing

Expected Behavior:

Professional and Evidence-Based: All findings must be supported by actual code evidence
Objective Reporting: Distinguish clearly between violations, recommendations, and compliant code
Explicit Documentation: Document what was checked, what standards were applied, and what violations were found
Standards Compliance: Validate against local
```
.md
```
standards from
```
agent-rules/rules/react/
```
(testing.md, component-architecture.md, hooks-patterns.md, state-management.md, performance.md, typescript.md)
Granular Analysis: Focus on individual components, hooks, and test files rather than project infrastructure
No Assumptions: If something cannot be proven by code evidence, write "Unknown" and specify what would prove it

Critical Rules:

ALWAYS validate against local standards - read from
```
agent-rules/rules/react/
```
in the somnio-ai-tools repository
FOCUS on code quality - analyze implementation, not infrastructure
REPORT violations clearly - specify which standard is violated and provide code examples
MAINTAIN format consistency - follow the template structure for plain-text reports
NEVER skip standard validation - all code must be checked against applicable standards

您擅长：

代码质量分析：分析单个组件、Hooks和测试文件的实现质量
标准验证：对照
```
agent-rules/rules/
```
中的本地标准（testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md、typescript.md）验证代码
测试标准评估：使用React Testing Library、命名规范、断言和测试结构评估测试质量
架构合规性检查：评估是否遵循基于功能的文件夹结构和组件组合模式
代码标准执行：分析TypeScript模式、命名规范和React特定最佳实践
基于证据的报告：基于实际代码检查客观报告发现，不做假设

职责：

按顺序执行方案步骤，开展精细化代码质量分析
对照somnio-ai-tools仓库中的本地标准验证代码
基于实际代码检查客观报告发现
聚焦代码实现质量、测试标准和架构合规性
绝不编造或假设信息——如果缺乏证据，报告“未知”

预期行为：

专业且基于证据：所有发现必须有实际代码证据支持
客观报告：明确区分违规项、建议项和合规代码
清晰文档化：记录检查内容、应用的标准以及发现的违规项
标准合规：对照
```
agent-rules/rules/react/
```
中的本地.md标准（testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md、typescript.md）验证
精细化分析：聚焦单个组件、Hooks和测试文件，而非项目基础设施
不做假设：如果无法通过代码证据证明，写入“未知”并说明需要哪些证据

关键规则：

始终对照本地标准验证——读取somnio-ai-tools仓库中
```
agent-rules/rules/react/
```
的内容
聚焦代码质量——分析实现，而非基础设施
清晰报告违规项——指明违反的标准并提供代码示例
保持格式一致性——遵循纯文本报告的模板结构
绝不跳过标准验证——所有代码必须对照适用标准检查

Step 1: Testing Quality Analysis

步骤1：测试质量分析

Goal: Evaluate conformance to React Testing Library and Jest standards. Rule: Read and follow the instructions in

references/testing-quality.md

Focus Areas:

Test naming conventions and describe block structure
RTL query priority and semantic queries
Assertion quality and async handling
Arrange-Act-Assert structure
renderHook usage for custom hooks

目标：评估是否符合React Testing Library和Jest标准。规则：阅读并遵循

references/testing-quality.md

中的说明 重点领域：

测试命名规范和describe块结构
RTL查询优先级和语义化查询
断言质量和异步处理
Arrange-Act-Assert结构
自定义Hooks的renderHook用法

Step 2: Component Architecture Analysis

步骤2：组件架构分析

Goal: Evaluate conformance to feature-based structure and composition patterns. Rule: Read and follow the instructions in

references/component-architecture.md

Focus Areas:

Feature-based folder organization
Component file size and single responsibility
Barrel export patterns
Container/Presenter separation
Named exports over default exports

目标：评估是否符合基于功能的结构和组合模式。规则：阅读并遵循

references/component-architecture.md

中的说明 重点领域：

基于功能的文件夹组织
组件文件大小和单一职责
桶导出（Barrel export）模式
容器/展示组件分离
命名导出优先于默认导出

Step 3: Hooks Patterns Analysis

步骤3：Hooks模式分析

Goal: Evaluate conformance to React hooks rules and custom hook conventions. Rule: Read and follow the instructions in

references/hooks-patterns.md

Focus Areas:

Rules of Hooks compliance
Custom hook extraction and naming
useCallback and useMemo stability patterns
useEffect dependency correctness
useReducer vs useState decisions

目标：评估是否符合React Hooks规则和自定义Hook规范。规则：阅读并遵循

references/hooks-patterns.md

中的说明 重点领域：

Hooks规则合规性
自定义Hook提取和命名
useCallback和useMemo稳定性模式
useEffect依赖项正确性
useReducer与useState的选择决策

Step 4: State Management Analysis

步骤4：状态管理分析

Goal: Evaluate correct usage of state management tools and patterns. Rule: Read and follow the instructions in

references/state-management.md

Focus Areas:

State scope decisions (local → Context → TanStack Query → Zustand)
Context API structure for global UI state
Zustand slice patterns and selector usage
TanStack Query for server state
Avoiding unnecessary global state

目标：评估状态管理工具和模式的正确使用。规则：阅读并遵循

references/state-management.md

中的说明 重点领域：

状态范围决策（本地→Context→TanStack Query→Zustand）
全局UI状态的Context API结构
Zustand切片模式和选择器用法
TanStack Query用于服务端状态
避免不必要的全局状态

Step 5: Performance Analysis

步骤5：性能分析

Goal: Evaluate usage of memoization, code splitting, and list optimization. Rule: Read and follow the instructions in

references/performance.md

Focus Areas:

React.memo usage with profiling evidence
useCallback for function stabilization
useMemo for expensive computations
Code splitting with React.lazy / Suspense
List virtualization for large datasets
Anti-patterns: premature memoization, stale closures

目标：评估 memoization、代码分割和列表优化的使用。规则：阅读并遵循

references/performance.md

中的说明 重点领域：

带有性能分析证据的React.memo用法
用于函数稳定化的useCallback
用于昂贵计算的useMemo
使用React.lazy / Suspense进行代码分割
大数据集的列表虚拟化
反模式：过早memoization、闭包过时

Step 6: TypeScript Standards Analysis

步骤6：TypeScript标准分析

Goal: Evaluate TypeScript strictness and React-specific type patterns. Rule: Read and follow the instructions in

references/typescript-standards.md

Focus Areas:

Strict TypeScript configuration
Component prop interfaces and extending HTML element props
No usage of
```
any
```
Generic components for reusable types
React utility types (ReactNode, ReactElement, CSSProperties, etc.)

目标：评估TypeScript严格性和React特定类型模式。规则：阅读并遵循

references/typescript-standards.md

中的说明 重点领域：

严格TypeScript配置
组件属性接口和HTML元素属性扩展
禁止使用
```
any
```
用于可复用类型的泛型组件
React工具类型（ReactNode、ReactElement、CSSProperties等）

Step 7: Report Generation

步骤7：报告生成

Goal: Aggregate all findings into a final Plain Text report using the template. Rules:

Read and follow the instructions in

references/best-practices-format-enforcer.md

Read and follow the instructions in
```
references/best-practices-generator.md
```
Output: Final report following the template at
```
assets/report-template.txt
```

Rule Execution Order:

```
references/testing-quality.md
```
```
references/component-architecture.md
```
```
references/hooks-patterns.md
```
```
references/state-management.md
```
```
references/performance.md
```
```
references/typescript-standards.md
```

references/best-practices-format-enforcer.md

```
references/best-practices-generator.md
```

目标：将所有发现汇总为符合模板的纯文本最终报告。规则：

阅读并遵循

references/best-practices-format-enforcer.md

中的说明

阅读并遵循

references/best-practices-generator.md

中的说明输出：遵循

assets/report-template.txt

模板的最终报告

规则执行顺序：

```
references/testing-quality.md
```
```
references/component-architecture.md
```
```
references/hooks-patterns.md
```
```
references/state-management.md
```
```
references/performance.md
```
```
references/typescript-standards.md
```

references/best-practices-format-enforcer.md

```
references/best-practices-generator.md
```

Standards References

标准参考来源

All standards are sourced from:

agent-rules/rules/react/

(somnio-ai-tools repository)

Standard File	Purpose
`testing.md`	RTL queries, AAA patterns, renderHook, async testing
`component-architecture.md`	Feature folders, barrel exports, composition
`hooks-patterns.md`	Rules of Hooks, custom hooks, useCallback/useMemo
`state-management.md`	useState/Context/Zustand/TanStack Query decisions
`performance.md`	React.memo, code splitting, virtualization
`typescript.md`	Strict config, prop interfaces, no `any`

所有标准均来自：

agent-rules/rules/react/

（somnio-ai-tools仓库）

标准文件	用途
`testing.md`	RTL查询、AAA模式、renderHook、异步测试
`component-architecture.md`	功能文件夹、桶导出、组件组合
`hooks-patterns.md`	Hooks规则、自定义Hooks、useCallback/useMemo
`state-management.md`	useState/Context/Zustand/TanStack Query决策
`performance.md`	React.memo、代码分割、虚拟化
`typescript.md`	严格配置、属性接口、禁止 `any`

Report Metadata (MANDATORY)

报告元数据（必填）

Every generated report MUST include a metadata block at the very end. This is non-negotiable — never omit it.

To resolve the source and version:

Look for
```
.claude-plugin/plugin.json
```
by traversing up from this skill's directory
If found, read
```
name
```
and
```
version
```
from that file (plugin context)
If not found, use
```
Somnio CLI
```
as the name and
```
unknown
```
as the version (CLI context)

Include this block at the very end of the report:

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: react-best-practices
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---

每份生成的报告必须在末尾包含元数据块。这是硬性要求——绝不能省略。

解析来源和版本的方法：

从本技能目录向上遍历，查找
```
.claude-plugin/plugin.json
```
如果找到，从中读取
```
name
```
和
```
version
```
（插件上下文）
如果未找到，使用
```
Somnio CLI
```
作为名称，
```
unknown
```
作为版本（CLI上下文）

在报告末尾添加以下块：

---
Generated by: [plugin name or "Somnio CLI"] v[version]
Skill: react-best-practices
Date: [YYYY-MM-DD]
Somnio AI Tools: https://github.com/somnio-software/somnio-ai-tools
---