React Doctor Skill：专抓 AI 写出的烂 React 代码的静态扫描仪

React Doctor Skill：专抓 AI 写出的烂 React 代码的静态扫描仪

你的 Agent 写的 React 很烂——这个 Skill 就是来治它的。

React Doctor 是一个确定性（deterministic）的 React 代码静态扫描工具，专注于抓出 AI 编程助手（Claude Code、Cursor、Codex 等）在生成 React 代码时最常犯的错误。它覆盖五个维度：State & Effects、Performance、Architecture、Security、Accessibility，兼容所有主流 React 框架（Next.js、Vite、TanStack、React Native、Expo）。

功能与设计原则

React Doctor 的核心逻辑不是”静态分析规则堆砌”，而是一套针对 AI 生成代码特征的定向检测规则。AI 写 React 时有几类高频问题：滥用 array index 作为 key、在 useEffect 里乱用依赖、用 inline function 作为回调、遗漏 accessibility 属性、CSS-in-JS 内存泄漏等——这些问题传统 ESLint 规则覆盖不全，或规则之间互相冲突。

它的设计原则是：确定性 + 可配置 + 只报引入的问题。CI 模式下只报告当前分支 PR 新引入的问题，不翻旧账；规则可通过 doctor.config.ts 精细配置；支持 JSON ESLint / oxlint 配置继承。

认可度

• GitHub Stars：14,136（截至 2026-07-27）
• NPM 月下载：3,648,549 次（2026-06 月区间），是 Skill 圈里少见的 npm 下载量级
• 2026-07-27 仍在活跃更新（GitHub 事件脉冲显示持续提交）
• GitHub Topics: skill、claude-code、react

链接

GitHub：https://github.com/millionco/react-doctor
官网文档：https://react.doctor/docs
NPM：https://npmjs.com/package/react-doctor

原作者

millionco（GitHub Organization）——专注 AI Coding 工具链的开发者组织，目前主维护 react-doctor 与相关生态。

详细介绍

React Doctor 由 npm 包 @react-doctor/cli 驱动，安装即用，不需要复杂配置。项目根目录运行 npx react-doctor@latest 即可触发全面审计，输出结构化的问题报告。

Skill 安装方式：

npx react-doctor@latest install

此命令将 Skill 注入到 Claude Code / Cursor / Codex 等 AI 编程工具的 skills 目录，Agent 在生成代码时会主动参考规则避免重蹈覆辙。

CI 集成（一行命令接入 GitHub Actions）：

npx react-doctor@latest ci install

自动添加 workflow 文件，每次 PR 触发扫描并在评论里摘要本次变更引入的问题，而非扫描整个代码库。

覆盖的检测维度：
– State & Effects：useEffect 依赖遗漏、stale closure、用 setState 的函数式形式混用
– Performance：不必要的 re-render、memo 缺失、inline object/array 作为 props
– Architecture：组件职责膨胀、prop drilling、逻辑与视图混杂
– Security：dangerouslySetInnerHTML 误用、用户输入未转义、敏感数据暴露
– Accessibility：aria 属性缺失、img 缺少 alt、键盘导航阻断

特点

• 零配置开箱即用：不写 doctor.config.ts 也能跑，规则开箱即启
• AI Agent 专用 Skill：内置”教 Agent 学规则”的 Skill 文件，安装后 Agent 会主动规避同类错误
• PR 增量扫描：CI 模式只报新引入的问题，不翻历史旧账，降低修复心理负担
• 全框架覆盖：Next.js / Vite / TanStack / React Native / Expo 无需额外适配器
• 可配置规则深度：doctor.config.ts 支持按需开启/关闭规则、调整检测严格度

使用方法

快速审计（本地）：

npx react-doctor@latest

安装为 Agent Skill：

npx react-doctor@latest install
# 然后在 Agent 对话里描述任务，Agent 会自动参考规则

接入 GitHub Actions：

npx react-doctor@latest ci install

查看 CI 配置选项：

react-doctor ci config   # 调整扫描范围、评论格式、gate 阈值
react-doctor ci upgrade  # 升级 workflow 版本

退出遥测（隐私优先）：

npx react-doctor@latest --no-telemetry

使用场景与目标人群

适用场景：
– 团队引入 AI 编程工具后，React 代码质量下滑需要系统性治理
– Code Review 资源有限，需要自动化扫描兜底
– AI Agent（Claude Code / Cursor）需要自我纠错能力
– 大型 React 项目接入 CI，防止低质量代码合并进 main 分支

目标用户：
– 前端开发团队（尤其是使用 Next.js / Vite 的全栈团队）
– AI Coding 重度用户（Claude Code、Cursor 用户）
– Tech Lead / 代码质量负责人

输入与输出案例

输入：
一个 Claude Code Agent 在编写用户列表组件时使用了 array index 作为 React list 的 key：

{data.map((item, index) => (
  <ListItem key={index} data={item} />
))}

输出：
运行 npx react-doctor@latest 后输出：

[react-doctor/no-array-index-as-key]
避免用数组索引作为 key。当列表重新排序或过滤时，
索引作为 key 会导致组件状态错乱。
位置: src/components/ListItem.tsx:6
建议: 用 item.id 或其他唯一标识替换 key={index}

输入（Skill 模式）：
在 Claude Code 里执行任务：”实现一个带筛选功能的用户列表组件”

Skill 介入行为：
Agent 在生成代码前参考 react-doctor Skill 规则，直接用 item.id 作为 key，避免生成后被 react-doctor 扫描报错再返工。

GitHub：https://github.com/millionco/react-doctor

GitHub: https://github.com/millionco/react-doctor