在 Agent 编程工作流中，Claude Code、Cursor、Windsurf 等工具生成的 React 代码往往存在高度相似的缺陷模式：hook 依赖数组遗漏、状态派生错误、barrel import 导致打包膨胀等。这些问题不是语法错误，不会导致编译失败，但会在运行时制造难以追踪的性能与正确性隐患。react-doctor 的设计目标正是填补这一空白 —— 在 CI 流水线中以量化的 0–100 健康度评分替代人工 Code Review 中的模糊判断，并为编码助手提供内置的学习素材，使其从源头减少这类问题的产生。
健康度评分的计算逻辑与工程含义
react-doctor 的评分体系建立在一个核心原则之上：评分惩罚的是受触发的规则种类数，而非规则触发的总次数。这一设计有重要的工程含义。假设某个文件中存在 50 处 no-barrel-import 违规，当修复了其中 49 处后，评分不会因此改善 —— 只有将所有 50 处全部修复，才会移除该规则带来的 0.75 分惩罚。这个设计避免了评分被大量同质化问题稀释，使得评分变化直接反映代码库整体质量的结构性改善。
具体的计算公式为：100 - (unique_error_rules × 1.5) - (unique_warning_rules × 0.75)。error 级别规则的成本是 warning 的两倍，这意味着在阈值判定时应当重点关注 error 级规则的数量。例如，一个代码库触发了 3 个 error 规则和 10 个 warning 规则，其最终得分为 100 - 4.5 - 7.5 = 88。react-doctor 官方定义的评分区间为：75 分以上为 Great，50–74 分为 Needs work，50 分以下为 Critical。
需要特别注意的是，评分可能随工具版本升级而下降。这是因为 react-doctor 会持续增加新规则，而新规则在既有代码库中触发会带来额外的分数惩罚。这不是代码质量退化的信号，而是工具能力增强的结果。如果需要跨版本保持评分稳定，应当在 CI 配置中锁定具体版本号，如 react-doctor@2.3.1，而非使用 @latest。
三层忽略配置体系的工程实践
react-doctor 提供了细粒度的规则忽略机制，通过 react-doctor.config.json 中的三个嵌套键实现从粗到精的覆盖控制。这三个配置项的选型直接影响扫描结果的有效性与可维护性。
ignore.rules 是最粗粒度的选项，直接在全局范围内禁用指定规则。适用场景是某条规则与项目实际需求存在系统性冲突，且这种冲突不是单文件级别而是整个代码库的共性问题。例如，如果项目中有意使用 react/no-danger 来处理经过严格审查的富文本渲染，可以将这条规则加入全局忽略列表。这种方式简单直接，但代价是失去对该规则在整个代码库中的监控能力。
ignore.files 提供文件级别的全规则忽略，适用于生成的代码或第三方依赖中的问题。例如 src/generated/** 目录下的代码通常不应纳入扫描范围。此选项应当谨慎使用，因为对某个文件的完全忽略意味着该文件中所有规则都被屏蔽，包括后续新增的规则。如果只是希望忽略特定规则在特定文件中的触发，应当使用 ignore.overrides。
ignore.overrides 是最精细的控制层，允许对指定文件或 glob 模式禁用特定规则组合，同时保持其他规则对该文件的监控能力。以 components/modules/diff/** 为例，如果该目录下的组件确实需要使用数组索引作为 key（如 Diff 算法中的无重复场景），可以配置 overrides 使其免于 no-array-index-as-key 规则，但仍然受到 no-render-in-render 等其他规则的约束。这种配置方式保留了扫描覆盖率，同时为合理的例外情况提供了表达空间。
配置项还支持 package.json 中的 reactDoctor 键，当配置文件与 package.json 存在重复键时，CLI 参数具有最高优先级，配置文件次之，package.json 最低。这一优先级设计使得开发者在本地调试时可以快速通过 CLI 参数覆盖配置，而 CI 环境中的标准化配置不会被本地临时改动影响。
Agent 集成的两种工作模式
react-doctor 对编码助手的支持分为被动检测与主动预防两个层面。
被动检测体现在工具对 50 余种编码助手的自动识别。当扫描过程中检测到文件由特定 Agent 生成，工具会记录这一元数据但不改变扫描行为。这一信息在 --json 输出中可见，便于团队分析哪些代码质量问题与特定工具的使用模式相关联。
主动预防通过 npx react-doctor@latest install 命令实现。该命令会提示用户选择目标 Agent 类型，随后在项目中写入对应的规则文件：Claude Code 对应 AGENTS.md 和 CLAUDE.md，Cursor 对应 .cursorrules，其他工具对应 SKILL.md。这些文件包含 React 开发的最佳实践说明与项目特定的代码规范，编码助手在后续的生成任务中会参考这些文件的内容。--yes 参数可以跳过交互式提示，适用于自动化脚本或初始项目搭建流程。
这一设计的工程价值在于将代码质量控制从被动的事后检测前移到主动的事前干预。通过让编码助手在生成代码时就知道项目的规范约束，可以从根本上减少同类问题的产生，而不是依赖 CI 流水线反复捕获相同类型的缺陷。
CI/CD 接入的关键参数
在持续集成环境中接入 react-doctor 需要关注几个核心参数。
--fail-on 参数控制何时以非零退出码终止流水线。可选值为 error（默认）、warning 和 none。在初次引入 react-doctor 的项目中，建议设置为 warning 以避免阻断现有流程，同时积累基线数据。当团队处理完已知问题后，可逐步收紧至 error 级别。none 模式适用于仅需收集数据但不阻断发布的场景。
--diff [base] 与 --staged 提供增量扫描能力。前者对比指定分支的变更，后者仅扫描暂存区的文件。这两种模式都自动禁用死代码检测，因为 knip 的死代码分析依赖完整的项目图谱。增量扫描显著缩短了单次检查的耗时，适合高频提交场景。但需要注意，如果修改涉及依赖关系的变更（如删除某个被广泛使用的工具函数），增量扫描的死代码检测盲区可能导致误报。
--annotations 参数将诊断结果输出为 GitHub Actions 的 ::error 和 ::warning 格式，实现与原生 lint 注解一致的视觉呈现。结合 github-token 参数（仅在 pull_request 事件中需要），诊断结果会自动作为 PR 评论发布并持续更新，避免重复堆叠。
对于需要程序化处理扫描结果的场景，--json 输出结构化报告，--score 仅输出数字评分。Node.js API 提供了更底层的 diagnose 函数，允许在脚本中直接调用分析逻辑并访问 result.score 和 result.diagnostics 对象，实现自定义的监控仪表盘或与项目内部质量系统的集成。
评分体系在团队协作中的应用策略
在实际团队环境中，react-doctor 的评分可以承担多种角色。从质量门禁角度，可以设置 PR 合入前必须达到的最低分数阈值，例如要求所有新增代码所在的文件评分不低于 70 分。从趋势监控角度，可以在团队内部维护评分的历史曲线，识别代码库整体质量随时间的演变。从开发者反馈角度，评分本身可以成为编码助手性能评估的量化指标之一，帮助团队了解不同工具在不同代码场景下的表现差异。
值得注意的是，react-doctor 在 CI 环境中自动启用离线评分模式，跳过与评分 API 的网络通信。这确保了 CI 流水线的确定性，同时也保护了代码隐私 —— 扫描结果不会上传至外部服务。如果需要强制离线模式，可以在配置文件中设置 "offline": true。
资料来源：GitHub millionco/react-doctor 仓库，https://github.com/millionco/react-doctor
内容声明：本文无广告投放、无付费植入。
如有事实性问题，欢迎发送勘误至 i@hotdrydog.com。