用途:为 Effect-TS 代码库强制统一、有主见的编码模式,优化类型安全、可测试性、可观测性与可维护性。审查 diff/plan 时可调用 effect-advocate 子代理。
主要能力与规则:服务用 Effect.Service 并开启 accessors,业务逻辑不用 Context.Tag;依赖在服务内用 dependencies 声明,不在使用处手动 Layer.provide。错误用 Schema.TaggedError 并带 message 字段,避免普通类或通用 Error;错误要具体(如 UserNotFoundError、SessionExpiredError),不要泛化 NotFoundError。处理错误用 catchTag/catchTags,避免 catchAll 或吞掉错误。实体 ID 用 Schema.UUID.pipe(Schema.brand(...)) 加品牌类型。函数优先 Effect.fn(需带 span 名),Effect.gen 仅用于共享管道。参数是运行时数据,依赖从上下文 yield。日志用 Effect.log 结构化数据,不用 console.log。配置用 Config.* 校验,不直接读 process.env。Option 用 Option.match 处理两分支,禁止 Option.getOrThrow;领域类型用 Option<T> 而非 null/undefined。Atom 在组件外 Atom.make,全局状态用 Atom.keepAlive,React 中用 useAtomSet,副作用用 get.addFinalizer() 清理,结果用 Result.builder 配合 onErrorTag。
必要用法:Cursor 的 read_lints 不显示 Effect Language Server 诊断,需用 CLI:npx effect-language-service diagnostics --file <path>,或整项目 npx effect-language-service diagnostics --project tsconfig.json;编辑 Effect 代码时运行并修复报告问题,effect-language-service quickfixes 可查看建议改动。
限制与禁止:服务内禁止 runSync/runPromise;Effect.gen 内禁止 throw,应 Effect.fail;禁止 catchAll 丢失类型信息;禁止吞掉错误。SubscriptionRef 的 .changes 已含当前值快照,不要再前置 get,需跳过初始快照可用 Stream.drop(1)。更多细节见 references 下 service-patterns、error-patterns、schema-patterns、layer-patterns、effect-atom-patterns、rpc-cluster-patterns 等文档。