React Doctor Agent Skill 实战指南改动后回归检查、/doctor 全量分诊流程与规则调优【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor本文基于仓库中的 Agent 技能定义文件 skills/react-doctor/SKILL.md 及其配套参考 skills/react-doctor/references/explain.md 展开系统讲解这套 Skill 如何教编码 AgentClaude Code、Cursor、Codex 等在修改 React 代码后执行回归检查、发起全量清理、做 UI 设计审计与运行时性能扫描以及理解、调优规则的正确方式。读完后你可以把这套工作流直接接入自己的编码 Agent并掌握rules系列子命令背后真实的配置编辑机制。一、Skill 是什么元数据与触发时机SKILL.md是一个标准的 Agent Skill 文件YAML frontmatter 声明了技能名、版本1.2.0和一段description正文则是给 Agent 看的操作手册。frontmatter 中的description定义了技能被触发的时机原文要点是完成一个功能、修复一个 bug、提交 React 代码之前用户输入/doctor或要求扫描scan、分诊triage、清理clean upReact 诊断覆盖面包括 lint、可访问性、包体积与架构并且内置了回归检查与一套可拉取「权威 playbook」的完整本地分诊工作流。技能的定位一句话概括扫描 React 代码库中的安全、性能、正确性与架构问题输出 0–100 的健康分。正文按「什么场景执行什么命令」组织下面逐场景还原并结合仓库源码核对每个命令的真实实现。二、改动后回归检查--scope changed这是 Skill 中最核心的一条规则——每次改完 React 代码之后都执行npx react-doctorlatest --verbose --scope changed然后确认健康分没有下降。如果分数掉了必须在提交之前修掉引入的回归。参数语义来自 SKILL.md 的 Command 表Flag作用.扫描当前目录--verbose按规则展示受影响文件与行号--scope changed只报告相对 base 分支新引入的问题默认是 full--scope lines只报告落在改动行上的问题--score只输出数字分数design只运行聚焦的 UI 设计类诊断--scope changed的关键价值在于区分「存量债务」与「本次改动引入的新问题」CI 场景下 React Doctor 正是这样做到「只报告你的 PR 引入的问题而不是你已有的 backlog」见 README.md。从源码结构看scan命令的入口在 runScanCommand当带显式文件路径时会先做参数校验并直接走inspectAction否则解析 TUI 环境、执行项目迁移runProjectMigrations、通过resolveScanTarget解析扫描目标与用户配置最后交给 Ink TUI 的runScanApp运行——这说明「交互终端 非交互CI/Agent」两种形态共用同一套底层inspect管线Skill 中给 Agent 的命令行在两个环境下行为一致。三、全量清理按严重度分级修复对于一般的代码清理或质量改进Skill 给出的命令是默认作用域npx react-doctorlatest --verbose默认--scope full扫描整个代码库修复顺序有明确优先级先 errors后 warnings。这一条对 Agent 特别重要——它把「一次扫出一百条诊断」的大输出约束成了可执行的优先级队列避免 Agent 平铺直叙地批量修改。四、UI 设计审计design子命令当需求是「审计 UI 设计」而非「检查代码健康」时npx react-doctorlatest design --verbosedesign只会选中带 design 标签的规则覆盖 UI 组合composition、排版typography、交互interaction、可访问性与动效motion并且包含在普通健康扫描中保持 opt-in 的聚焦规则——也就是说设计审计是比默认全量扫描更广、更聚焦的规则子集。源码印证designAction 的实现非常薄它只是在原有 flags 上叠加design: true并默认lint: true后委托给inspectAction。这意味着design不是一个独立的扫描引擎而是对同一inspect管线的一次「规则面收窄」与 SKILL.md 描述的「selects only design-tagged ... rules」完全对应。五、运行时性能问题scan url录制 DevTools 轨迹当用户抱怨的是「运行时慢」而不是静态代码问题时SKILL.md 给出了专门的录制流程前提是交互式终端npx react-doctorlatest scan url --format json执行时 React Doctor 会打开一个隔离的系统 Chrome 临时 profile不打扰用户已打开的普通浏览器在用户手动复现慢交互的过程中录制 DevTools 性能轨迹随着 React 渲染用紫色描边 组件名高亮正在渲染的组件用户按Enter停止录制Agent 应先读结构化摘要再去检查返回的本地.json.gz轨迹文件从中提取 CPU、浏览器层与 React 组件层的证据。需要用户已登录的浏览器状态时改用--cdp remote-debugging-url这要求 Chrome 已经以远程调试方式在跑。SKILL.md 对此有明确的安全边界值得原样记给 Agent绝不索要 cookie绝不复制用户的浏览器 profile轨迹文件视为敏感的本地应用数据README 补充说明它可能包含页面 URL、源码路径与 React profiling 细节未经明确许可绝不上传。README.md 中还补充了两个运行细节可供实操参考交互式终端下可以react-doctor scan不带 URL 直接选一个检测到的 localhost 应用而编码 Agent 与 CI 必须显式传 URL由于 Chrome 性能追踪是浏览器级别的--cdp挂载的 profile 若还有打开的页面会被拒绝工具会先关掉空白启动页、结束后关闭自己的扫描页签但保留挂载浏览器本身。六、/doctor完整本地分诊工作流当用户输入/doctor、说 run react doctor、或要求一次完整分诊/清理而不只是回归检查时SKILL.md 规定的动作是拉取权威 playbook并严格执行其中每一步curl --fail --silent --show-error \ --header Cache-Control: no-cache \ https://www.react.doctor/prompts/react-doctor-agent.md这个设计有三个要点Playbook 是唯一事实来源single source of truth它是一个 scan → filter → triage → fix → validate 的循环直接编辑工作树working tree且明确约定「永不 commit、永不开 PR」——提交决策始终留给用户。更新即生效在源头更新 prompt 后所有 Agent 下一次 fetch 就拿到新流程无需重装 Skill。--header Cache-Control: no-cache正是为了保证每次拿到最新版。按规则取修复配方playbook 执行到具体修复时会在内部按需拉取每条规则的权威配方https://www.react.doctor/prompts/rules/plugin/rule.md让每次修复都使用「reviewer 测试过的标准 recipe」而不是 Agent 自己临场发挥。这种「Skill 本体只是路由 安全边界具体步骤远程可更新」的模式让团队可以把修复经验持续沉淀到 playbook 与 per-rule recipe 中而客户端 Skill 保持极小。七、规则的解释与调优rules子命令与最小控制面当用户想理解某条规则、对某条规则有意见、或者想调整哪些规则参与运行时注意这不是修代码修代码走主 Skill //doctorSKILL.md 指路到 references/explain.md。其工作流是五步从诊断中确定规则 key如react-doctor/no-array-index-as-key先解释再改动npx react-doctorlatest rules explain react-doctor/no-array-index-as-key选择与用户意图匹配的最窄控制见下面的决策指南用rules子命令应用——它会就地编辑你的doctor.config.*或package.json#reactDoctor保留其他字段与格式验证改动生效npx react-doctorlatest --verbose --diff完整的命令面npx react-doctorlatest rules list # 所有规则 当前生效严重度 npx react-doctorlatest rules list --configured # 只看你的配置改过的 npx react-doctorlatest rules list --category Performance # 按类别过滤 npx react-doctorlatest rules explain rule # 为什么重要 如何配置 npx react-doctorlatest rules disable rule # 规则永不运行 npx react-doctorlatest rules enable rule # 按推荐严重度重新开启 npx react-doctorlatest rules set rule warn # off | warn | error npx react-doctorlatest rules category React Native off # 整类规则 npx react-doctorlatest rules ignore-tag design # 跳过一族规则design、test-noise 等 npx react-doctorlatest rules unignore-tag design规则引用支持三种写法完整 keyreact-doctor/no-danger、裸 idno-danger、legacy keyreact/no-danger。决策指南把控制面匹配到意图explain.md 给出的意图 → 控制映射原则是选最窄的那个用户意图推荐控制不同意某条规则 / 对我是误报rules disable rule设rules.key off全局停跑这是「我不想要这条规则」的默认选择规则没问题但严重度不对rules set rule warn或error想开启一条默认关闭的规则rules enable rule整个领域不想要如全部 React Native 规则rules category Category off某一行为族太吵design、test-noise、migration-hintrules ignore-tag tag规则要保留只想隐藏出 PR 评论 / 分数 / CI 门禁不要 disable改配置里的surfacessurfaces.prComment.excludeRules、surfaces.score.excludeTags、surfaces.ciFailure.excludeCategories本地cli输出仍会显示把 test/story 文件的问题重新计入生产健康分设surfaces.score.includeFileContexts或surfaces.ciFailure.includeFileContexts为[test]、[story]或两者三层控制的组合语义务必理解ignore.tags在linting 之前就禁用所有带该 tag 的规则因此一条被 tag 忽略的规则即使rules/categories把它设为warn/error也保持关闭——规则级覆盖无法重新打开 tag-ignored 规则对未被 tag 禁用的规则rules覆盖categoriescategories覆盖规则默认值surfaces只影响可见性哪个出口展示/计入门禁永远不改变规则是否运行。配置的落盘方式配置存放在doctor.config.ts也支持.js/.mjs/.cjs/.json/.jsonc或package.json的reactDoctor键。rules子命令编辑「哪一个存在就哪一个」TS/JS 编辑通过 magicast 保留原格式若一个都没有则创建doctor.config.json并打上$schema。最小示例// doctor.config.ts export default { rules: { react-doctor/no-array-index-as-key: off }, categories: { React Native: warn }, ignore: { tags: [design] }, };源码层面可以核对这些行为的实现rules.ts 中SEVERITY_VALUES硬编码了[off, warn, error]三个合法取值rules set传其他值会报Invalid severityresolveProjectRoot会向上找最近的 package 目录作为项目根applyConfigChange统一走「解析配置目标 → 变换配置 →writeRuleConfig写回」的管线而reportManualEdit处理了一个边界情况——如果用户配置是动态模块如export default () ({...})无法静态编辑CLI 会打印出建议的 JSON 片段让用户手工应用而不是盲目改写。最后 explain.md 还规定了一个「教育用户」的礼仪解释规则时先用rules explain输出的 Why it matters用户要深入时再给 per-rule recipe只有用户理解之后才提议 disable——因为很多「碍事」的规则其实抓到了真实问题。八、Skill 如何装进 Agentnpx react-doctorlatest installSKILL.md 本身存放在仓库的skills/react-doctor/目录用户侧通过一条命令安装到本地 Agent 环境README 说明支持 Claude Code、Cursor、Codex、OpenCode 等npx react-doctorlatest install从 install-react-doctor.ts 的源码结构看安装流程比「复制一个 Skill 文件」要完整得多它依赖agent-install包getSkillAgentConfig、installSkillsFromSource、SKILL_MANIFEST_FILE按 Agent 类型放置技能清单内置detectAvailableAgents/computeDefaultSelectedAgents检测本机可用的编码 Agent 并记住用户偏好install-agents-preference.ts同时提供可选的git-hook支持 ghooks、simple-git-hooks、lephook、pre-commit 等一整族 git hook 方案见GitHookKind枚举与 GitHub Actions 工作流安装还会根据 lockfilepnpm / yarn / bun / npm识别包管理器并在需要时写入 doctor 脚本。也就是说仓库中这份 SKILL.md 是「发行源」install命令负责把它分发到各 Agent 的技能目录如.agents/skills/一类约定路径并配好提交前钩子。九、快速对照表场景命令依据改完 React 代码回归检查npx react-doctorlatest --verbose --scope changedSKILL.md「After making React code changes」全量清理npx react-doctorlatest --verbose默认 fullerrors 先于 warningsSKILL.md「For general cleanup」UI 设计审计npx react-doctorlatest design --verbosedesign.ts运行时性能npx react-doctorlatest scan url --format json登录态用--cdpSKILL.md README「Runtime performance traces」完整分诊fetch react-doctor-agent.md playbook严格执行 scan → filter → triage → fix → validateSKILL.md「/doctor」理解/调整规则rules explain→rules disable\|set\|enable\|category\|ignore-tag→--verbose --diff验证explain.md装进编码 Agentnpx react-doctorlatest installinstall-react-doctor.ts十、小结这份 Skill 的设计可以归纳为三层固定命令面回归检查、全量扫描、design、runtime scan全部可由 Agent 直接执行、远程可更新的流程面/doctorplaybook 与 per-rule recipe更新即全网生效、保守的配置面先解释、后调优控制面从窄到宽依次为规则级 → 类别级 → tag 级 → surfaces 可见性级。源码中的scan/design/rules命令实现与 SKILL.md 的描述一一对应说明文档与实现保持同步维护把这套 Skill 安装进编码 Agent 之后Agent 在「提交前回归检查」与「深度清理」两种模式下都会遵循与人类工程师相同的操作纪律。【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考