在 Roblox Luau 中划分模块边界…

适用于为 Roblox Luau 代码选择最小模块形态、明确实例与事件连接的所有权和清理、按需调度 task，并在可失败调用中区分成功返回 nil 与真正失败。

适用场景

解决思路

1. 无状态转换或校验默认使用普通函数。
2. 需要私有状态时使用带私有状态的模块，并且每个模块只作为一个明确子系统所有者。
3. 不要仅仅为了给函数分组命名空间而创建 manager 类。
4. 多个独立值需要共享行为和生命周期时，使用带 metatable 的对象。
5. 项目已经一致使用现有库抽象时，遵循该抽象。
6. 不要为一个调用点引入 Promise、signal、cleanup 或框架依赖。
7. 构造函数使用 `.` 调用。
8. 实例方法使用 `:` 调用。
9. 可变字段放在实例上，不要放在类表上。
10. 连接 signal、创建实例或启动 task 的代码负责 cleanup。
11. 在生命周期结束时保存并 cancel 或 disconnect 这些连接/任务。
12. 当观察者不应看到部分状态时，先在 parent 之前配置实例。
13. 只有在 API 或生命周期需要 ancestry 时才提前 parent，并记录该原因。
14. 不要把它当作解决复制竞态的魔法修复；它只是可见性控制。
15. 用 pcall 保留失败语义，例如：local ok, value = pcall(dataStore.GetAsync, dataStore, key); if not ok then return nil, `read failed: {value}` end; return value, nil -- value may legitimately be nil。
16. 不要把“调用成功且返回 nil”合并成“调用失败”。
17. 仅在领域操作可安全重复时重试。
18. Persistence、HTTP、purchases、remotes 交给各自的领域技能处理。
19. 有意使用 `task.defer`、`task.spawn`、`task.delay`、`task.cancel`。
20. 避免 legacy `wait()` 和无理由轮询。
21. 优先使用真实的状态变更 signal；否则选择并测量明确的 cadence。
22. Review 时确认所有者明确。
23. Review 时确认公共 API 窄。
24. Review 时确认没有循环 require。
25. Review 时确认没有不经意的并发启动。
26. Review 时确认成功状态与缺失数据状态保持区分。
27. Review 时确认 connections/tasks 已清理。
28. Review 时确认客户端输入路由到 `roblox-networking`。

适用边界 · 注意事项

• 不用于 Luau 语言行为细节；语言行为用 `roblox-luau-core`，类型用 `roblox-luau-types`。
• 不用于项目级所有权和启动；这些用 `roblox-architecture`。
• 不用于持久化、HTTP、购买、remotes 的领域语义；这些交给各自领域技能。