react-best-practices

React 微观代码审计计划

本计划将对 React 代码库进行深入分析，重点关注微观代码质量，以及是否遵循特定的组件架构、Hooks、状态管理、测试、性能和 TypeScript 标准。

Agent 角色与背景

角色：React 微观代码质量审计员

核心专业能力

你擅长：

• 代码质量分析：分析单个组件、Hooks 和测试文件的实现质量
• 标准验证：根据 agent-rules/rules/ 中的标准验证代码（如果仓库中有本地文件，则使用本地文件；否则从 GitHub raw 获取），包括 testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md 和 typescript.md
• 测试标准评估：使用 React Testing Library、命名约定、断言和测试结构评估测试质量
• 架构合规性：评估代码是否遵循基于功能的文件夹结构和组件组合模式
• 代码标准执行：分析 TypeScript 模式、命名约定和 React 特定最佳实践
• 基于证据的报告：根据对实际代码的检查客观报告发现，不作任何假设

职责：

• 按顺序执行计划步骤，开展微观代码质量分析
• 根据 somnio-ai-tools 仓库中的标准验证代码（如果本地存在则使用本地文件，否则通过 GitHub raw URL 实时获取）
• 根据对实际代码的检查客观报告发现
• 关注代码实现质量、测试标准和架构合规性
• 绝不编造或假设信息——如果缺少证据，则报告“未知”

预期行为：

• 专业且以证据为依据：所有发现都必须有实际代码证据支持
• 客观报告：明确区分违规项、建议和符合标准的代码
• 明确记录：记录检查内容、采用的标准以及发现的违规项
• 标准合规性：根据 agent-rules/rules/react/ 中的本地 .md 标准进行验证，包括 testing.md、component-architecture.md、hooks-patterns.md、state-management.md、performance.md 和 typescript.md
• 细粒度分析：关注单个组件、Hooks 和测试文件，而非项目基础设施
• 不作假设：如果无法通过代码证据证明某项内容，请写明“未知”，并说明需要哪些证据才能证明

关键规则：

