核心分析¶

问题核心：判断是否采用 react-doctor 应基于项目技术栈、规模与对静态质量度量的需求。

适用场景（适合）¶

• 中大型 React 应用：拥有复杂 state/effect、多个团队协作、PR 流程，需要防止 hooks 误用与无效渲染。
• 跨平台项目：如 React Native 与 Web 的混合代码库，框架感知规则能降低跨平台误报。
• 需要量化健康度的团队：希望在 CI/PR 中用“0–100”评分追踪长期质量趋势。
• 使用或训练 coding agents 的团队：提供 npx react-doctor install 以把最佳实践灌输给代码生成代理。

不推荐的场景（不适合）¶

• 非 React 项目：工具规则针对 React 优化，对纯 Vue/Angular/后端项目帮助有限。
• 小型、一次性或实验性仓库：引入和维护配置的成本可能超过收益。
• 受限运行环境：无法在 CI 中运行 Node 的环境或不允许安装外部依赖的受限仓库。

实用建议¶

1. 在决定前用 npx -y react-doctor@latest . 做一次试跑，查看健康评分与主要违规规则的性质。
2. 评估团队是否能接受初期配置和忽略列表的维护成本：中大型项目通常收益更明显。

重要提示：如果你的主痛点是运行时错误或动态交互问题，别仅依赖静态工具——需结合测试与监控。

总结：react-doctor 最适用于需要静态语义治理的大型 React 代码库；对非 React 或受限环境则不宜作为主要工具。

核心分析¶

问题核心：将新静态检查工具引入现有流程时，噪音（第三方/生成文件误报与不当 suppression）是最大阻力。

技术分析¶

• 关键能力：
• react-doctor.config.json 提供 ignore.rules, ignore.files, 和 ignore.overrides 三层精细控制。
• 工具尊重 .gitignore, .eslintignore, .oxlintignore，并可合并现有 lint 配置（adoptExistingLintConfig）。
• 支持 GitHub Action，可在 PR 中发布注释并输出 score，用于可视化而非直接阻断。

实用建议（分步引入）¶

1. 合并现有配置：开启 adoptExistingLintConfig:true，让 react-doctor 折叠现有 ESLint 规则，避免重复报警。
2. 排除第三方/生成代码：在 ignore.files 中添加 src/generated/**、node_modules/** 或工具生成目录；对少数需要例外的文件使用 ignore.overrides。
3. 先展示后阻断：在 GitHub Action 中先发布 PR 注释（不 fail），以 warning 级别收敛团队反馈，然后逐步把关键规则设为 fail-on。
4. 使用增量扫描：在大型仓库启用 --diff 或 --staged，把 CI 时间与关注点限制在变更集。
5. 排查 suppress 问题：遇到抑制注释无效时使用 --explain 调试注释位置和规则作用域。

重要提示：切勿一次性在大仓库启用全部严格规则——先收敛，再逐步提升为最佳实践。

总结：通过合并现有 lint、精细化 ignore、先以警告方式在 PR 展示、并使用增量扫描，可以平滑引入 react-doctor 并最小化噪音。

核心分析¶

问题核心：死代码检测基于静态可达性分析，面对现代构建和动态加载模式时会存在固有盲区。

技术分析¶

• 准确场景：
• 显式未导出或未被任何模块引用的函数、变量、组件。
• 项目内部静态引用链可穷尽的模块/符号。
• 常见误判（False Positives）：
• 动态 import / 按需加载：通过字符串拼接或运行时计算路径的 import 无法被静态解析。
• 运行时注册/反射：框架或插件在运行时用约定或元数据注册组件（如某些路由/插件系统）。
• 依赖注入或服务定位器：符号仅在运行时被注入或通过反射调用。
• 测试/工具链引用：测试 runner 或构建插件在运行时引用某些文件导致其看似未使用。

降低误报的实用建议¶

1. 配置忽略：把生成代码或运行时注册目录加入 ignore.files（例如 src/generated/**、plugins/**）。
2. 显式导出/标注：对运行时引用的模块添加显式注释或导出，便于静态工具识别或手动排除。
3. use overrides：用 ignore.overrides 仅对少数文件放行特定规则，保留其他规则的检测。
4. 结合变更集检查：优先关注变更（--diff/--staged），把人工审查成本放在新引入或修改的代码上。

重要提示：把静态 dead-code 检测视为“高价值但非完美”的工具——能显著发现显式未使用代码，但需要配置以适应复杂运行时模式。

总结：对大多数静态场景，dead-code 检测可靠；对动态加载/运行时注册的情况，通过配置、显式标注与变更集优先策略可以有效降低误报。

核心分析¶

问题核心：把静态规则和 explain 能力直接注入给 coding agents，可在代码生成阶段预防反模式，并在生成后用工具自动审查与反馈，实现闭环改进。

技术分析¶

• 现成能力：npx react-doctor install 能把规则/指导注入到多种 agent；工具可通过 CLI/Action/ESLint 插件运行并提供 --explain 以解析触发原因。
• 集成路径：
• Pre-generation: 把 recommended 规则、禁止列表和典型反模式示例注入 agent 的 prompt/template，指导生成时避开常见错误。
• Post-generation: 在 agent 产出后立即运行 react-doctor（本地或 CI），收集诊断并把可修复项反馈回 agent，要求其按照建议调整代码。
• CI Gatekeeping: 对 agent 提交的 PR 使用 diff 扫描并在 PR 中发布评分与问题，作为质量门槛或可视化指标。

实用建议¶

1. 在 agent prompt 中加入简短规则摘要（例如“不在渲染中触发副作用”、“避免派生状态并解释何时使用 useMemo/useCallback”）。
2. 把 react-doctor install 纳入 agent 的初始化脚本，使其默认启用团队的规则集。
3. 使用 post-generation 钩子：自动运行 react-doctor 并把 explain 信息回传给 agent，以便 agent 基于具体错误调整生成策略。
4. 对 agent 产生的输出优先使用 --diff 模式，减少不必要的全量扫描开销。

重要提示：agents 需要能访问注入的规则并接受反馈循环；否则只能对生成后代码进行审查，难以在生成端彻底避免错误。

总结：通过预置规则提示 + 生成后自动扫描并反馈 + CI 中量化门槛的组合策略，可显著降低 coding agents 生成坏 React 代码的概率，并把最佳实践固化进自动化流程。