大改造不敢放手multi-phase-plan 把一个 PR 拆成一章一个验收点【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude让 AI 代理去做一次横跨十几个文件、牵动多个模块的大改造几乎是每个团队迟早会踩的坑。任务太大代理要么一头扎进去乱改一气要么把计划写得像散文执行时却和计划完全脱节。你在睡醒之后面对的不是交付物而是一个需要从头核对的烂摊子。pstack 技能栈里的 multi-phase-plan 想解决的问题正是这个把大改造变成一串可以逐章验收的小 PR每个 PR 自带单元、实机、性能三重证据让放手变成一件有据可查的事。本文基于仓库源码playbook 原文与其配套的机器检查脚本 check-plan.mjs拆解这套方法的完整机制。大改造的失控点就是 multi-phase-plan 的适用边界先划定适用边界。这个 playbook 的第一条规则是反直觉的当改动只涉及一两个文件、路径显而易见时直接跳过规划流程说一句不需要计划然后停手。它不打算为小改动支付仪式成本。它真正服务的是两类任务一类是跨阶段的长期工作迁移、系统重构、跨模块的多部分改动一类是多 PR 叠加交付——多个 PR 之间存在依赖关系后一个要叠在前一个的分支上而不是都从 main 上开花。源码中的路由逻辑写得很清楚poteto-mode的 Non-negotiables 会把大型或跨切面的改动路由到这里同时与figure-it-out、orchestrate划清界限——单次定制运行走 figure-it-out多日多 PR 的常驻项目走 Orchestrate而 multi-phase-plan 负责的正是一个规划文件、一串有依赖的 PR、逐章验收这一档。支撑它成立的核心理念只有一句话写在 playbook 开头You own the plan, not the code. The plan is a checklist an owner runs box by box and the operator audits from the evidence.The plan is the deliverable.规划者拥有的不是代码而是计划本身。计划不是给执行者看的愿景文档而是一份执行者逐框打勾、操作者凭证据审计的清单。这正是它区别于普通任务分解的地方计划即交付物代码是这份交付物的自然产出物。7 步无代码规划流程从零写出一份可执行清单multi-phase-plan 把规划阶段压缩为 7 个步骤全程不写业务代码产出是一份结构化 Markdown 计划文件。逐条对照源码第 1 步判定边界。一两个文件、方案明显的改动直接跳过见上文。这是懒惰协议原则principle-laziness-protocol的体现不为不需要计划的任务支付规划成本。第 2 步用原型先解决分歧。规划阶段如果有悬而未决的问题不许靠问人来解决而是跑 prototype.md 做一次性验证——哪个布局、哪种交互、哪个时序用可观察的证据定。原型的分支、SHA 和截图全部留档进 Appendix A。只有任何实验都无法裁决的产品或偏好问题才允许问操作者而且要给出选项而非开放式提问。这正是 never-block-on-the-human 原则的落地可逆的工作直接推进把结果摆出来让人纠偏。第 3 步子代理探索守住上下文窗口。探索交给subagent_type: pstack:poteto-agent的子代理每个子代理返回文件指针、代码约定、测试命令和入口点禁止把大段代码内联回主线程。这是 guard-the-context-window 原则的直接应用上下文窗口是有限的不可再生资源主线程只保留摘要。第 4 步复制骨架逐项填空。这是整个流程的骨架所在。计划文件默认写入代理存储~/.claude/orchestrate/slug/docs/并强制保持每个标题、每个子块的出现顺序。核心约束有三条一个 PR 一节一节就是一次独立变更配自己的证据sequence-verifiable-units 原则在 How to read this 里指名执行 playbook——autopilot-full.md独立 PR 队列、操作者逐个点击合并还是autopilot-stack.md线性基分支栈、操作者统一落地执行 playbook 全权负责 base 选择、拓扑变更与合并权限常驻型项目则改走orchestrate.md。第 5 步先过 technical-writing再过 unslop。计划正文是单一 Diátaxis 模式how-to附录放解释与参考。每个标题陈述任务或结论禁长破折号、禁句中冒号。pstack 对文字纪律的执念在这里和代码纪律同等强度。第 6 步机器检查。这是把计划质量从口头要求变成硬性门禁的关键运行node skills/poteto-mode/scripts/check-plan.mjs plan.md脚本输出的每一行报错都必须修掉。这是 encode-lessons-in-structure 原则的标本——不用更多文字教导而是用脚本强制结构。第 7 步交接停手。汇报计划路径和脚本输出然后停。执行只从操作者的明确 go 开始由计划点名的执行 playbook 接管。check-plan.mjs 的检查项本身就泄露了这套方法的全部纪律要求。它校验必须有 H1 标题How to read this 必须包含一个框就是一个工作单元只有证据存在才能打勾以及完整验证规则原文Program checklist 必须按顺序包含 Arm the program、Spawn owners、PR mechanics、Verdict and merge、Boot recipe 五个 H3 块每个 PR 章节的子块必须精确按Depends on. → Files. → Build. → You see. → Verify, unit. → Verify, live. → Verify, perf. → Review gate. → Merge.排列live 车道必须恰好是 Lane 1 到 Lane 10每条车道必须命名截图路径并带 pass 谓词perf 块必须依次是 Metric. → Probe. → Baseline. → Rule.。任何偏离都直接以非零退出码拒绝这份计划。unit/live/perf 三重验证为什么测试通过不算验证通过这套方法最反行业直觉的地方在于它的验证规则。在 multi-phase-plan.md 和 check-plan.mjs 里同一句话以完全相同的措辞出现且要求每个验证块必须以它开头Tests alone are not sufficient verification. A PR is verified only when its unit, live, and perf boxes are all checked.一个 PR 只有在单元、实机、性能三个框全部打勾之后才算验证通过。这句话是验证规则的唯一权威表述check-plan.mjs 甚至会逐字检查每个 Verify 块是否以它开头——改一个字都过不了脚本。三个层次分别验证什么源码给出了非常具体的规格unit单元命名测试文件和它新增的用例给出运行命令。这是三个层次里唯一传统的部分也是被明确判定为不充分的部分。live实机这是强制块没有例外。在 PR head 上用配置的swarm workers模型跑 10 条车道每条车道驱动真实界面通过 driver skill保存截图并带 pass 谓词。其中 Lane 1 是对 trunk 的回归车道——在同一负载场景下分别跑 trunk 和 head。如果 trunk 本来就没有这个功能车道要记录这一事实转而验证diff 新增的行为 用户等待的最终状态而不是伪造一个 trunk 结果。这与 prove-it-works 原则一脉相承验证真实工件不验证代理红色不是测量结果断言内容才是。perf性能双面门禁。trunk 和 head 必须都产出同名指标先测 trunk baseline再以交错方式测 head。如果 trunk 缺功能则要为 diff 新增的工作单独设定绝对预算并覆盖用户等待的端到端状态——严禁在两个不可比场景之间声称一个比率。这与 explain-the-number 原则呼应报告数字之前先排除它测的不是你以为的那个东西。最后还有一道 review gate改变交互的 PR 必须走人工审查——操作者在聊天里看截图和 30–60 秒视频后才点合并不改变交互的 PR 则写**Review gate.** None. PR id is not review-gated.不挂任何框。机器验证与人工判断的边界被划得清清楚楚。pstack 概览图展示了这套技能栈的全貌一根 skills 树、多个 agent harness 共享、poteto-mode 作为路由入口而 multi-phase-plan 只是其中负责规划层的一环它产出的计划文件会继续被 swarm、show-me-your-work、shipping 等技能接力。一个多 PR 叠加任务的完整拆解以迁移 A → B为例把上述机制落到一个具体场景假设要完成一次把组件库从 A 迁移到 B的大改造涉及 30 个文件、3 个可叠加 PR。用 multi-phase-plan 骨架写出来的计划会长这样。计划头部少于十行说明改什么、为谁改、程序执行的规则、PR 的先后顺序。例如将 30 个调用点从 A 迁移到 B消除双依赖窗口。PR #1 与 #2 独立先行PR #3 依赖前两者。How to read this声明一个框就是一个工作单元每个框点名验证它的证据——文件、日志行、截图、测试运行或 SHA只有证据存在才能打勾。并指名执行 playbook本例选autopilot-stack.md三个 PR 有依赖关系、操作者要求先审后落地声明谁合并、哪些 PR 是操作者自己的待办停在 merge-ready。Program checklist分五个 H3 块Arm the program向操作者陈述协议与计划后停手只在明确 go 后执行把计划路径、PR 顺序、验证规则、合并人、完成条件写进 standing orders每小时用真实/loop动态模式武装审计 tick用固定提示词逐字驱动收到 hold 或 stand-down 立即向每个 owner 下发零写入指令。Spawn owners每个 PR 一个 owner按依赖图启动——PR #1 与 PR #2 独立先行都从 main 分支PR #3 在 PR #2 之后。锁定文件边界如PR #1 只触碰legacy-imports/守住 review gate。PR mechanics一次性解析 forge默认ghcommand -v origin成功且可解析仓库时用origin pr开 ready PR 而非 draftstack 子 PR 以父分支为 basepush 前跑一次 lint 和 typecheck每次 commit 前跑/deslopreview 前跑/no-comments按bugbot-triage.md处理每条 review-bot 评论。Verdict and merge在 code-ready head SHA 及每次改动 patch 的 push 之后跑 swarm——一条 gate 车道、PR 自己的 10 条 live 车道、perf 车道外加两条以上互不重叠的 audit 车道读 diff 和 receipts不信任 PR 描述只有所有车道 PASS 才清理新 head 换新 swarm 与新 verdict受shipping.md的 patch-id 规则约束。Boot recipe每条 live 车道在 PR head 自己的 worktree 里跑给出git fetch origin head-branch git checkout head SHA、启动后端与界面等待 ready、只通过 driver skill 的命令输入、截图统一存/tmp/swarm-pr-id/worker-n/slug.png。每个 PR 一节严格按九个子块展开。以PR #2迁移渲染管线为例Depends on.PR #1。Files.编辑render/下三个文件删除legacy/下一个文件。Build.一个变更命名符号与文件例如将LegacyRenderer.render()替换为BRenderer.render()并迁移其调用点。You see.一个可观察结果带精确日志行或界面状态。Verify, unit.测试文件与新增用例运行命令。Verify, live.以验证规则原文开头Lane 1 回归车道对 trunk 与 head 跑同一负载场景本例 trunk 无新渲染器则记录该事实并验证 diff 新增行为 用户等待的最终渲染状态Lane 2–10 是具体场景、截图 slug、pass 谓词。Verify, perf.Metric.trunk 与 head 都测的首帧渲染耗时、Probe.交错执行的命令、Baseline.先记录 trunk 值、Rule.head 对 trunk 的数值与失败阈值。Review gate.本 PR 改变交互复制车道截图、录 30–60 秒视频、贴到聊天、停在 merge-ready 等操作者点击。Merge.root 在确切 head SHA 上的干净 verdict、bugbot triage 完成、base 与 verdict 在当前执行 playbook 与 patch-id 规则下有效、owner 自己 squash-merge或 root 追加到基分支栈由操作者自底向上落地。Close the program确认每个框都有证据打勾按执行 playbook 要求回复操作者。四个附录兜底Appendix A 记录原型证据分支、SHA、产物链接以及仍未证实的悬而未决问题Appendix B 记录被否决的替代方案与否决原因Appendix C 记录每个风险落在哪个 PR、owner 盯什么Appendix D 是链接与阅读清单指明哪些 PR 需要how与interrogate技能、按 show-me-your-work 的格式留决策轨迹decisions.tsv每个决定一行时间、阶段、决定、理由、证据、结果。这套方法真正改变的是什么回到开头的问题为什么大改造总让人不敢放手因为放手的代价不可预测——你不知道代理在哪一步跑偏、哪个假设错了、哪个 PR 悄悄引入了回归。multi-phase-plan 把不可预测性拆掉了计划文件是机器检查过的结构化清单每个框绑定具体证据每个 PR 在合并前必须同时过单元、实机、性能三道门改变交互的 PR 还保留人工审查。你要做的不是盯着代理干活而是对照清单查证据、看截图、点合并。计划即交付物这句话把责任从信任代理转移到了审计证据上——而这正是任何工程化 AI 工作流最终都要到达的位置。【免费下载链接】pstack-claudeClaude Code, Codex, Copilot, Pi, OpenCode, Gemini, and Prime Agent versions of Potetos pstack. Rigorous agent workflows with Cursor primitives translated for other harnesses.项目地址: https://gitcode.com/GitHub_Trending/ps/pstack-claude创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
