get-shit-done 竞态修复实录：`ai-integration-phase` 如何用「顺序执行 + Edit-only」消除 AI-SPEC.md 的 last-writer-wins 覆盖

• 人工智能
• AI 应用
• 提示工程
• 开发工具
• 工作流自动化
• AI Agent

导读

ai-integration-phase是 get-shit-done（GSD）系统中生成 AI 设计契约（AI-SPEC.md）的关键工作流。它曾经存在一个隐蔽的并发缺陷：当gsd-ai-researcher与gsd-domain-researcher被并行派发时，后者的Write调用会以整文件覆盖的方式静默抹掉前者写入的 Section 3/4，实测发生率高达 40%（5 个 agent 中有 2 个中招）。本文基于变更记录 .changeset/fix-3096-ai-integration-parallel-race.md，结合工作流定义、Agent 提示词与回归测试源码，完整拆解这一竞态的根因、修复策略（显式顺序执行约束 + Edit-only 工具纪律）以及防止复发的测试保障，并提炼出可复用到任何多 Agent 协作场景的共享文件写入工程原则。

一、背景：ai-integration-phase与 AI-SPEC.md

ai-integration-phase是 GSD 生命周期中介于 discuss-phase 与 plan-phase 之间的设计契约阶段。其命令入口定义在 commands/gsd/ai-integration-phase.md，由工作流 get-shit-done/workflows/ai-integration-phase.md 具体编排，按顺序完成四步流水线：

Select Framework → Research Docs → Research Domain → Design Eval Strategy → Done

即依次派发四个 Agent：

1. gsd-framework-selector—— 选定 AI 框架（含备选方案与理由）；
2. gsd-ai-researcher—— 研读框架官方文档，产出 AI-SPEC.md 的 Section 3（Framework Quick Reference）、Section 4（Implementation Guidance）与 Section 4b（AI Systems Best Practices）；
3. gsd-domain-researcher—— 研究业务领域与专家评估标准，产出 Section 1b（Domain Context）；
4. gsd-eval-planner—— 基于领域上下文设计评估策略，产出 Section 5/6/7（Evaluation Strategy、Guardrails、Production Monitoring）。

最终产物 AI-SPEC.md 由模板 get-shit-done/templates/AI-SPEC.md 生成，在规划开始前锁定四类关键决策：框架选择、实现指引、领域上下文与评估策略。工作流末尾的校验步骤（Step 10）会逐项检查 Section 2 框架名、Section 1b 的领域评估要素、Section 3 的代码块、Section 4b 的 Pydantic 示例、Section 5 的评估维度表等是否非空，防止生成"空壳契约"。

二、Bug #3096：并行派发导致的 AI-SPEC.md 整体覆盖

2.1 根因：两个"看似不相交"的 Agent 共享同一个文件

在修复之前，工作流的 Step 7 与 Step 8 只按顺序罗列了派发动作，并未显式声明二者的执行约束。而gsd-ai-researcher与gsd-domain-researcher写入的是 AI-SPEC.md 中互不重叠的章节（前者写 Section 3/4/4b，后者写 Section 1b）。这种"章节不相交"的表象，让编排者产生了一个完全合理的优化冲动：并行派发这两个 Agent 以缩短整体耗时。

这正是竞态的温床，依据如下：

• gsd-ai-researcher的职责定义（见 agents/gsd-ai-researcher.md）要求使用Write工具创建/更新文件，并明确"ALWAYS use the Write tool to create files"；
• gsd-domain-researcher（见 agents/gsd-domain-researcher.md）同样声明使用Write工具完成 Section 1b 的写入。

2.2 事故现场：最后写入者赢（last-writer-wins）

Write工具的语义是整文件替换而非增量更新。并行场景下的事件序列如下：

1. 编排者同时派发两个 Agent，二者各自读取 AI-SPEC.md 模板，在各自的内存中持有文件的初始副本；
2. gsd-ai-researcher完成研究，用Write提交了包含 Section 3/4/4b 内容的完整新文件；
3. gsd-domain-researcher随后完成领域研究，在 finalization 时用Write提交它内存中那份"尚未包含 Section 3/4"的旧副本——这一步把整个 AI-SPEC.md 静默替换回了 researcher 写入前的状态，Section 3/4 就此丢失。

变更记录给出的实测数据是：发生率约 40%（一次真实运行中 5 个 worktree agent 有 2 个触发该竞态）。其危险之处在于失败是"静默"的——文件依然存在、结构依然完整、没有报错，只有事后校验时才能发现 Section 3/4 缺失。修复前的恢复代价同样高昂：需要重新派发一次gsd-ai-researcher，大约 18 分钟的真实墙钟时间。

三、修复方案：两层防线，双管齐下

变更记录与工作流源码共同确认了修复的两条核心措施（落地于 get-shit-done/workflows/ai-integration-phase.md）：

3.1 第一道防线：显式的顺序执行约束

在 Step 7 顶部新增了专门的排序说明块（Ordering note）：

Ordering note (prevents tool-level last-writer-wins race):Steps 7 and 8 write disjoint sections of AI-SPEC.md but MUST run sequentially — wait for Step 7 to complete before spawning Step 8.

Step 8 同样携带独立提示：

Wait for Step 7 to complete before spawning this step(see ordering note in Step 7).

关键措辞是MUST run sequentially与wait for Step 7 to complete before spawning Step 8。这不是一句模糊的"建议按顺序"，而是把执行约束写进契约本身：任何读取该工作流的编排者（无论是 Claude Code、Codex 还是其他运行时的 orchestrator）都会看到明确的指令——第 8 步必须在第 7 步完成之后才能启动。同时说明块直接点破了设计动机：两个步骤虽然写不同章节，但共享同一个文件，Write的整文件替换语义会让并行派发产生 last-writer-wins 覆盖。

