principle-separate-before-serializing-shared-state

在序列化共享状态前，先消除共享

当并发执行者可能共享可变状态时，首先要问：他们是否真的需要同一个可变对象？如果不需要，就消除共享。如果确实需要共享，就通过结构性方式强制串行化：锁文件、顺序阶段、独占所有权。指令和约定无法控制并发。

原因： 对共享状态进行并发写入会产生竞态条件，问题时有时无、难以复现，调试成本也很高。告诉 Agent 或 goroutine 要“轮流操作”行不通。

模式：

1. 识别共享的可变状态（双方都会读写的文件、双方都会推送到的分支、双方都会定义和使用的 API）。
2. 默认做法：消除共享写入目标。 要问：这些执行者需要同一个规范对象，还是在发布彼此独立的信息？为每个执行者分配各自拥有的文件、键、分支或状态目录，并仅在读取或报告时合并。在同一个 state.json 中由两个工作线程分别写入自己的 lastX 字段，仍然属于共享变更；而使用 indexer-state.json 和 metrics-state.json 则不属于。
3. 只有当同一个共享写入目标确实是不可违背的约束时，才通过结构性方式串行化访问（锁文件、顺序阶段、单写入者执行者或原子比较并交换）。把“我们需要一把锁”视为需要审视的设计异味，而不是默认答案。