pstack的Refactoring Playbook行为保持型重构的8步完整指南【免费下载链接】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-claudepstack 的refactoring playbook重构手册是 poteto-mode 中的一套行为保持型重构工作流结构可以变行为不能变。它通过先钉住行为契约、小步移动、最后证明等价的完整步骤帮你在 Claude Code、Codex、Pi 等 Agent 环境中安全地完成重命名、提取、合并、搬移等重构任务避免改完就崩的重构事故。什么是行为保持型重构Behavior-Preserving Refactoring在 pstack 中重构被定义为一种独立的 playbook与另外两类任务严格区分任务类型行为变化典型场景Feature功能新增行为加一个新按钮Bug fix修复纠正行为修一个错误结果Refactoring重构行为不变重命名、提取函数、去重、搬移模块这个定义写在 refactoring.md 的第一行核心原则只有一句话You own the contract. The structure changes. The behavior does not.你负责契约。结构会变行为不变。如果重构过程中发现了缺失的功能或真正的 bugplaybook 要求把它拆分出去单独处理先把结构性变更按钉住的契约交付而不是混在一个 PR 里。Refactoring Playbook 的8步重构流程完整流程定义在 refactoring.md共 8 步每一步都对应一条可复用的原则技能。第1步先钉住行为契约Pin the Behavior Contract在动任何结构之前先弄清楚这块代码现在的行为并用特征化测试、快照或等价性测试装置把它钉住用how技能先摸清受影响子系统的契约如果这块代码没有测试覆盖先写钉子再动结构特别注意类型检查和 lint 不算钉子它们证明不了行为没变。这是整个 playbook 最关键的一步——钉子是后面每一步的回归基准。第2步说出代码缺失的结构名称按照principle-model-the-domain源码命名代码缺失的结构状态机、类型化模型、注册表还是别的什么。如果形状已经很清晰且局部无聊但清晰的代码就保持原样。重塑必须删除分支或非法状态而不是增加间接层。第3步命名目标形状明确描述如果今天从零构建模块布局、类型和调用图应该长什么样。如果目标形状跨越了函数边界先运行architect技能做并行设计探索再动手搬移见 architect/SKILL.md。第4步先做减法再做加法在引入新形状之前先删掉死代码、合并只有一个调用者的包装器、去掉冗余校验器和孤儿引用。依据是 principle-subtract-before-you-add在复杂系统上叠加会复利式放大复杂度先删才能看到本质结构。同时遵守懒惰协议principle-laziness-protocol交付能到达目标形状的最小变更任何可能对将来有用的投机式清理直接回滚。第5步小步移动每步保持钉子常绿每次只做一小步行为保持型的改动改完立刻验证钉子仍然通过。对 API 重塑要求迁移所有调用者、并在同一波删除旧 APIprinciple-migrate-callers-then-delete-legacy-apis不留兼容垫片不保留新旧双路径逐一对照真实文件抽查每次重命名——重命名会悄悄漏掉字符串、文档文字和反向引用中的用法机械性编辑可以委派给子代理执行但要给出明确范围文件路径、被移动的名字、必须保持的行为。第6步证明行为没变而不只是能编译按 principle-prove-it-works 在真实产物上验证。较大的重塑要求做等价性检查三种形式任选其一一个 diff 新旧输出的脚本把记录的基线在新代码上回放在对应界面上通过驱动技能做冒烟运行。it compiles能编译在这个 playbook 里不算证明。第7步确认这个变更值得保留成功标准是降低读者认知负载principle-minimize-reader-load如果 diff 在任何地方都没有降低读者的追踪层级或隐藏状态直接回滚。判断标准很简单新读者能否在 30 秒内回答X 从哪里来什么能改变 X。第8步整理成小的有序提交按 principle-sequence-verifiable-units 重排成有序提交规范的顺序是先减法的提交 → 再重塑 → 最后后续清理每个行为保持型的切片在下一个开始之前都保持绿色让提交序列本身就能说服评审者。最后运行Opening a PRplaybookopening-a-pr.md完成交付。重构结束后要交付什么playbook 规定最终回复必须包含五样东西缺一项都不算完成结构改变了什么你用什么钉子锁住了它等价性证明是什么读者认知负载的差值降低了多少什么上线了、什么被回滚了。并且明确一条No new behavior没有新行为。快速上手与相关文件安装 pstack 后直接对poteto-mode说你的目标它会自动匹配到 Refactoring playbook例如use poteto-mode to extract the retry logic into its own module。各运行时的安装方式见 README.md完整技能清单与配置说明在 docs/reference.md。重构流程中会用到的一组原则技能全部位于 plugins/pstack/skills/ 目录下值得单独收藏principle-prove-it-works对真实产物验证拒绝能编译principle-subtract-before-you-add先减法后加法principle-sequence-verifiable-units把工作切成小而可验证的单元principle-migrate-callers-then-delete-legacy-apis迁移调用者后立即删除旧 APIprinciple-minimize-reader-load以读者认知负载衡量重构收益一句话总结pstack 的 refactoring playbook 把安全重构从一句口号变成 8 个可执行的步骤——先钉住行为契约再小步移动结构最后用等价性证明和读者负载来验收。照着它走重构就只是一次结构搬家而不是一场冒险。【免费下载链接】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），仅供参考