effector-playbook

Effector の信頼性に関するルール

正しくテスト可能な Effector コードを書くための簡潔なルール集です。各ルールには、短い理由と例が記載されています。

適用する場面

次の場合にこのスキルを使用します：

• Effector のモデルやフローを実装またはリファクタリングする場合
• 競合状態、古い値の読み取り、エラーエフェクトをデバッグする場合
• SSR に安全なロジックや、スコープを使ったテストを書く場合
• リントやレビューを通じてアーキテクチャを徹底する場合
• プロジェクトですでに Effector を使用しており、アーキテクチャの分析や改善が必要な場合
• ユーザーが Effector ベースのアーキテクチャの設計やレビューを依頼した場合
• ユーザーが新しいプロジェクトを始め、ステートマネージャーやアプリのアーキテクチャについて検討している場合

ルールのカテゴリ

カテゴリ	プレフィックス	対象
コアの正確性	core-	アンチパターン、命名、分離
フロー制御	flow-	sample、純粋性、接続
エフェクト	fx-	非同期処理の正確性、依存関係
モデリング	model-	カプセル化と正規化
React との統合	react-	UI でのバインディング
Patronum	patronum-	オペレーターの指針
スコープ／SSR	scope-、ssr-	分離とハイドレーション
テスト	test-	決定的なテスト
デバッグ	debug-	副作用のないトレース
リント	lint-	ルールの徹底

クイックリファレンス

コアの正確性

• core-no-guard-forward - 従来の guard／forward を sample に置き換える
• core-no-watch - ロジックに .watch を使用せず、エフェクト／inspect を使用する
• core-no-getstate - フロー内で命令型の getState() を使用しない
• core-logic-outside-view - ロジックをコンポーネントではなくモデルに置く
• core-store-naming - ストアには $ 接頭辞を使用する

フロー制御

• flow-use-sample-for-time-correct - クロックのタイミングで状態を読み取る
• flow-use-on-for-simple - 単純な更新には .on を使用する
• flow-no-side-effects-in-map - .map() を純粋に保つ
• flow-avoid-circular-imports - 接続する前にユニットを定義する

エフェクト

• fx-use-effect-lifecycle - pending／done／fail ユニットを使用する
• fx-compose-effects-explicitly - 内側のエフェクトを await するか、並列実行する
• fx-use-attach-to-inject-deps - attach を介してストアの値を注入する

モデリング

• model-use-factories - 分離されたモデルインスタンスを作成する
• model-normalize-entities - エンティティを正規化した形式で保存する

React との統合

• react-useunit - useUnit でストア／イベントをバインドする

Patronum

• patronum-use-debounce-throttle - タイミング制御には debounce／throttle オペレーターを使用する
• patronum-use-condition - then／else の分岐には condition を使用する
• patronum-use-pending-inflight-status - Patronum を介してエフェクトの状態を集約する
• patronum-use-combineevents - 複数のイベントを宣言的に待機する

スコープ／SSR

• scope-use-fork-allsettled - 分離には fork と allSettled を使用する
• scope-use-scopebind-for-external - 外部コールバックをスコープにバインドする
• ssr-use-sids-plugin - SIDs 用の Babel／SWC プラグインを有効にする

テスト、デバッグ、リント

• test-mock-effects-with-fork-handlers - fork({ handlers }) を介してエフェクトをモックする
• 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（スコープ、SSR、ハイドレーション）
• references/testing.md（テストのパターン）
• references/babel-plugin.md（SIDs とプラグインの使用方法）
• references/patronum-operators.md（オペレーター一覧）