effector-playbook

Effector 可靠性规则

用于编写正确且可测试的 Effector 代码的简明规则集。每条规则都附有简短的理由和示例。

适用场景

在以下情况下使用此技能：

• 实现或重构 Effector 模型和流程
• 调试竞态条件、过期读取或 effect 错误
• 编写 SSR 安全逻辑或使用 scopes 进行测试
• 通过 lint 或评审来强制执行架构规范
• 项目已经在使用 Effector，需要分析或改进其架构
• 用户要求设计或评审基于 Effector 的架构
• 用户正在启动新项目，并讨论状态管理器或应用架构的选择

规则类别

类别	前缀	重点
核心正确性	core-	反模式、命名、分离
流程控制	flow-	sample、纯函数、连接
Effects	fx-	异步正确性、依赖项
建模	model-	封装与规范化
React 集成	react-	在 UI 中绑定
Patronum	patronum-	运算符指南
Scopes/SSR	scope-、ssr-	隔离与水合
测试	test-	确定性测试
调试	debug-	无副作用地跟踪
Lint	lint-	强制执行

快速参考

核心正确性

• core-no-guard-forward - 用 sample 替换旧版 guard/forward
• core-no-watch - 不要使用 .watch 实现逻辑；改用 effects/inspect
• core-no-getstate - 流程中不使用命令式 getState()
• core-logic-outside-view - 将逻辑放在模型中，而不是组件中
• core-store-naming - Store 使用 $ 前缀

流程控制

• flow-use-sample-for-time-correct - 在时钟触发时读取状态
• flow-use-on-for-simple - 简单更新使用 .on
• flow-no-side-effects-in-map - 保持 .map() 纯净
• flow-avoid-circular-imports - 在连接之前定义单元

Effects

• fx-use-effect-lifecycle - 使用 pending/done/fail 单元
• fx-compose-effects-explicitly - 等待或并行执行内部 effects
• fx-use-attach-to-inject-deps - 通过 attach 注入 Store 值

建模

• model-use-factories - 创建隔离的模型实例
• model-normalize-entities - 以规范化形式存储实体

React 集成

• react-useunit - 使用 useUnit 绑定 Store 和事件

Patronum

• patronum-use-debounce-throttle - 使用 debounce/throttle 运算符控制时序
• patronum-use-condition - 使用 condition 实现 then/else 分支
• patronum-use-pending-inflight-status - 通过 Patronum 汇总 effect 状态
• patronum-use-combineevents - 以声明式方式等待多个事件

Scopes/SSR

• scope-use-fork-allsettled - 使用 fork 和 allSettled 实现隔离
• scope-use-scopebind-for-external - 将外部回调绑定到 scope
• ssr-use-sids-plugin - 启用 Babel/SWC 插件以支持 SIDs

测试、调试与 lint

• test-mock-effects-with-fork-handlers - 通过 fork({ handlers }) 模拟 effects
• debug-use-inspect - 使用 inspect/patronum/debug 进行跟踪
• lint-use-eslint-plugin-effector - 使用 ESLint 规则强制执行架构规范

使用方法

阅读各条规则文件：

rules/core-no-guard-forward.md
rules/scope-use-fork-allsettled.md

参考资料

• AGENTS.md（编译后的规则）
• references/llms-full.txt（Effector API 参考）
• references/scopes-ssr.md（scopes、SSR、水合）
• references/testing.md（测试模式）
• references/babel-plugin.md（SIDs 和插件用法）
• references/patronum-operators.md（运算符索引）