让 AI 写的 React 不再烂

5 月 12 日到 13 日两天，一款叫 React Doctor 的开源工具单日涨了 804 星，登顶 GitHub Trending TypeScript 日榜。总 star 数 8679，2026 年 2 月才出生，三个月就长到了这个体量。

它做的事情很具体——给 50+ coding agent 一键注入「React 写法规矩」，扫代码时给出一个 0-100 的单一健康分。

这件事对国内每天用 Trae、通义灵码、豆包 Coder、千问 Code、文心快码、CodeBuddy 的开发者来说，是个明确信号：AI Coding 工具链开始进入「写完还要被打分」的下半场。

打开仓库 README 第一句话很直接：「Your agent writes bad React, this catches it.」一句话定调子——它默认你已经在用 AI 写 React 代码，工具的角色不是替代 AI 写代码，而是给 AI 立规矩 + 给 AI 写出来的东西打分。

昨天（5 月 12 日）我们刚拆过 James Shore 那篇关于 AI Coding 维护成本反比的长文，那是一篇方法论级别的判断框架——给行业递了一把尺子。今天这件事是那把尺子的第一个落地工具。一个是哲学，一个是落地，前后是连着的。

它在做什么：6 类诊断 + 健康分

打开 README，6 个诊断类目摆得很清楚：state & effects、performance、architecture、security、accessibility、dead code。

每类下面是十几条到二十条具体规则，加起来 70 多条 React 专项规则。

底层引擎是 oxlint，一款 Rust 写的 ESLint 兼容 linter，2025 年下半年跑得很快。React Doctor 把规则封装成 oxlint plugin 与 ESLint plugin 双形态，可以直接和你项目里已有的 .eslintrc 合并。

每一类对应一种 AI 写 React 代码最容易翻车的倾向：

• • State & Effects：useEffect 滥用、派生 state 反模式、fetch-in-effect；
• • Performance：内联函数重渲、数组索引当 key；
• • Architecture：桶式 barrel 导入、组件层级错位；
• • Security：dangerouslySetInnerHTML 滥用；
• • Accessibility：缺 alt、ARIA 错配；
• • Dead Code：未导入文件、未引用变量。

把 6 类放在一起看会发现一个共性：每一类都对应 AI 写 React 代码时最容易翻车的某一种倾向。

LLM 训练数据里有大量旧版 React 用法，缺少 useEffect 与「派生 state 反模式」相关的 React 19 时代新约定。React Doctor 在 State & Effects 这一类里收录了 no-fetch-in-effect、no-derived-state-effect、no-cascading-set-state，每条都对应一种常见 AI 误用。

barrel 导入这条特别值得一提。AI 写代码经常在 index.ts 里大量重导出，结果是 tree shaking 失效、构建体积膨胀。这种问题以前要靠人工 review 才能发现，React Doctor 把它自动化了。

值得多说一句的是规则集与框架版本的对应关系。React Doctor 会自动识别 React 19、React 18、React 17 的版本差异，对 React Compiler 启用一组额外规则——React 18 项目里这些规则不触发。「按版本启用」对国内同时维护多套 React 项目的团队特别友好。

健康分 73/100 是怎么算的

公式很简洁：

Health Score = 100 − (unique_error_rules × 1.5) − (unique_warning_rules × 0.75)

注意「unique」两个字——计数对象是「触发了几种不同的规则」，不是「触发了几次」。

同一条 no-barrel-import 规则在你代码里触发 49 次还是 50 次，扣分一样。

这个设计是有意为之，鼓励把一类问题彻底解决，而不是零散修补。

得分对应三档：

• • 75 分以上：Great，可以放心交付；
• • 50-74 分：Needs work，可以上线但需要安排维护时间；
• • 50 分以下：Critical，代码积累的规则违例种类已经多到需要专门治理。

需要诚实指出的是，这套打分公式本身是简化的。它假设 error 严重程度 = 1.5 × warning，并且假设所有规则的扣分权重相同。真实世界里安全类规则触发的危害远大于 a11y 类规则，但公式没体现这一点。

React Doctor 团队在 README 里也承认这一点，说健康分是「方向性指标」，不是精确度量。这种诚实态度反而让工具更可信——它不假装自己是万能的，它只在「比起没分数」这个 baseline 上往前走了一步。

健康分还有一个特性需要留意——版本升级时分数可能下降。每次 release 会新增规则，新规则在你代码里如果有违例就会扣分。生产 CI 里建议把 react-doctor pin 到具体版本，本地开发与每月人工扫描用最新版接收新规则。

国内开发者用这个工具的实操路径很直接：每周扫一次主仓库，把健康分曲线画出来。连续三周下降，回头查最近合并的 PR 引入了什么。

一行命令两种用法

扫：

npx -y react-doctor@latest .

一行下去，工具自动识别项目类型（Next.js / Vite / React Native）、识别 React 版本、识别已有 lint 配置，然后跑 6 类规则扫描，输出健康分。

装：

npx -y react-doctor@latest install

这条命令是 React Doctor 真正区别于普通 lint 工具的地方。

它检测项目根目录已配置的 coding agent，然后给检测到的 agent 各自写一份对应的规则文件。

普通 lint 工具是写完代码才告诉你哪里错了，React Doctor 是在 agent 写代码之前先把规则塞进 agent 的 system prompt 等价物里。

一个被注入了 React Doctor 规则的 Claude Code，在生成 useEffect 时会主动避开 no-fetch-in-effect——这是质的不同。

50+ agent 怎么覆盖

海外主力有 Claude Code、Cursor、Codex CLI、OpenCode、Aider、Cline、Roo Code、Kilo Code、Windsurf、Continue.dev、GitHub Copilot Chat 等。

