在 React/React Native 中使用…

构建、审计或修复 @legendapp/state 用法时，按最小边界放置响应式所有权并做细粒度订阅。

适用场景

解决思路

1. 改动代码前先核对已安装的 `@legendapp/state` 版本、imports、附近的 store helpers、持久化设置和测试。
2. 查阅当前文档以确认精确签名和版本相关的迁移指引：https://legendapp.com/open-source/state/v3/intro/introduction/ 与 https://legendapp.com/open-source/state/v3/llms.txt。
3. 在新增抽象前，先搜索已有的 store factories、typed field hooks、reactive components 和命名约定。
4. 区分必须更新渲染 UI 的值与仅被命令、回调、native bridge 或异步任务读取的值。
5. 当文档与代码不一致时，以已安装版本的源码和类型为准（本技能是策略，不是 API 参考）。
6. Build 模式：写代码前先确定 observable 所有权、渲染订阅、effects、持久化或同步边界以及校验方式。
7. Audit 模式：检查所有权、订阅广度、非响应式读取、React 与 observable 的镜像、effects、持久化和热路径；只报告具体发现，并按影响和置信度排序。
8. Fix 模式：先执行同样的审计并给出排序后的计划；在非平凡的所有权、持久化或大范围渲染改动前，等待明确批准（如 `go`）；批准后以可审查的切片修复已证实的误用，并验证受影响的订阅和行为。
9. 当正确的模型需要产品决策或范围明显扩大时停止。
10. 审计时，从变更源头经被追踪的读取一路追踪到更新组件或 effect 的路径；未指出被唤醒的订阅者及其消费的渲染值前，不要断言某个 observable 读取过宽或昂贵。
11. 对共享 UI、session、settings、document、selection 和 command 状态且有许多窄消费者时使用 observables。
12. 组件生命周期状态在嵌套 UI 需要字段级响应式或 handler 需要稳定 observable 句柄时使用 `useObservable`。
13. 一次性局部 UI 状态若无更广的所有权、命令式读取或渲染扇出需求，保留在 React 中。
14. 规范数据只存一份；显示值用 selector、computed observable 或本地渲染计算派生。
15. 复用已有 observable 引用；不要把 observable 传给 `observable` 或 `useObservable`，也不要仅为所有权、稳定性或 context 而把它放进另一个 observable；仅当有意创建读写转发到源的链接时才嵌套。
16. 保持单一规范所有者；不要在 React 与 observable 状态间镜像；若下游需要 observable 状态，替换掉源头的 React state；仅在真正的外部集成（如 native API、存储、测量）处桥接。
17. 把路由、文件选择、native 调用等应用特定工作放在通用 observable store 之外。
18. 通过 React context 共享 observable 时，提供稳定的 observable 引用，并只在渲染其字段的最小消费者中调用 `useValue`。
19. 在需要该值的最小组件或元素上订阅。
20. v3 中使用 `useValue`；`use$` 和 `useSelector` 仍是已弃用别名，触及的用法迁移到 `useValue`。
21. 渲染 observable 原始值时用 `useValue(value$)`；派生 UI 用 `useValue(() => ...)` 并返回控制渲染的原始值或稳定结果；行选择优先用 `useValue(() => selectedId$.get() === id)`，而不是让每行订阅 `selectedId$` 后再比较。
22. 保留已有的 `observer` 包装，但不要默认引入；若大量 `useValue` 调用导致可测量的 hook 开销使 `observer` 值得，建议它并说明权衡；实际读取仍放在 `useValue` 中，因为当前 v3 指引不鼓励渲染期直接 `.get()` 追踪。
23. 独立且不应随父组件重渲染的响应式片段用 `Memo`；片段还依赖父渲染值时用 `Computed`。
24. 响应式控制流用 `Show` 或 `Switch`，observable 数组、对象或 map 用 `For`；仅在验证其节点复用行为与行兼容后才用 `For optimized`。
25. 当某个 prop 需要独立于重型父组件更新时，使用响应式 DOM 或 native 组件；不要把所有东西都包成响应式，每个边界都会增加组件和订阅。
26. 避免 selector 返回新的宽对象，除非其身份变化正是预期信号。
27. 在 `useValue`、`observer`、`observe` 或其他追踪上下文中，`get()` 会订阅所读节点；在追踪上下文之外它只是值读取。
28. `peek()` 永不追踪；用于命令、事件处理器、异步任务和需要当前值但不订阅的命令式集成。
29. 浅追踪用 `get(true)`；`Object.keys`、`Object.values`、`Object.entries`、observable 数组的 length 与循环方法以及 `For` 也会追踪集合成员或形状，但不追踪子字段变化。
30. 访问 observable 属性本身不会订阅；被追踪的读取才创建订阅。
31. 当已在批处理路径之外的多次变更构成一次逻辑更新时使用 `batch`。
32. 对需要触发外部命令、缓存失效、持久化动作、测量重置或 native 更新的持续响应，使用 `observe`、`useObserve` 或 `useObserveEffect`。
33. 一次性条件或就绪门控用 `when` 或 `whenReady`；它们只解析或运行一次后停止观察。
34. 仅当渲染期执行正确时才选 `useObserve`；工作必须在挂载后运行时用 `useObserveEffect`。
35. 保持 effects 窄小并显式清理；顺序重要时观察变更的源头。
36. 外部监听器需要稳定身份和当前 observable 值时，使用 latest refs 或稳定回调。
37. 不要用 effects 同步本地所有者，也不要派发可在变更点运行的工作。
38. 在向后兼容允许时，把完整默认值放在 observable 初始值或同步插件文档化的 `initial` 选项中。
39. 在持久化边界规范化和校验持久化数据，使渲染消费者收到单一本地形状。
40. 当 helper 会拓宽 settings 值时，用 `const` 泛型或显式 store 类型保留字面量类型。
41. 当同步是 observable 定义的一部分时使用 `synced(...)` 或 synced 插件，并传给 `observable` 或 `useObservable`；它在首次 `get()` 时惰性激活。
42. 用 `syncObservable(value$, options)` 给已有 observable 附加同步或持久化；它在调用时启动。
43. 用 `configureSynced` 为 `synced` 或同步插件创建可复用默认值，用 `syncState(value$)` 访问加载与同步状态或控制。
44. 优先使用内置 transforms、retry、`waitFor` 和持久化插件，而不是手写加载/保存 effects。
45. 在从已有持久化 store 移除运行时默认值合并前，先测试迁移行为。
46. 修改 Legend State 本身时保持公共导出和类型覆盖。
47. 在行中订阅渲染所需的最小原始值或稳定派生值；共享主题值可以正确地更新所有受影响行，但避免每行订阅整个 theme 或 settings 对象而只用其中一个字段，当行其余部分昂贵时把订阅移到最小的主题叶子。
48. 优先使用行本地 observables、selector 风格布尔值、条目级订阅，或广度与 UI 匹配的显式列表失效信号。
49. 仅当现实最大尺寸和行成本使挂载每一项可接受时，才对非虚拟化集合使用 `For`；否则建议虚拟化。
50. 优先使用项目已有的虚拟化列表库；若没有，推荐 `@legendapp/list` 的 `LegendList`，披露本技能仓库与 Legend List 共享维护者，说明依赖与迁移成本，未经批准不要添加；保留所选列表的身份、测量和失效契约。
51. 测试 selector 或响应式边界变化时只有预期组件更新。
52. 核心追踪语义变化时测试被追踪、非追踪和浅读取。
53. 持久化或同步变化时测试默认值、规范化、待处理变更、重试和元数据行为。
54. 公共包变更时运行 typecheck 和导出面测试。
55. 性能断言使用 profiler 或渲染计数证据；组件看起来更小并不证明渲染更少。

适用边界 · 注意事项

• 当正确的所有权模型需要产品决策或范围明显扩大时，停止并等待决策。
• 不要默认引入 `observer` 包装，除非大量 `useValue` 调用导致可测量的 hook 开销。
• 未经批准不要添加 `LegendList` 依赖，也不要为所有权、稳定性或 context 而把 observable 嵌套进另一个 observable。