Artificial Intelligence

react-doctor Scores Your AI-Generated React, Then Teaches Your Agent to Stop Writing It

By 吴琼琼 · May 12, 2026

Read original on juejin.cn ↗ Google Translate ↗ Alt translation

AI coding agents produce React that runs but routinely ships with stale closures, wasted re-renders, and silent accessibility failures that linters miss. A tool that both audits this damage and teaches the agent to avoid it cuts review time and prevents production bugs that TypeScript and ESLint alone cannot catch.

Summary

A single `npx` command scans an entire React project—Next.js, Vite, React Native—and produces a Lighthouse-style health score with file-and-line diagnostics for cascading setState calls, derived state, closure traps, unnecessary re-renders, XSS risks, missing aria labels, and dead code. Every finding includes a fix suggestion, not just a flag.

CI integration posts scan results as PR comments and can fail the build on warnings, blocking bad React from merging. The tool also merges existing ESLint or Oxlint configs so teams layer health scoring on top of their current lint setup without replacing it.

The standout feature is `react-doctor install`, which injects its rules directly into local AI coding agents. After installation, Claude Code, Cursor, Codex, and others generate React that respects the same checks the scanner enforces—shifting the tool from post-hoc cure to upfront prevention.

Takeaways

— Running `npx -y react-doctor@latest .` in a project root produces a 0–100 health score and a per-file issue list with fix suggestions.

— Scores of 75+ are Great, 50–74 Needs work, and below 50 is Critical.

— Checks span six categories: state and effects, performance, architecture, security, accessibility, and dead code.

— Detects cascading setState, derived state that should be useMemo, setState during render, and stale closures from incomplete dependency arrays.

— Flags unnecessary useMemo/useCallback as well as missing ones, because blind memoization carries its own overhead.

— CI integration via GitHub Actions scans changed files on PRs, comments findings, and can fail the build on warnings.

— `react-doctor install` injects rules as Agent Skills into Claude Code, Cursor, Codex, OpenCode, and 50+ other agents so they generate compliant React from the start.

— Automatically merges existing ESLint and Oxlint configs into its scoring, and supports rule-level, file-level, and override-based ignores.

— First-run scan on a 300-component Next.js project took about 30 seconds and surfaced 40+ issues.

— Some rules, particularly unnecessary useMemo detection, produce false positives in complex type-inference scenarios.

Conclusions

Quantifying React code quality with a single numeric score changes team conversations from subjective arguments to evidence-based decisions about where to spend improvement time.

Teaching an agent to write compliant code at generation time is a more scalable strategy than reviewing and fixing its output afterward—it treats the cause, not the symptom.

The tool's value sits in a gap that ESLint and Biome explicitly do not fill: they lint patterns, but they do not assess overall codebase health or prioritize severity across categories.

AI-generated React is especially prone to closure traps and derived-state bloat because agents optimize for immediate correctness, not for render efficiency or long-term maintainability.

Acceptable false-positive rates on performance rules are a known tradeoff in static analysis; the real question is whether the time saved catching real issues outweighs the time spent dismissing false alarms.

Concepts & terms

Cascading setState

Calling setState for two or more state variables sequentially inside a single useEffect or event handler, causing multiple re-renders where one would suffice. Batching in React 18+ reduces but does not eliminate this in all cases.

Derived state

Storing a computed value in its own useState variable and updating it via useEffect whenever the source state changes. This wastes a render cycle; useMemo or a plain variable computed during render is usually correct.

Stale closure

A function inside useEffect that captures a variable from its surrounding scope at creation time, but the useEffect dependency array omits that variable, so the function never sees updated values on subsequent renders.

Agent Skills

A mechanism in AI coding agents (Claude Code, Cursor, etc.) that injects custom rules, conventions, or tool configurations into the agent's context, steering code generation toward specific practices without per-prompt instruction.

Source: juejin.cn ↗ Google Translate ↗ Backup ↗