ccg-workflow direct-fix 策略详解:零开销四阶段状态机与单文件 Bug 的最小化修复

原创2026-10-09 12:55:201,910 阅读

ccg-workflow direct-fix 策略详解:零开销四阶段状态机与单文件 Bug 的最小化修复

direct-fix 是 CCG 工作流引擎(ccg-workflow)内置的 10 个执行策略中最轻量的一个,专为「范围清晰、单文件、<30 行变更」的简单 bug 修复设计。本篇以 direct-fix 策略文件 为主体,完整拆解其适用条件、四阶段状态机(定位 → 诊断 → 修复 → 验证)与升级规则,并结合 CCG 智能入口 /ccg:go、通用阶段指导 与 安装器源码 说明它如何被路由、安装与执行。读完你可以掌握:引擎如何为 S 级 bug 任务自动选择该策略、每个阶段的 Gate 检查点是什么、以及策略文件从仓库模板到 ~/.claude/.ccg/engine/strategies/ 的部署链路。

一、direct-fix 的定位:零外部模型开销的轻量修复路径

项目 README 将引擎的 10 个内置策略汇总为一张选型表,其中 direct-fix 一行明确标注:适用「Simple bug, single file」,外部模型一栏为「—」,Agent Teams 一栏同样为「—」,并配以一句话概括——「Simple tasks run fast with zero overhead」(简单任务零开销快速执行)。

这与 direct-fix.md 文件头部的定义完全一致:

适用于范围清晰、单文件的简单 bug 修复。Claude 独立完成,不调用外部模型。

所谓「零开销」,具体含义是:

  • 不加载模型路由器:model-router.md 中定义的 codeagent-wrapper 外部模型调用模板(Codex / Gemini / Grok 等 CLI 并行调用)在 direct-fix 中完全用不到。作为对比,guided-develop 策略 的 Phase 3 就要求「M 复杂度必须调用双模型并行分析,不可只调一个,不可跳过」,两者的重量级差距一目了然;
  • 不创建任务状态文件:/ccg:go 命令明确规定「复杂度 S → 跳过任务创建(保持轻量)」,因此 direct-fix 任务不会在 .ccg/tasks/ 下生成 task.json;
  • 由 Claude 单模型端到端完成:从定位、诊断到修复、验证全部由 Claude 独立完成,不 spawn 子代理、不启动第三方 CLI。

适用条件

策略文件给出的三个硬性适用条件:

条件 要求
复杂度 S 级(单文件,<30 行变更)
问题信息 错误信息或复现路径明确
风险 low 或 medium

这里的复杂度分级继承自 /ccg:go 的评估标准:S = 单文件变更、范围清晰、预估 <30 行;M = 2-5 文件单模块;L = 5+ 文件跨模块;XL = 架构级变更。风险评估中 low 指「无生产影响、可逆、有测试覆盖」,medium 指「修改现有行为,需要测试验证」。三条同时满足才应走 direct-fix;任何一条不满足,都应触发后文「升级规则」中的策略切换。

二、路由机制:/ccg:go 如何选中 direct-fix

用户不需要手动指定策略。/ccg:go(见 go.md)作为 CCG 智能入口,在 Phase 1 完成意图分析(任务类型、复杂度、风险、领域四项评估)后,用一张决策矩阵选出策略:

类型 \ 复杂度 S M L / XL
bug-fix direct-fix debug-investigate debug-investigate
refactor direct-fix refactor-safely refactor-safely
feature quick-implement guided-develop full-collaborate

从表中可以看出,direct-fix 有两条进入路径:

  1. bug-fix + S 复杂度——最典型的路径,如「修复某文件里的一个越界报错」;
  2. refactor + S 复杂度——例如把单文件里的一个函数提取重命名,范围同样收敛在单文件内。

两个关键的路由细节值得注意:

  • 风险修正:go.md 规定「如果风险为 high 且策略不含外部模型审查,升级一档(如 direct-fix → debug-investigate)」。因为 direct-fix 没有外部模型交叉审查环节,高风险任务(API 契约变更、数据库迁移、认证/加密逻辑)会被自动抬升到带双模型诊断的 debug-investigate 策略;
  • 用户可覆盖:展示分析结果后,若用户对自动选择有异议(例如坚持「小修一下」),引擎接受用户覆盖并加载指定策略;同时 Phase 0 还内置了「直接做 / just do it / 小修一下」等逃生舱短语,可跳过分析直接由 Claude 处理。

策略文件的安装与加载位置

策略文件在仓库中位于 templates/engine/strategies/,但 Agent 运行时读取的是用户主目录下的部署副本。安装器源码 展示了这一过程:安装时将 templates/engine/ 整体复制到 ~/.claude/.ccg/engine/(含 strategies/ 子目录),并且复制时启用变量注入({ inject: true }),把模板中的占位变量替换为用户配置中的实际模型名。

