docs(agents): os-dev isolates scratchpad temp files in a per-issue subdir (#5614) - #5727
Merged
Merged
Conversation
…bdir (#5614) Parallel os-dev agents dispatched in one batch share a single container scratchpad directory. Nothing separates their temp files, so the natural filenames — `pr-body.md`, `notes.md`, `diff.txt` — collide: whoever writes last wins, both writers get a success receipt, and the loser reads the other agent's content back under its own name. Measured once already (#5614): the #5483 agent's PR body draft came back as the #5176 agent's, discovered only on read-back. Fixed structurally rather than by convention, one level down from the worktree-first rule it mirrors: the agent creates an `issue-<n>/` subdir under the scratchpad as a first step and writes every temp file only there, so isolation does not depend on each agent remembering to decorate filenames. Added as a sub-bullet of the worktree-first rule (same shape, adjacent location) instead of a new numbered item, which would renumber items 2-6 and break the `(rule 6)` cross-reference further down the file.
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
os-zhuang
added
the
skip-changeset
Claude
github-actions
Bot
added
the
documentation
os-zhuang
marked this pull request as ready for review
August 6, 2026 02:26
This was referenced Aug 6, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #5614
采 issue 建议的方案 2(结构式),PM 已裁定:结构优于纪律。单文件文档改动,仅
.claude/agents/os-dev.md,+10/-0。失败形状(issue 实测)
同一 PM 会话并行派发的 os-dev subagent 共享同一个容器 scratchpad 目录,目录里没有任何东西区隔各单的临时文件。于是最自然的文件名(
pr-body.md、notes.md、diff.txt)天然撞车:后写者覆盖先写者,双方都拿到成功回执,受害面是「拿自己的名字读回别人的内容」。已实咬一次——#5483 的 dev 写的 PR 正文草稿被同批 #5176 的 dev 覆写,直到回读才发现内容换了主(PR #5609 因该 dev 当场改名规避而未受影响)。批次越大碰撞概率越高。改动
在开工步骤区的 worktree-first 条目下新增一条子项:开工即在 scratchpad 下建本单专属
issue-+ 单号 子目录,所有临时文件(PR 正文草稿、报告草稿、中间测量、探针输出)只写在其中;附一两句静默覆写的失败形状与 #5614/#5483/#5176 实例;并给出与 worktree-per-task 同构的定位——靠结构隔离,不靠记性。放置位置的取舍:写成 worktree-first 的子项而非新编号项。两个理由——(1) 形状同构、位置紧邻,worktree 隔离共享检出、scratchpad 隔离共享临时目录,后者正是前者「低一级」的同一条规则;(2) 插入新编号项会把原 2–6 项整体顺延,而文件后段「
premise_still_valid: false…(rule 6)」是按编号交叉引用的,顺延即断链——本单要求现有段落一字不动,故不改编号。列表层级/缩进(3 空格-+ 5 空格续行)与既有第 3 条子项完全一致。范围严格限于该一条:收尾清单、Byte discipline、Toolchain traps、Resource discipline、报告模板等段落一字未动;AGENTS.md 与 SKILL.md 未触碰(治理面一处落点够用)。
验证
纯 prompt 文档改动,没有可执行断言面,因此逆向验证(还原被删分支看诊断转红)对本单不适用——没有被删除的代码分支,也没有会因此变色的测试;这里如实说明,不编造形状相符的证据。实际做的是:
git diff --numstat=10 0,单文件单 hunk;前后上下文行逐字节未变(-U6复核)。node scripts/check-nul-bytes.mjs绿:OK (scanned 5614 tracked text file(s); …; no raw ASCII control bytes),含 test(devx): check-nul-bytes 的 --self-test 断言字符类引用面逐字节相等,终结该族漂移 (#5646) #5680 的字符类引用面断言(该行未触碰)。grep -naP '[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]'退出码 1。**强调全文成对,新增行无行尾空白、无超 80 列(全文 3 处超宽均为改动前既有行)。issue-5614/子目录里,按本 PR 新增的这条纪律执行。发布面
.claude/文档-only,不发布任何包,无 changeset → 走skip-changeset标签路线(按 os-dev.md 现行收尾清单:回读 labels → 写并集 → 再回读)。Generated by Claude Code