每个 agent 写入文件路径不同：

• • Claude Code → CLAUDE.md
• • Cursor → .cursorrules
• • Codex CLI → AGENTS.md
• • OpenCode → SKILL.md
• • Aider → CONVENTIONS.md

install 命令的核心价值就是屏蔽这些路径差异——开发者不需要记 6 种规则文件位置，一条命令各自处理好。

国产 agent 的兼容情况怎么样？

React Doctor 没有官方声明支持，但国产工具中大多数已经具备「agent 规则文件」机制：Trae、通义灵码、千问 Code、CodeBuddy 都支持 AGENTS.md，豆包 Coder 与文心快码 Pro 版提供企业规则集机制。

意味着把 React Doctor install 生成的 AGENTS.md 同步到国产工具的对应位置，是可以工作的。

这条路径目前还没人系统验证过，但从公开文档判断兼容性是足够的。这也是这一周值得动手做的一件事——选一个用得最重的国产工具，把 React Doctor 生成的规则文件塞进去，看 agent 写代码的风格是不是有可观察的变化。

国内同类工具现状

把这张表放在一起看会发现三件事。

第一，国内工具在 agent 规则注入这条基建上已经齐了。一年前还没有 agent 规则文件机制，现在六款主流工具都有。

第二，国内工具普遍只提供通用 React 提示，没有专项规则集。Trae、通义灵码、豆包 Coder、千问 Code、文心快码、CodeBuddy 的 React 支持都还停在「能识别 React 项目、能写 React 代码」的阶段。

第三，PR 自动评分这条全空白。国内工具里没有任何一款提供端到端的 PR 健康分输出。

这是国产工具未来半年的明确空间。

而且国内工具的差异化方向不在「跟随 React Doctor」，而在「做更广的规则集」。React Doctor 只覆盖 React，国内项目栈里 Vue / 小程序 / Taro / uni-app 占比都不低。一款国产工具如果能做出 Vue Doctor、小程序 Doctor、Taro Doctor，市场空间反而比单纯模仿 React Doctor 大。

国内开发者这周值得做的三件事

第一件，抽两小时，给自己负责的 React 项目跑一次 React Doctor，看 baseline 健康分多少。一行命令的事。

第二件，本月内试一次，把 React Doctor install 生成的 AGENTS.md 同步到国产工具（Trae / 通义灵码 / CodeBuddy 任选一款），观察 agent 写代码风格是否有可见变化。

第三件，季度内推动一次，团队层面把 React Doctor CI 接入主仓库，把健康分作为 PR 合并的硬指标之一。

第三件最重要——它把工程质量从「靠人盯」转向「靠工具盯」，是国内一线团队下一阶段卷质量必然要走的路。

具体怎么接？流程其实不复杂。

跑 npx -y react-doctor@latest . 拿到当前 baseline 健康分。这是团队当前的真实水平。

加 --verbose 重跑，看 6 类问题分布。重点不是总分，而是哪一类拉低分数最多。

跑 npx -y react-doctor@latest install --yes，让工具自动给检测到的 agent 写规则文件。生成的文件务必 commit 进仓库，让所有团队成员同一份规则。

接 CI 用一段 yaml：

- uses: millionco/react-doctor@main  with:    diff: main    github-token: ${{ secrets.GITHUB_TOKEN }}    fail-on: error

PR 自动评分 + 自动评论，这一步比单纯本地扫描重要得多。它把健康分变成一个团队级别的可见信号。

最后设一条「不允许低于」的硬线。比较稳妥的做法是当前 baseline 减 3 分。比如 baseline 73，硬线设 70。这样团队可以容忍小幅波动，但任何让健康分跌破 70 的 PR 都得在合并前修好。

整个流程跑起来初期工作量不大——首次接入约 1-2 小时，后续每月 review 30 分钟。这是工程基建里 ROI 最高的一档投入之一。

行业进入「写完还要被打分」的成熟期

React Doctor 三个月长出 8679 星、单日 +804 这件事，意味着 AI Coding 工具链开始往专科化、可量化、agent 友好三个方向同时走。

三个方向叠在一起，就是「写完还要被打分」的工程文化。

ESLint 出现 14 年，jsx-a11y 出现 10 年，过去这两件事都没在前端社区普及。React Doctor 这种「专项规则 + 健康分 + agent 注入」三合一的形态，是把过去散落在三种工具里的能力打成一个包——开发者按一次就用得起来。

对国内开发者，这是个好消息。国内工具的 agent 规则注入基建已经齐了，剩下的是「在 agent 规则文件层之上做专项规则集 + 健康分」这一层。这条路径上海外只走在了前面半步，国内厂商完全能跟上——尤其是 Vue / 小程序 / Taro / uni-app 这些本地化技术栈，海外开源社区不会主动覆盖，是国产工具一片明确的空地。

国内开源生态在这件事上其实有自己的优势。React Doctor 只覆盖 React，国内项目栈里 Vue / 小程序 / Taro / uni-app 占比都不低，这部分海外开源社区不会主动覆盖。国产开源团队完全有能力做出本地化规则集——技术栈一样可分析、agent 注入路径已经齐了、CI 集成方式也很成熟。这是一片明确的、海外不会进的空地。

5 月 12 日 James Shore 那篇维护成本框架文章给行业递了一把尺子，5 月 13 日 React Doctor 8679 星的爆发给了那把尺子的第一个落地工具。两件事连起来看就是一句话——AI Coding 工具链进入「写完还要被打分」的成熟期，国内开发者站在和海外同行同样的起点上，没必要焦虑，但值得动手。

看见，然后动手，然后变好。