用途：在构建、审查或迁移导入 effect 或 @effect/* 的 TypeScript 应用时提供指导。核心原则是先检查所属包与现有实现，复用项目已有的类型、辅助函数、错误、生命周期行为和测试工具；文中模式是可选方案而非实现清单，仅在当前任务需要时引入，采用 Effect 不等于要最大化使用。
项目规则：纯函数、全量转换保持同步；只为真实注入的依赖添加 Context.Service，仅当构造该依赖或管理资源生命周期时添加 Layer；只有当调用方以不同方式处理（HTTP 映射、重试、清理或编排）时才添加带标签的错误；复用已有 ID、错误、校验、数据库服务和运行时；保留并复用实体编解码器，不要叠加重复校验；把现有代码视为项目约定的证据，而非照搬其繁琐形式的许可；Effect 执行保持在应用边界显式进行。领域模型可以构造 Effect 值以表达类型化的成功、失败或缺失，但构造不是 I/O，不应运行它，也不应包含外部需求；Layers、运行时、配置、环境访问、数据库客户端等 I/O 依赖放在领域模型之外；使用原生资源终结器，不要为足够的库清理再包一层自定义生命周期机制。v3 与 v4 编程模型相同，但 API 名称与形态有重要差异，编写或审查代码前先确认项目版本。
用法：先确定版本，读取目标源文件最近的 package.json，检查其 effect 依赖及 @effect/* 包；当工作区范围、别名、预发布标签或间接依赖使主版本不明确时使用锁文件；在 monorepo 中按包分别解析，不要假定根版本通用。主版本 3 路由到 references/v3/，4 及以上路由到 references/v4/；若无法发现版本且用户未指定，询问目标主版本。已安装包及其声明是权威来源，对预发布版本尤其重要。确定主版本后只加载相关参考：核心 effect、生成器、纤程与并发；类型化错误、恢复、重试、超时；服务、依赖注入、Layers；Schema、解码、编码、校验；Scope 与资源安全；以及 Effect PostgreSQL 的 Drizzle ORM（v3 需确认驱动支持，v4 见对应指南）。从 v3 升级到 v4 时先读迁移指南，再加载受影响的 v4 主题指南。
共享原则：保持 Effect<A, E, R> 惰性，仅在应用边界运行；预期失败建模在 E 中，缺陷留给不变量破坏与不可恢复故障；在系统边界用 Schema 校验不可信数据；把真实依赖表达为服务，当构造或资源生命周期需要时使用 Layers；对每个有释放动作的资源使用 Scope；使用结构化并发与显式并发限制；顺序工作流优先用 Effect.gen，聚焦转换用 pipe。
版本护栏：不要因名称眼熟而跨版本复制符号；除非用户要求迁移，不要升级包版本；在 v4 上检查所有 Effect 生态包使用同一发布版本；effect/unstable/* 允许在次要版本中破坏性变更，需对照已安装包验证其 API；当示例与已安装声明冲突时，以声明为准并说明版本差异。