ccg-workflow 安全重构策略 refactor-safely 详解：五阶段状态机、测试基线与双模型迭代审查

【免费下载链接】ccg-workflow多模型协作工作流引擎 — /ccg:go 一个命令AI 自动分析意图、选择策略、编排 Codex Gemini Claude 协作执行项目地址https://gitcode.com/gh_mirrors/cc/ccg-workflow点击查看免费下载在 ccg-workflow 中/ccg:go会根据任务类型与复杂度自动选择执行策略其中重构类任务复杂度 M 及以上会命中refactor-safely策略。本文以 refactor-safely 策略文件 为主体完整拆解其理解 → 基线 → 规划 → 增量执行 → 迭代审查的五阶段状态机、每阶段的 Gate 条件与输出格式并结合引擎的模型路由器、Hook 状态追踪与校验 Skill 源码说明该策略如何做到行为不变、每步可验证、失败即停止。策略定位从 /ccg:go 决策矩阵到任务创建入口命令 go.md 定义了 CCG 引擎的智能路由先获取项目上下文git status、项目配置文件、目录结构再对任务做类型分类、复杂度与风险评估最后按决策矩阵选择策略。其中重构行的路由规则为类型 \ 复杂度SML / XLrefactordirect-fixrefactor-safelyrefactor-safely也就是说复杂度 S 的小重构走轻量的direct-fixM 及以上才启用refactor-safely。附录策略一览也标注该策略外部模型可选适用于代码重构需要安全保障的场景。进入该策略前还有一个硬性前置复杂度 ≥ M 且非 git-action 时必须先创建任务目录.ccg/tasks/{task-name}/并写入task.json含status、strategy、currentPhase、nextAction、gate、branch等字段再Read加载策略文件。从源码结构看这正是 workflow-state Hook 能逐轮注入ccg-state面包屑Task / Strategy / Phase / Gate / Next的前提——没有task.json就没有状态追踪。适用条件与 L/XL 前置加载策略文件开头明确了适用条件复杂度 M 或以上重构、整理、提取、简化类任务需要保证行为不变。当复杂度达到 L/XL 时策略要求前置加载模型路由器Read(~/.claude/.ccg/engine/model-router.md)model-router.md 提供动态模型选择框架从用户配置~/.claude/.ccg/config.toml的[routing]区块提取frontend.primary默认antigravity与backend.primary默认codex等字段并按阶段给出模型与角色提示词analyzer / architect / reviewer / debugger / builder的搭配。对重构策略有两个关键影响审查阶段始终双模型交叉验证backend 模型 $BACKEND/reviewer.mdfrontend 模型 $FRONTEND/reviewer.md两者并行 spawn 后综合结果纯 Claude Code 模式优先判定若frontend.primary和backend.primary都是claude则不调用 codeagent-wrapper、不启动任何外部模型 CLI所有原外部模型角色改用 Agent Teams 子代理完成如双模型交叉审查 spawn 两个独立的 reviewer Agent。此时交叉验证的收益来自独立上下文 不同视角且零外部依赖。工作流状态机五个 Phase 的 Gate 链策略核心是一张五阶段状态机每完成一个阶段都要回顾对应[phase-state:N]块确认 Gate 已满足并输出 Next告知用户下一步。完整状态定义如下[phase-state:1-understand] 当前阶段理解现有代码 Next: 映射完依赖关系后建立测试基线 [/phase-state:1-understand] [phase-state:2-baseline] 当前阶段建立基线 Gate: 代码已理解 ✓ Next: 基线建立后进入规划 [/phase-state:2-baseline] [phase-state:3-plan] 当前阶段规划重构步骤 Gate: 测试基线已建立 ✓ Next: 计划确认后逐步执行 [/phase-state:3-plan] [phase-state:4-execute] 当前阶段增量执行 Gate: 用户已确认计划 ✓ Next: 每步执行后验证测试通过 [/phase-state:4-execute] [phase-state:5-verify] 当前阶段最终验证 Gate: 所有步骤已执行 ✓ Next: 全部测试通过后报告结果 [/phase-state:5-verify]Gate 是阶段间的硬性检查点。按 phase-guide.md 的 § 2 规范Gate 分三类数据 Gate前序阶段是否产出必要数据、确认 GateHARD STOP必须等待用户明确确认、质量 Gate产出物是否达标。Gate 失败时须说明缺失什么并给出补救建议不可绕过标记[required]的阶段不可跳过。阶段详解Phase 1: 理解现有代码 [required]Task 更新currentPhase → 1-understandnextAction → 读取代码映射依赖。本阶段做四件事读取所有涉及重构的文件映射依赖关系——谁调用了这些代码谁被这些代码调用识别公共 API / 接口边界这些不能轻易改变记录当前行为特征。这一步是后续行为不变承诺的依据只有先摸清调用边界和现有行为增量执行阶段才能判断某次改动是否越界。Phase 2: 建立测试基线 [required]基线是重构安全性的锚点。步骤为运行现有测试pnpm test/go test/pytest等按项目技术栈选择记录测试结果作为基线如果没有相关测试 → 告知用户建议但不强制先补测试输出基线状态 测试基线 通过: [N] 个 失败: [M] 个已有的非重构引入 覆盖: [相关模块的测试覆盖情况]注意失败: M 个已有的非重构引入这一项的设计意图重构验收标准是不引入新的失败而不是测试全部通过。已有的失败被明确记录为基线的一部分避免把历史债务误判为重构事故。Phase 3: 规划增量重构步骤制定增量重构计划原则是每一步都能独立通过测试。计划输出格式 重构计划 ## 目标 [重构目标和预期效果] ## 步骤每步独立可验证 1. [步骤描述] — 影响文件: [...] 2. [步骤描述] — 影响文件: [...] ... ## 不变量 - [不应该改变的行为/接口]不变量一节显式列出本次重构不应该改变的行为与接口与 Phase 1 识别的 API 边界呼应。对于 L/XL 任务可选调用外部模型做架构审查即通过模型路由器 spawn backend 模型 architect角色。最后展示计划、等待用户确认——这是 Phase 4 的 Gate确认 Gate / HARD STOP。Phase 4: 增量执行Task 更新currentPhase → 4-executenextAction → 逐步执行重构。逐步执行每步之后应用变更运行测试测试通过 → 继续下一步测试失败 →立即停止分析原因修复或回退。每步报告格式Step [N/M]: [描述] — ✅ 测试通过 / ❌ 测试失败这个每步即测、失败即停的循环把回归风险压缩到单步粒度任何一步引入的行为偏差都会当场暴露且修复或回退的成本只有一个步骤的 diff而不是一整批大改。Phase 5: 迭代审查 [Ralph Loop]Phase 5 不是一次性审查而是引用 phase-guide.md § 10 的Ralph Loop 迭代审查协议最多 3 轮完整流程为运行完整测试套件对比基线确保不引入新的失败获取变更git diff全量输出并行调用双模型审查run_in_background: true每轮 spawn 新调用、干净上下文backend 模型 reviewer 角色 — 关注安全、性能、错误处理、行为一致性frontend 模型 reviewer 角色 — 关注可访问性、设计一致性如涉及前端等待双模型结果综合审查意见质量关卡必须逐个调用 Skill不可跳过不可用自己的判断替代调用 Skillverify-quality— 等待报告调用 Skillverify-security— 等待报告调用 Skillverify-change— 等待报告综合双模型审查与质量关卡按严重度分级出报告用户决定必须等待有 Critical →发现 N 个 Critical 问题。修复后再审一轮[Y/n]无 Critical →审查通过。需要再审一轮[y/N]用户选择继续 → 修复后回到 Round N1用户选择停止 → 退出审查循环git diff展示全部变更对比基线确认无回归输出结果✅ 重构完成 步骤: [N] 步全部通过 变更: [文件数] 文件[行数] 行 测试: 基线 [N] 通过 → 重构后 [N] 通过 审查: [N] 轮[Critical: N, Warning: N, Info: N] Next: /ccg:commit 提交每轮审查的进度追加到.ccg/tasks/{task-name}/fix-log.jsonl。从 phase-guide.md § 10 的源码级规范看Ralph Loop 有几条关键规则值得注意每轮审查必须 spawn 新 Agent不复用上一轮上下文避免上下文污染越修越烂fix-dev 也是新 Agent从磁盘读取最新代码状态、只修分配的问题最多 3 轮MAX_ROUNDS3超过说明问题根深应回退到规划阶段用户始终有决定权不自动循环。fix-log.jsonl每轮追加一行 JSON例如{round: 1, critical: 2, warning: 5, fixed: [file1:issue, file2:issue], ts: ISO} {round: 2, critical: 0, warning: 3, fixed: [file3:issue], ts: ISO}三个质量关卡并非空架子在仓库中都有具体实现verify-quality通过node scripts/quality_checker.js 扫描路径自动计算圈复杂度阈值 ≤ 10、函数长度≤ 50 行、文件长度≤ 500 行、参数数量≤ 5、嵌套深度≤ 4等指标并检测重复代码、魔法数字、死代码等异味。它对重构完成场景有明确的自动触发定义与 Phase 5 的关卡调用正好对应verify-change通过node scripts/change_analyzer.js分析变更的文件分类、模块识别、文档同步状态与测试覆盖代码变更 50 行但 DESIGN.md 未更新、 30 行但无测试更新等情况会触发警告verify-security安全扫描关卡与双模型审查中 backend reviewer 关注的安全、错误处理形成机器 模型的双重覆盖。Spec Evolution 与任务归档审查通过后、任务归档前策略要求执行 phase-guide.md § 8 的Spec Evolution Protocol分析本次重构的git diff提炼可复用的重构模式和架构约定如有值得记录的经验 → 草拟 Spec 条目展示给用户确认后追加到.ccg/spec/{domain}/index.mdSpec 不可静默写入必须用户确认无值得提炼的经验 → 跳过不要强行凑条目。最后更新status → archived并归档任务mkdir -p .ccg/tasks/archive/$(date %Y-%m) mv .ccg/tasks/{task-name} .ccg/tasks/archive/$(date %Y-%m)/ git add .ccg/tasks/ git commit -m chore: archive ccg task按月份归档使.ccg/tasks/目录保持可检索进行中的任务在顶层历史任务进archive/YYYY-MM/。引擎层的支撑机制策略文件本身是纯 Markdown 协议其可靠性依赖引擎的几个底层机制1. 状态面包屑与死循环检测。workflow-state.js 在每条用户消息时运行UserPromptSubmit Hook读取活跃任务的task.json写入最近 10 轮的滚动缓冲.turns.json然后注入ccg-state面包屑第 26-50 行。检测规则是连续 3 轮phasenextAction完全相同即判定死循环并在面包屑中注入⚠️ LOOP DETECTED警告与 Break-Loop Protocol停止当前重复动作 → 5 Why 根因分析 → 必须变更nextAction连续 2 次触发则强制暂停请用户介入。这对增量执行阶段特别重要——如果某一步反复修复-失败Hook 会强制流程跳出原地打转。2. 错误恢复与策略升级。phase-guide.md § 5 规定了错误恢复表外部模型调用失败按路由器重试、测试失败修复后重跑、用户要求中止则立即停止并报告已完成工作§ 4 规定策略只能升级、不能降级除非用户明确要求。重构中若发现这是架构级问题而非重构引擎应明确告知并建议升级如升级到full-collaborate经用户确认后从新策略 Phase 1 开始已完成的分析可复用。3. 等待与重试规则。按 model-router.md § 4双模型并行审查中 frontend 模型失败最多重试 2 次间隔 5sbackend 模型运行中需保持轮询可能 5-15 分钟3 次全败则降级为单模型模式并告知用户。这保证 Phase 5 的双模型交叉审查在单侧故障时不会让整个流程卡死。铁律MUST NOT策略文件底部的铁律是整个流程的不可妥协约束不可一次性大改— 必须拆分为增量步骤每步必须验证测试— 测试失败立即停止保持行为不变— 除非重构目标明确包含行为变更不扩大范围— 只重构用户指定的范围。总结一次完整重构的执行链路把各环节串起来/ccg:go 重构 xxx 模块触发该策略后的完整链路是路由go.md 判定为 refactor 类型、复杂度 ≥ M → 创建.ccg/tasks/{task-name}/与task.json→ 加载refactor-safelyL/XL 时先加载 model-router.md理解读代码、映射依赖、划定 API 边界更新currentPhase → 1-understand基线跑全量测试输出 测试基线把历史失败与重构引入的失败区分开规划输出 重构计划目标 / 独立可验证的步骤 / 不变量HARD STOP 等待用户确认增量执行每步应用变更 → 跑测试 → 报告 Step [N/M]失败立即停止Ralph Loopgit diff 双模型并行审查 verify-quality / verify-security / verify-change 三道关卡按 Critical / Warning / Info 分级用户决定是否再修再审最多 3 轮每轮新 Agent收尾git diff全量展示、对比基线确认无回归、Spec Evolution 提炼经验、输出✅ 重构完成报告、按月归档任务。这套设计的核心思想可以概括为一句话用测试基线定义行为不变用增量步骤把回归风险限制在单步 diff 内用干净上下文的多模型 Skill 关卡把审查从主观判断变成可分级、可追踪fix-log.jsonl、由用户掌握终止权的过程。以上即为refactor-safely策略在 ccg-workflow 中的完整机制与实操要点。赞分享【免费下载链接】ccg-workflow多模型协作工作流引擎 — /ccg:go 一个命令AI 自动分析意图、选择策略、编排 Codex Gemini Claude 协作执行项目地址https://gitcode.com/gh_mirrors/cc/ccg-workflow点击查看免费下载相关推荐ccg-workflow guided-develop 策略详解中等复杂度功能开发的六阶段状态机、双模型并行分析与 Ralph 迭代审查ccg workflow guided develop 策略详解中等复杂度功能开发的六阶段状态机、双模型并行分析与 Ralph 迭代审查 本文以 ccg woccg-workflow 阶段执行规范详解Gate Check、死循环检测与 Ralph Loop 迭代审查机制ccg workflow 阶段执行规范详解Gate Check、死循环检测与 Ralph Loop 迭代审查机制 本文围绕 ccg workflow多模型协ccg-workflow 的 debug-investigate 策略解析五阶段状态机与双模型并行诊断如何定位原因不明的复杂 Bugccg workflow 的 debug investigate 策略解析五阶段状态机与双模型并行诊断如何定位原因不明的复杂 Bug 对于「报了 500、堆栈上一篇嵌入式设备福音OpenTracker在树莓派上的性能调优与应用案例下一篇MxEngine渲染技术深度剖析PBR、全局光照与后期特效实现创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考