docs(agents): record the parallel-coordination rules that stopped the rework loop

Same work, two instruction versions in the queue: the executing agent follows
the stale one while the lead has already finished and committed the revised
one. Nothing in the queue records which instruction is current, so which
version runs is effectively random. That is what the mutual-overwrite round
was, not a communication failure.

AGENTS.md gains a 9th section with the five rules, including the one that
actually had to be enforced: withdrawing an instruction requires telling the
executor by name, because replacing it in the queue is not withdrawal.

Mechanical follow-up work that cannot collide with someone else (anchor
recalculation, wording, missing tests) should be done while waiting rather
than queued. Committing stays with the lead.

GATE-DOCS 6/6, ANCHOR AUDIT 129 refs / 0, PATH AUDIT 454 / 0. AGENTS.md
248 -> 267 lines, outside the 500-line soft cap and the size checker only
covers src/, web/ and cloudflare-worker/.
This commit is contained in:
anonsaber 2026-09-30 03:03:59 +08:00
parent b764d6dc30
commit 24a3f04dab
1 changed files with 19 additions and 0 deletions

View File

@ -246,3 +246,22 @@
- 在文档或注释里引用不存在的依赖、函数、类型、键、路径或行号。
- 把「计划做」写成「已完成」;把「推测」写成「结论」。
- 只改代码不改文档,或只改文档不改代码。
---
## 9. 协作与并行边界
多 agent 并行时,**同一件事只能有一个有效指令版本**。这不是礼仪,是事故来源。
2026-09-29 的实际故障:同一件事的旧版指令和新版指令同时躺在队列里,执行者按**旧版**动手,
lead 已经按**新版**收口并提交——同一份文档被两个人改,一次收口变成三轮互相覆盖。
**哪一版被执行是随机的,队列里没有「哪条有效」这个概念。**
1. **撤回必须点名。** 作废一条已发出的指令,光把新版发出去不算数——要直接告诉执行者
「那条作废、别做、保持 idle」。
2. **派活前先查状态。** 对方 `working` 时不要派活、不要改它的交付物、不要假设它收到了;
确认 `idle` 之后再派。
3. **不要发「改进版」覆盖未执行的旧版。** 要么等旧版执行完,要么先点名作废,再发新版。
4. **不要广播。** 广播会把整队打进 paused;点对点派发或靠任务派发唤醒。
5. **不撞车的机械收尾自己做。** 锚点重算、文档措辞、测试补齐这类不会互相覆盖的工作,
等别人时自己做完,不要排队——排队本身是延迟源。提交由 lead 统一收口。