React Doctor 的 Agent 贡献指南CLAUDE.md 与 AGENTS.md 如何编码 Effect v4 工作流与发布纪律【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctorReact Doctor 是一个以「AI Agent 协作」为第一设计目标的 monorepo仓库根目录的 CLAUDE.md 只有寥寥 4 行但它通过AGENTS.md引入指令把全部贡献规范收敛到 AGENTS.md约 437 行中。读完本篇你将掌握这套 Agent 指南的完整骨架——通用代码规约、truffler 符号去重流程、五包结构布局、Effect v4 的导入/错误/服务/Layer 惯用法、双后端遥测架构以及 Changesets 发布授权与 GitHub Action 独立版本化的操作细节。CLAUDE.md四行入口与 AGENTS.md 引入CLAUDE.md 的全文只有两条信息一句指向贡献指南的自然语言说明约定、包布局、规则管线、发布步骤见 AGENTS.md以及一行AGENTS.md引入指令。后者是 Claude Code 的文件引入语法——Agent 启动时会自动把 AGENTS.md 的全文载入上下文。这种「入口文件极薄、规范文件单一」的结构是有意的无论贡献者使用 Claude Code 还是其他读取 AGENTS.md 的 Agent 工具规范都只维护一份。下面的内容均以该指南为骨架并以仓库源码作为实现层面的佐证。通用代码规约General RulesAGENTS.md 的第一节是一组 MUST 级硬规约核心要点如下包管理命令使用antfu/nini安装、nr script运行、nun卸载类型风格TypeScript interface 优先于 type 别名所有类型放在全局作用域函数风格箭头函数优先于 function 声明参数超过一个时改为单个对象参数如Files.readLines({ filePath, rootDirectory })命名文件用 kebab-case变量名必须描述行为且拒绝一两个字母的缩写例如.map()里用innerX而不是x用didPositionChange而不是moved并要求「频繁地重新评估、重命名变量使其更精确」注释默认不写注释确属 hack 的代码如setTimeout或易误解逻辑必须以// HACK: 原因开头魔法数字一律收进constants.ts使用带单位后缀的SCREAMING_SNAKE_CASE如_MS、_PX工具函数小而专注的 utility 放utils/一个 utility 一个文件禁用不必要的as类型断言、!!取布尔值用Boolean、重复代码。其中两条与「公共面public surface」和「去重」直接相关product-thinking 关卡在新增或修改 CLI 标志/命令、评分、配置、JSON 报告、包 API、GitHub Action、网站或终端输出之前必须先跑.agents/skills/product-thinking/定义的流程——命名用户的 job、先复用再新增、接入一个遥测指标、补齐兼容产物、设定 kill metric。Lint 规则则走独立的规则管线。对应技能文件见 .agents/skills/product-thinking/SKILL.mdtruffler 符号搜索新增 utility/helper/type/常量/规则之前和任务结束之后都要用 truffler 搜一遍现有符号捕获重复与死代码见下节。符号搜索与去重trufflerrayhanadev/trufflerdev dependency是基于oxc-parser的模糊 JS/TS 符号搜索工具根目录 package.json 中固定了^0.4.2版本。指南给出的短流程是两段式规划/定范围时从行为推导若干查询词提议名 领域名词 动词先搜最窄的根读完 top matches 再动手——这是「不重复造轮子」加utils/一文件一工具约定的落地手段完成任务后重新搜索你新增的符号确认没有重复已有 helper并删除被你改动取代的代码。指南给出的参考命令与使用方式bunx rayhanadev/truffler query packages --kind function,method,interface,type,constant --limit 20必须用bunx rayhanadev/truffler执行已发布的bin是 Bun 直接运行的 TypeScript 入口且会复用锁定的 dev dependency 而非重新下载。query与根路径如packages/core/src收窄可提高精度无匹配时才放宽。完整工作流见 .agents/skills/find-similar-functions/SKILL.md。包布局一个私有诊断引擎加四个发布物AGENTS.md 用一张目录树定义了 monorepo 的职责边界packages/下packages/ core/ PRIVATE 诊断引擎 src/ types/ 私有共享跨包 TS 类型DiagnoseOptions、 ProjectInfo、JsonReport 等——无运行时代码 project-info/ 项目发现discoverProject、findMonorepoRoot、 框架检测、在 Effect 运行时接管之前抛出的 窄化 Error 子类 errors.ts TaggedErrorClass 叶子 ReactDoctorError 联合 schemas.ts Diagnostic / Severity / JsonReport / buildDiagnosticIdentity同时以 react-doctor/core/schemas 子路径导出 refs.ts 环境配置的 Context.Reference run-inspect.ts 流式编排器核心心脏 build-diagnostic-pipeline 逐元素过滤管线单一事实来源 services/ Context.Service 实现Files、Git、Project、 Config、Linter、Maintainability、Score、 Reporter、Progress、NodeResolver、 StagedFiles、SupplyChain LintPartialFailures ... 其余 lint / score / suppression 引擎 api/ PRIVATE 编程式 diagnose()Effect.runPromise 外壳 react-doctor/ PUBLISHED CLI 公开 inspect() bin oxlint-plugin-react-doctor/ PUBLISHED 100 规则持有权威的 react-native-dependency-names.ts 从 core 再导出以打破 规则包 ↔ core 循环 eslint-plugin-react-doctor/ PUBLISHED oxlint 插件的 ESLint 镜像这套布局可以推断出两条设计约束其一core/完全私有规则包与 CLI 之间通过它中转规则包与 core 之间的循环依赖靠「react-native-dependency-names.ts由规则包持有、core 再导出」来打破其二api/同样私有编程式入口只是一个Effect.runPromise外壳这决定了后文遥测为何「对react-doctor/api天然静默」——凭据只存在于 CLI 侧。Effect v4 惯用法导入、错误与分发指南声明运行时基于effect4.0.0-beta.102与根 package.json 中dependencies.effect的固定版本一致并以tmp/effect/.patterns/effect.md克隆的参考gitignored和姊妹应用react-doctor-evals作为规范样例来源。导入一个模块一行// 必须 import * as Schema from effect/Schema; import * as Effect from effect/Effect; import * as Cause from effect/Cause; // 禁止伞式导入会膨胀类型解析图 import { Schema, Effect } from effect;错误TaggedErrorClass 联合 结构化分发每个可失败服务都以ReactDoctorErrorreason: Schema.Union([...])失败每个叶子是Schema.TaggedErrorClassSelf()(Tag, { fields })且用get message()getter而非message 返回人类可读字符串不透明原因在 message 里用Cause.pretty(Cause.fail(this.cause))渲染渲染器只按error.reason._tag分发绝不按error.message.includes(...)formatReactDoctorError/isReactDoctorError/isSplittableReactDoctorError统一住在 packages/core/src/errors.ts禁止另开 error 形状 helper。仓库源码印证了这一约定packages/core/src/errors.ts 中密集出现TaggedErrorClass与ReactDoctorError全文 27 处命中packages/core/src/services/git.ts 与 packages/core/src/project-info/errors.ts 也各自构建标签错误叶子。v4 的分发惯用法同样被写入硬性规则Effect.catchReasons(errorTag, cases, orElse?)是 v4 规范的分发方式每个 case 捕获一个_tagorElse兜底禁止在catch块里手写if (cause.reason instanceof X)阶梯。规范形状见inspect.ts → restoreLegacyThrow与api/diagnose.ts。源码中services/git.ts与errors.ts确在使用catchReasonsEffect.catchTag(tag, handler)用于单个标签错误例如 packages/core/src/services/git.ts 中用Effect.catchTag(PlatformError, ...)把ChildProcess平台错误折叠成ReactDoctorErrorEffect.die(error)把恢复值提升为runPromise原样重抛的缺陷用于编程契约仍要求旧Error类的场景禁止在Effect.gen内try/catchv4 硬规则同步抛出包进Effect.try({ try, catch })再用Effect.orElseSucceed/Effect.catch恢复。生成器卫生方面终端效果Effect.fail/Effect.interrupt/Effect.die必须写return yield*以便 TypeScript 识别不可达代码v4 改为了Effect.gen({ self: this }, function* () { ... })的 this 绑定形式普通Effect.gen不变Effect.fnUntraced用于热路径——指南同时明确当前代码库尚未用它因为 Git 调用与 inspect 管线是每次扫描一次而非热循环。Services、Layer 与 Schema 约定服务定义Context.ServiceSelf, Interface()(react-doctor/Name, { make: ... })标识符用短前缀方法体热路径用Effect.fnUntraced一行式用Effect.sync测试层与编排用Effect.gen可观测方法非平凡方法用Effect.fn(Service.method)使其作为命名 span 出现在 OTel trace 中——无 tracer 层时生产代价为零接了Otlp.layerJson(...)则每次服务调用一个 spanLayer 命名词汇表layerNodeNode 生产实现、layerOf(value)预供值测试层、layerInMemory(Map)内存文件树服务、layerCapture把调用记录进Ref的捕获测试层如ReporterCapture、layerNoopvoid/丢弃语义Reporter/Progress分析器 Linter/Maintainability 用layerOf([])、以及layerOxlint、layerHttp等实现名Schema 分工线上记录Diagnostic、JsonReport用Schema.ClassSelf(Name)({ fields })字面量联合用Schema.LiteralsSchema.NullOr/Schema.optional对应| null与?品牌原语用Schema.brand(X).pipe()入参类型InspectInput、LintInput用 interface以避免热路径上的运行期 encode/decode 开销环境配置环境变量读取与缓存路径一律走Context.ReferenceT(react-doctor/X, { defaultValue })测试通过Layer.succeed(MyRef, ...)覆盖密钥类配置优先Config.redacted(ENV_NAME)以便自动脱敏。packages/core/src/refs.ts 是该约定的直接样例OxlintSpawnTimeoutMs以Context.Referencenumber(react-doctor/OxlintSpawnTimeoutMs, ...)定义defaultValue从REACT_DOCTOR_OXLINT_SPAWN_TIMEOUT_MS环境变量读取、缺省回落到constants.js的OXLINT_SPAWN_TIMEOUT_MS——文件头注释还解释了为何在启动时读取便于评测沙箱在不重编译 react-doctor 的情况下调高预算。遥测架构Axiom 与 Sentry 双后端指南的 Observability 一节是全篇最长也最工程化的部分核心是故意拆分的两个后端Axiom收 trace 与 metrics每次运行的宽事件wide event、每个Effect.fn(Service.method)span、全部计数器/分布。选择理由是 Axiom 按摄取量计费、无活跃序列上限适合高基数宽事件Sentry只收 crashsource-map 符号化scripts/sentry-sourcemaps.mjs、issue 分组、可引用的事件 id。由于 Effect 只有一个Tracer引用两者对 span 互斥CLI 固定tracesSampleRate: 0Sentry 永不记录 span。关键机制包括单一开关packages/react-doctor/src/cli/utils/is-telemetry-enabled.ts 是所有后端的唯一闸门——--no-score、--no-telemetry、REACT_DOCTOR_NO_TELEMETRY或测试运行全部关闭。源码显示它直接读process.argv而非 Commander 解析结果因为决策发生在 CLI 解析参数之前它还会在VITEST/NODE_ENVtest下静默防止 e2e 套件把构建产物 CLI 的子进程扫描发回生产遥测每进程只构建一次 telemetry 层packages/react-doctor/src/cli/utils/telemetry-runtime.ts 把层构进长生命周期 scope 并共享Context。原因是 Effect 的 delta-temporality 状态挂在 metrics exporter 实例上第二个 exporter 会以「无历史快照」重报每个计数器的全量值——静默地把所有指标翻倍。core/tests/telemetry-payload.test.ts中有回归测试钉住这个双重计数行为传输层core/src/observability.ts拥有三个 layer。因为 Axiom 用不同 header 把 trace/metrics 路由到不同数据集X-Axiom-Datasetvsx-axiom-metrics-dataset而Otlp.layer只支持单一 headers 对象layerAxiomTraces与layerAxiomMetrics被手工组合序列化用protobufAxiom 的/v1/metrics只收application/x-protobufOtlpSerialization.layerProtobuf随 Effect 自带、不加依赖。用户配置的REACT_DOCTOR_OTLP_*端点优先于第一方 Axiom否则 Axiom再否则Layer.empty匿名化OTLP 没有 Sentry 式beforeSend钩子故用core/src/utils/make-scrubbing-tracer.ts包一层 tracer让每个 span 名、属性值、事件载荷在出港前过anonymizeText家目录/用户名 →~再脱敏密钥与邮箱metrics 不经过 tracer则在 packages/react-doctor/src/cli/utils 的record-metric.ts发射点脱敏调用点仍应在源头脱敏如run-inspect.ts对inspect.directory用scrubSensitivePathstracer 只是兜底凭据Axiom ingest token 直接内嵌在 packages/react-doctor/src/cli/utils/constants.tsAXIOM_INGEST_TOKEN源码中可见于该文件 L212 附近与公开的 Sentry DSN 同理打包进 tarball——但它是真凭据故被铸为「ingest-only、限定两个数据集」轮换需发版靠 Axiom 侧的摄取量异常监控发现。REACT_DOCTOR_AXIOM_TOKEN/_DOMAIN/_DATASET前缀覆盖变量专为本地测试保留裸AXIOM_*是 Axiom 自己的变量名读它们会劫持其他工具的遥测。凭据只留在 CLI 侧是react-doctor/api「构造即静默」的原因span 规范形状多步操作的顶层入口用Effect.withSpan(name, { attributes })包裹属性键用点号命名空间inspect.directory、inspect.isCi。packages/core/src/run-inspect.ts 中runInspect即以Effect.withSpan(runInspect, {...})作为父 span每个Service.method是它的子 spanrunId每次 CLI 运行进程铸造一个随机runId随 Sentryruncontext 与宽事件携带但只在 crash 报告里作 tag关联 Axiom trace永不作 metric 属性——按运行唯一的值会炸掉计数器基数。指南还明确禁止向任一端点添加明文或哈希过的 repo id。宽事件wide event的建模哲学也值得注意每次扫描一个高维宽事件而不是一堆窄计数器。根 span 由build-run-event.ts用完整结局富化成功与失败路径都会落事件outcome.status为clean/ok/blocked/error、outcome.exitCode、outcome.errorTag属性按概念命名空间树状组织scan.*、outcome.*、diag.*、score.*、lint.*、timing.*、action.*数值结局保持 number 以便取p75(score.value)之类的分位数查询null经toSpanAttributes丢弃而非变null。新增运行级维度进build-run-context.ts→build-sentry-scope.ts新增单扫描结局维度进宽事件——不要加新计数器。控制台与日志必须import * as Console from effect/Console在渲染器、服务与任何 Effect 类型代码里用yield* Console.log(...)。Effect 的Console是Context.Reference默认 sink 就是globalThis.console生产路径等价于裸console.log但可被测试/静默模式替换禁止另造Logger/LoggerWriter抽象——历史自定义 Logger 服务在渲染管线 Effect 化时已移除唯一剩余桥梁是cli/utils/cli-logger.tsEffect.runSync(Console.X)的薄同步包装静默模式走Effect.provideService(Console.Console, silentConsole)渲染管线或installSilentConsole()JSON 模式猴子补丁全局 console——调用点没有任何if (silent) return。测试布局与提交前检查测试与源码同包、置于各包tests/目录packages/core/tests/ — 服务测试 run-inspect 编排测试packages/api/tests/ — api 外壳测试packages/react-doctor/tests/ — CLI 端到端 fixture 测试。测试框架是vite-plus/testvitest 封装。指南要求提交前必跑与根 package.json 的 scripts 一致pnpm test # 所有包 pnpm lint pnpm typecheck pnpm format # 仅校验用 format:check pnpm smoke:json-report # 用 schema 校验已构建 CLI 的 JSON 输出补充环境约束根 package.json 的engines要求node: ^20.19.0 || 22.13.0。发布授权Agent 必须在首个发布动作前停下「Release authorization」一节是写给 Agent 的硬边界四条 MUST不鼓励 minor/major Changesets用户没明确要该级别就不要加patch Changesets 合适时可自行加绝不在「合并前一刻」未获得用户对该 PR 与版本的新鲜显式确认的情况下合并任何 Changesets 发布 PR含changeset-release/*分支「合并、发布、盯绿」的笼统指令不构成发布 PR 的合并授权——把触发发布的 PR 合并视为发布行为本身绝不发布包、推送/移动发布 tag、或触发/批准/重跑/合并发布工作流除非用户针对确切版本与包做了新鲜显式确认。Agent 可以准备、验证、盯发布候选但必须停在首个发布动作之前并报告等待用户批准的 PR、版本、包、tag 与工作流清单。GitHub Action 版本化独立于 npm 包的双 tag 命名空间仓库根的 action.yml 是 composite GitHub Action与 npm 包独立版本化。Action 的边界 action.yml 它 shell 出去的几个脚本scripts/ensure-json-report.mjs、scripts/normalize-changed-files.mjs、scripts/render-github-action-comment.mjs、scripts/resolve-package-spec.mjs改动其中任何文件都算一次 action 发布且该清单必须与 scripts/recommend-action-version-bump.mjs 中的ACTION_RELEASE_FILES发布守卫保持同步——该文件确实以const ACTION_RELEASE_FILES [...]维护这份清单。规则要点两套 tag 命名空间并行绝不混用npm 包 tag 无v前缀react-doctorX.Y.Z等由 Changesets 在 CI 创建见 .github/workflows/publish.ymlAction tag 是带v前缀的 semvervX.Y.Z加浮动主版本vNGitHub Actions 惯例v前缀使其与包 tag 区分。v0.x是重建前旧版PR 报告重建是v1.0.0当前为v2.x线每个触碰 action 文件的 commit 必须打 tagfeat(action)→ minor其余fix/refactor/chore/revert或对action.yml的纯文档编辑→ patchinputs/outputs 或运行时契约的破坏性变更 → major打完vX.Y.Z后浮动主版本vN必须移到同一 commit保证uses: .../react-doctorvN始终解析到最新兼容版本tag 是 GPG 签名附注 tagtag.gpgsigntrue裸git tag vX会要求 message 并在脚本中失败必须显式带 message# 在改动了 action 的 commit 上打新发布 tag git tag -a v2.2.3 commit -m react-doctor action v2.2.3 # 移动浮动主版本仅强制更新 vN 指针 git tag -fa v2 commit -m react-doctor action v2 (floating major - v2.2.3) git push origin v2.2.3 git push --force origin v2 # force 仅作用于移动中的主版本 tag绝不让消费方在文档/示例里引用main——main以pull-requests: write权限运行任意 HEAD是供应链风险加固 CI 推荐完整 commit-SHA 加尾注版本uses: .../react-doctorsha # v2.2.2便捷场景用vN。参考阅读指南末尾给出两条延伸阅读指针tmp/effect/.patterns/effect.mdEffect v4 惯用法的规范样例克隆件、gitignored与~/Developer/react-doctor-evals/src/本代码库运行时模式所建模的姊妹应用包括 Schemas.ts、Runner.ts、Worker.ts、errors.ts 的形状。小结CLAUDE.md 的 4 行与 AGENTS.md 的 437 行共同构成了一份「Agent 可读、可执行」的贡献契约它不只描述风格偏好而是把工程决策的理由delta-temporality 为何禁止双 exporter、宽事件为何优于窄计数器、main为何是供应链风险与硬性边界发布前的强制人工确认一起写进上下文让每个进入该仓库的 Agent 以同一套 Effect v4 惯用法、同一套符号去重流程和同一套发布纪律工作。对维护多 Agent 协作仓库的团队而言这份指南本身就是一个可借鉴的样板。【免费下载链接】react-doctorYour agent writes bad React. This catches it项目地址: https://gitcode.com/GitHub_Trending/re/react-doctor创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考