因此 direct-fix 的运行时加载语句是:

Read("~/.claude/.ccg/engine/strategies/direct-fix.md")

(/ccg:go 在 Phase 3 执行策略前按此路径加载;仓库内的 direct-fix.md 是该部署副本的源模板。)

由于 S 级任务不创建 task.json,workflow-state Hook 的 getActiveTask 找不到活跃任务时会直接 exit(0),不注入 <ccg-state> 面包屑。从源码结构看,这正是 direct-fix 保持「零开销」的另一面:它不依赖任务状态追踪与死循环检测机制,全部阶段流转由策略文件内部的 [phase-state] 块在会话中自我驱动。

三、工作流状态机:四阶段与 Gate 检查点

direct-fix.md 的核心是一段「工作流状态机」声明,由 4 个 <a href="https://link.gitcode.com/i/8c360bfd3adbc4cc5dc579c469131ac9" target="_blank">phase-state:N-name] 块构成。这些标记是策略文件的执行骨架,配合 [phase-guide.md § 1 阶段状态自检 的规范使用:每完成一个阶段,回顾对应块,确认 Gate 条件已满足,然后输出 📍 Next: [具体动作] 告知用户下一步;带 [required] 标记的阶段不可跳过。

策略文件原文的状态机定义:

[phase-state:1-locate]
当前阶段:定位问题代码
Gate: 项目上下文已获取 ✓(由 /ccg Phase 1 完成)
📍 Next: 找到问题代码后进入诊断阶段
[/phase-state:1-locate]

[phase-state:2-diagnose]
当前阶段:诊断根因
Gate: 已找到相关代码 ✓
📍 Next: 确定根因后进入修复阶段
[/phase-state:2-diagnose]

[phase-state:3-fix]
当前阶段:应用修复
Gate: 根因已确定 ✓
📍 Next: 修复完成后进入验证阶段
[/phase-state:3-fix]

[phase-state:4-verify]
当前阶段:验证修复
Gate: 修复已应用 ✓
📍 Next: 验证通过后报告结果,建议提交
[/phase-state:4-verify]

四个 Gate 全部是数据型 Gate(检查前序阶段是否产出了必要数据),没有一个 HARD STOP 确认 Gate——这与 guided-develop 的 Phase 4「计划审批 HARD STOP,必须等待用户确认」形成鲜明对比。direct-fix 追求的是在风险可控前提下的快速闭环:唯一需要等待用户确认的时机是升级策略时(见第五节)。phase-guide 对 Gate 执行还有统一兜底规则:Gate 失败时须说明缺失什么、给出补救建议,不可绕过。

四、阶段详情:定位、诊断、修复、验证

Phase 1: 定位 [required]

目标是从用户的一句话描述收敛到具体的问题代码,三步走:

  1. 提取关键信息——从用户描述中结构化出三要素:错误消息(如果有)、发生位置(文件、功能、页面)、复现步骤;
  2. 搜索相关代码,按信息完备度选择手段:
    • 有错误消息 → Grep 搜索错误文本(错误字符串往往是唯一且可精确匹配的锚点);
    • 有文件/函数名 → 直接 Read 目标文件;
    • 信息不足 → 用 MCP 搜索工具或 Grep 按关键词搜索;
  3. 读取找到的代码文件,理解上下文——不是只看报错行,而是把所在函数的输入、调用方与依赖一并读入。

这一步的 Gate 前置条件是「项目上下文已获取」,由 /ccg:go 的 Phase 1.1 在策略加载前完成(git status、读项目配置文件、浏览目录结构),所以策略执行时不必重复做项目级探查。

Phase 2: 诊断 [required]

定位到代码不等于找到根因。Phase 2 要求:

  1. 分析代码逻辑,找到 bug 的根因;
  2. 如果存在多个可能原因,按可能性排序(而不是只押注第一个假设);
  3. 用固定格式输出诊断结论,供用户快速核对:
🔍 诊断
  文件: [path:line]
  根因: [一句话说明]
  修复方案: [一句话说明]

这个诊断块是进入 Phase 3 的 Gate 凭证(「根因已确定 ✓」)。策略文件把本阶段标记为 [required],并在铁律中强调:即使"一眼看出问题",也要经过 Phase 2 确认根因,不可跳过诊断直接改代码。这一步的实质价值在于把「修复方案」从隐含动作变成显式可审查的产物——用户在这一行就能判断 Agent 是否找对了病灶,而不必等到 diff 出现。

Phase 3: 修复

修复阶段只有一条主线——应用最小修复(只改必要的部分),外加测试约定:

  • 如果项目有测试 → 运行相关测试;
  • 如果没有测试 → 建议但不强制添加(保持 S 级任务的轻量定位,不因补测试而把小修拖成大任务)。

Phase 4: 验证

验证阶段是「交付前最后一道闸」,包含四个动作:

  1. 用 git diff 展示全部变更;

  2. 按三个问题自查修复合理性:

    • 变更范围是否最小?
    • 是否引入新问题?
    • 边界条件是否考虑?
  3. 如果修复涉及认证 / 输入处理 / 安全相关代码 → 调用 /verify-security 安全扫描。对应仓库中的 verify-security 技能(配套扫描脚本 security_scanner.js),与 phase-guide § 10 Ralph Loop 中把 verify-security / verify-quality / verify-change 列为质量关卡的约定一致;

  4. 用固定格式输出结果:

✅ 修复完成
  变更: [N] 文件,[M] 行
  根因: [简述]
  修复: [简述]
  📍 Next: 可以用 /ccg:commit 提交

末尾的 Next 指引把流程平滑衔接到 commit 命令,形成「修复 → 验证 → 提交」的完整闭环。

五、升级规则与三条铁律

升级规则:复杂度膨胀时的出口

direct-fix 是「窄门策略」——它假设问题收敛在单文件内,但实际排查中范围经常膨胀。策略文件为此预设了三个出口:

触发条件 升级目标 理由
涉及 3+ 文件 guided-develop 多文件变更需要规划与文件级任务拆分
原因不明,需要深度调试 debug-investigate 单模型单遍排查不足以定位,需要双模型并行诊断
涉及架构问题 refactor-safely 表面是 bug,实质是结构问题,需要重构级保障

触发时机被限定在 Phase 1-2(定位与诊断阶段)——也就是说,一旦在读懂代码、锁定根因的过程中发现上述情况,就应当停止硬闯并建议升级,而不是带着「单文件假设」继续改代码。

升级动作本身受 phase-guide § 4 策略升级规则 约束:

  1. 明确告知用户:当前策略为 [名称],但发现 [原因],建议升级到 [目标策略];
  2. 等待用户确认;
  3. 确认后 Read ~/.claude/.ccg/engine/strategies/[target].md;
  4. 从新策略的 Phase 1 开始(已完成的分析工作可复用)。

以及一条全局约束:只能升级,不能降级(除非用户明确要求)。direct-fix 文件本身的表述与此一致——「告知用户并等待确认后切换策略」。

铁律(MUST NOT)

策略文件底部列出三条不可违反的纪律:

  1. 不可在未读代码的情况下猜测修复方案 —— Phase 1 必须实际读取代码。禁止「凭经验先改一版试试」;
  2. 最小修复原则 —— 只改导致 bug 的部分,不做「顺手重构」。这与验证阶段「变更范围是否最小」的自查互为表里:最小化既是修改时的约束,也是验收时的标尺;
  3. 不可跳过诊断直接改代码 —— 即使「一眼看出问题」,也要经过 Phase 2 确认根因。

三条铁律的共同指向是同一个工程判断:小 bug 的代价不在「改」,而在「改错之后难以回溯」——强制读代码、强制诊断输出、强制最小 diff,正是把一次轻修变成一次可审查、可复述的变更。

六、direct-fix 与其他策略的对比定位

把 direct-fix 放回引擎全貌(README 策略总表 + go.md 附录策略一览),其边界可以概括为:

维度 direct-fix quick-implement guided-develop debug-investigate
任务类型 bug-fix / refactor(S) feature(S) feature(M) bug-fix(M/L/XL)
文件范围 单文件 单文件/组件 2-5 文件 不预设,排查后确定
外部模型 无 无 可选单模型 双模型并行诊断
Agent Teams 无 无 — —
用户确认点 仅升级时 — 计划审批(HARD STOP) 按策略定义
阶段数 4(定位/诊断/修复/验证) — 6(需求→上下文→分析→规划→实施→验证) 按策略定义

从源码结构看,这些策略共享同一套基础设施:同一目录(templates/engine/strategies/)、同一套 [phase-state] 状态机语法、同一套 Gate 规范(phase-guide)和同一套模型调用模板(model-router);direct-fix 只是其中把外部模型维度全部置零的最小实例。对使用者而言,这意味着只需描述问题(如「/ccg:go 修复 login 按钮点击后 500 报错」),路由、复杂度评估与策略加载都由引擎完成;direct-fix 的价值则在于:当任务确实够小时,它用四条铁律保证「快而不乱」,并在范围一旦膨胀时给出明确的升级出口。

登录后查看全文
ccg-workflow