3.2 第二道防线：Edit-only 工具纪律注入

仅靠顺序约束并不够——即使顺序执行，若两个 Agent 各自仍持有过期的内存副本并在收尾时用Write提交，依然可能覆盖对方成果。因此修复同时向两个 Agent 的派发提示中都注入了强制工具纪律：

Tool discipline (mandatory):Use the Edit tool exclusively when modifying AI-SPEC.md — NEVER use Write on this file. Write replaces the entire file and will overwrite work from parallel or sequential sibling agents. Before editing, verify the section you are about to write is still a template placeholder.

这段注入包含三个层次：

• 工具切换：把默认的Write改为Edit——Edit只针对目标行做增量修改，不触碰文件其余部分；
• 原理说明：明确告知 AgentWrite会替换整个文件并覆盖兄弟 Agent 的成果（无论并行还是顺序），消除"为什么不能用 Write"的歧义；
• 前置校验：要求 Agent 在编辑前先确认目标章节仍是模板占位符（<!-- ... -->注释块），从源头避免对已写入内容的二次覆盖。

对应地，两个 Agent 的独立定义文件也保留了文档查找、质量标准与成功标准等完整规范（见 agents/gsd-ai-researcher.md 与 agents/gsd-domain-researcher.md），修复并未削弱各自的研究深度要求，只是修正了"如何落盘"的方式。

四、回归测试：把竞态防御固化为可执行断言

修复不是一次性的，仓库用专门的回归测试 tests/bug-3096-ai-integration-phase-parallel-race.test.cjs 把防御固化成了可重复验证的契约。该测试直接读取get-shit-done/workflows/ai-integration-phase.md的文本内容，用四个断言守护修复成果：

1. Step 7 必须包含顺序执行声明：校验工作流文本中出现sequentially或sequential字样，缺失即视为竞态可复发；
2. Step 7 的 agent 提示必须包含 Edit-only 纪律：截取 Step 7 到 Step 8 之间的文本块，断言其中同时出现Edit tool与NEVER use Write；
3. Step 8 的 agent 提示同样包含 Edit-only 纪律：截取 Step 8 到 Step 9 之间的文本块，做同样的断言；
4. Step 8 必须引用等待指令：断言 Step 8 文本块中出现Wait/wait/complete字样。

从测试源码可以推断其防御逻辑：因为ai-integration-phase.md的文本本身就是运行时所加载的部署契约（测试注释明确标注 "reading product workflow markdown to verify structural ordering contract"），对文本做结构断言，就是对运行时行为做验证。任何人后续编辑工作流时若误删排序说明或工具纪律，测试会立刻失败。

配套的 tests/ai-evals.test.cjs 则从配置侧守护整个 AI 集成阶段：验证workflow.ai_integration_phase配置项默认值为true、支持config-set/config-get读写，以及健康检查在缺失该配置时发出 W016 警告、并在--repair模式下通过addAiIntegrationPhaseKey自动补齐。

五、通用工程启示：多 Agent 共享文件的三条铁律

从这次 40% 发生率的真实事故中，可以提炼出适用于任何多 Agent（或多进程）协作写入共享文件的工程原则，这也是本修复超越单一仓库的通用价值：

1. Write是破坏性操作，共享文件必须禁用：任何会并发或接力写入的共享文件，都应约定Edit/patch式增量修改，并把这一约定以强制措辞注入每个参与者的提示词；
2. "章节不相交"不等于"可以并行"：只要共享同一物理文件，整文件替换语义就足以让任何顺序优化变成数据丢失事故——必须显式声明MUST run sequentially而非依赖读者的合理推断；
3. 用测试锁死契约文本：当"文档文本即运行时行为"时，对文档做结构断言（包含顺序关键字、包含工具纪律、包含等待指令）是最直接有效的防回归手段，成本极低且可自动执行。

GSD 团队在 .changeset/fix-3096-ai-integration-parallel-race.md 中将这次修复定性为Fixed，关闭 issue #3096，并选择将实测发生率、恢复代价写入变更记录——这些数据让后来的维护者能理解"为什么这里要写得这么严格"，而不是把约束当成过度设计。

六、如何在你的项目里复现与验证

如果你希望在自己的 GSD 项目中观察这套防御机制是否生效，可以按以下步骤操作（仓库为只读，以下均为查看与运行验证方式）：

1. 阅读工作流契约：打开 get-shit-done/workflows/ai-integration-phase.md，定位## 7. Spawn gsd-ai-researcher与## 8. Spawn gsd-domain-researcher两个小节，确认排序说明块与 Edit-only 纪律文本均在位；
2. 核对 Agent 提示词：对照 agents/gsd-ai-researcher.md 与 agents/gsd-domain-researcher.md 中关于文件写入的约束表述；
3. 运行回归测试：执行测试 tests/bug-3096-ai-integration-phase-parallel-race.test.cjs，四个断言全部通过即说明顺序约束与工具纪律未被破坏；
4. 验证配置开关：通过gsd-sdk query config-get workflow.ai_integration_phase确认 AI 集成阶段启用（默认true），或运行validate health观察 W016 警告的触发与--repair自愈行为。

这套"顺序执行 + Edit-only + 回归测试"的组合拳，让 AI-SPEC.md 的生成从一次 40% 概率的静默数据丢失，变成有契约、有纪律、有验证的可靠流水线。

• 人工智能
• AI 应用
• 提示工程
• 开发工具
• 工作流自动化
• AI Agent