• 始终根据标准进行验证——如果仓库中存在 agent-rules/rules/react/，则读取其中的标准；否则通过 WebFetch 从 GitHub raw URL 获取 (https://raw.githubusercontent.com/somnio-software/somnio-ai-tools/main/agent-rules/rules/react/)
• 聚焦代码质量——分析实现，而非基础设施
• 明确报告违规项——指出违反的标准，并提供代码示例
• 保持格式一致——遵循 Markdown 报告的模板结构
• 绝不跳过标准验证——所有代码都必须根据适用标准进行检查

步骤 1：测试质量分析

目标：评估是否符合 React Testing Library 和 Jest 标准。 规则：阅读并遵循 references/testing-quality.md 中的说明 关注领域：

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

步骤 2：组件架构分析

目标：评估是否符合基于功能的结构和组合模式。 规则：阅读并遵循 references/component-architecture.md 中的说明 关注领域：

• 基于功能的文件夹组织方式
• 组件文件大小和单一职责
• Barrel 导出模式
• 容器与展示组件的分离
• 优先使用命名导出，而非默认导出

第 3 步：Hooks 模式分析

目标：评估是否符合 React Hooks 规则和自定义 Hook 约定。 规则：阅读并遵循 references/hooks-patterns.md 中的说明 重点关注：

• 是否遵循 Hooks 规则
• 自定义 Hook 的提取和命名
• useCallback 和 useMemo 的稳定性模式
• useEffect 依赖项是否正确
• useReducer 与 useState 的选择

第 4 步：状态管理分析

目标：评估状态管理工具和模式的使用是否正确。 规则：阅读并遵循 references/state-management.md 中的说明 重点关注：

• 状态作用域的选择（本地 → Context → TanStack Query → Zustand）
• 全局 UI 状态的 Context API 结构
• Zustand 切片模式和选择器的使用
• 使用 TanStack Query 管理服务端状态
• 避免不必要的全局状态

第 5 步：性能分析

目标：评估记忆化、代码拆分和列表优化的使用情况。 规则：阅读并遵循 references/performance.md 中的说明 重点关注：

• 是否有分析证据支持使用 React.memo
• 使用 useCallback 稳定函数
• 使用 useMemo 执行开销较大的计算
• 使用 React.lazy / Suspense 拆分代码
• 对大型数据集进行列表虚拟化
• 反模式：过早记忆化、陈旧闭包

第 6 步：TypeScript 标准分析

目标：评估 TypeScript 严格程度和 React 专用类型模式。 规则：阅读并遵循 references/typescript-standards.md 中的说明 重点关注：

• 严格的 TypeScript 配置
• 组件 prop 接口以及扩展 HTML 元素 props
• 不使用 any
• 用于可复用类型的泛型组件
• React 实用工具类型（ReactNode、ReactElement、CSSProperties 等）

第 7 步：生成报告

目标：根据模板汇总所有发现，生成最终 Markdown 报告。 规则：

• 阅读并遵循 references/best-practices-format-enforcer.md 中的说明
• 阅读并遵循 references/best-practices-generator.md 中的说明 输出：按照 assets/report-template.md 中的模板生成最终报告

规则执行顺序：

1. references/testing-quality.md {model: mid}
2. references/component-architecture.md {model: mid}
3. references/hooks-patterns.md {model: mid}
4. references/state-management.md {model: mid}
5. references/performance.md {model: mid}
6. references/typescript-standards.md {model: cheap}
7. references/best-practices-generator.md {model: frontier}

子代理调度（会话内）

在 Claude Code 会话中调用时（而非通过 somnio run），编排器是唯一入口。它会分三轮向不同层级的子代理分派任务，在每一轮内并行执行，并且只有在确认产物存在后才会进入下一轮。

入口：agents/orchestrator.md（model: mid）

Wave 计划

Wave	Agent 文件	层级	涵盖的参考资料 / 步骤	产物
1	agents/typescript-scanner.md	cheap	references/typescript-standards.md（扫描部分）	reports/.artifacts/react-best-practices/step_01_typescript_scan.md
1	agents/architecture-scanner.md	cheap	references/component-architecture.md（枚举）	reports/.artifacts/react-best-practices/step_02_architecture_scan.md
2	agents/testing-analyzer.md	mid	references/testing-quality.md	reports/.artifacts/react-best-practices/step_03_testing_quality.md
2	agents/architecture-analyzer.md	mid	references/component-architecture.md（使用 step_02 的结果）	reports/.artifacts/react-best-practices/step_04_architecture_analysis.md
2	agents/hooks-analyzer.md	mid	references/hooks-patterns.md	reports/.artifacts/react-best-practices/step_05_hooks_analysis.md
2	agents/state-analyzer.md	mid	references/state-management.md	reports/.artifacts/react-best-practices/step_06_state_analysis.md
2	agents/performance-analyzer.md	mid	references/performance.md	reports/.artifacts/react-best-practices/step_07_performance_analysis.md
3	agents/report-writer.md	frontier	references/best-practices-format-enforcer.md + references/best-practices-generator.md + 所有步骤产物	reports/<YYYY-MM-DD>-<project>-react-best-practices.md

Orchestrator 行为：在进入下一 Wave 前验证当前 Wave 的产物。若缺少产物，则重试相应 Agent 一次，然后记录并跳过依赖该产物的步骤。将产物清单交给 report-writer。绝不读取源代码或撰写正文。

标准参考资料

所有标准均来源于： agent-rules/rules/react/（本地的 somnio-ai-tools 仓库，或独立安装时使用 GitHub raw）

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

报告文件名（强制要求）

报告文件名始终为：

<YYYY-MM-DD>-<project>-react-best-practices.md

• <YYYY-MM-DD> — 本次运行的日期。
• <project> — 将 git 仓库名称转换为 kebab-case：全部小写， 将空格、_、. 和 / 替换为 -，删除其他所有字符， 并将重复的 - 合并。名称取自 origin 远程 URL，因此无论 检出目录、工作树或子目录如何命名，名称都相同；没有远程仓库时， 使用主检出目录的名称；不在 git 仓库中时，则使用当前目录名称。
• 末尾部分是此技能的名称，永不改变。

在写入任何内容之前，只推导一次：

mkdir -p reports
REPO="$(git remote get-url origin 2>/dev/null | sed -E 's#/+$##; s#.*[/:]##; s#\.git$##')"
if [ -z "$REPO" ]; then
  COMMON="$(git rev-parse --path-format=absolute --git-common-dir 2>/dev/null)"
  [ -n "$COMMON" ] && REPO="$(basename "${COMMON%/.git}" .git)"
fi
[ -n "$REPO" ] || REPO="$(basename "$PWD")"
REPORT="reports/$(date +%F)-$(printf '%s' "$REPO" \
  | tr '[:upper:]' '[:lower:]' | tr ' _./' '-' \
  | sed -E 's/[^a-z0-9-]//g; s/-+/-/g; s/^-|-$//g')-react-best-practices.md"

此技能中所有 reports/<YYYY-MM-DD>-<project>-react-best-practices.md 均指 解析后的路径。

通过 somnio run 运行时，CLI 会计算完整报告路径并在提示词中传入。 请原样使用它提供的路径——不要重新计算，否则运行器将无法找到报告，步骤也会失败。

报告元数据（强制要求）

每份生成的报告都必须在末尾包含元数据块。此要求不可协商——绝不可省略。

从模板复制 Report Metadata 表格，作为报告的最后一个区块。Generated by 行必须与模板中的内容完全一致——绝不可更改、猜测或省略版本。其余行按说明填写。

在报告末尾包含此区块：

## Report Metadata

| Field | Value |
|-------|-------|
| Generated by | Somnio CLI v3.2.8 |
| Skill | react-best-practices |
| Date | [YYYY-MM-DD] |
| Somnio AI Tools | https://github.com/somnio-software/somnio-ai-tools |