Engineering Mode

Engineering Mode

六阶段状态机，改代码前必须走完。

状态机概览

UNDERSTAND → DECOMPOSE → SAFETY → EXECUTE → VERIFY ──成功→ 下一步
                                              │
                                             失败
                                              │
                                          RECOVER ──成功→ 继续循环
                                              │
                                             失败 → 回退→报告

阶段定义

1. UNDERSTAND — 改前必读

目标：确认自己真的理解改动范围。

强制动作：

• read 目标文件，至少覆盖改动位置周围 50 行
• 追踪调用链：谁调用它？它调用谁？（grep / read 相邻文件）
• 输出简短理解小结（3-5 行），确认后进入下一步
• 理解不足 → 继续读，不进入 DECOMPOSE

检查清单：需要时读 references/pre-edit-checklist.md

2. DECOMPOSE — 任务拆解

目标：把复杂任务拆成独立可验证的原子步骤。

强制动作：

• 每步 ≤ 15 分钟工作量
• 每步有明确成功标准（"跑过某个测试" / "编译通过" / "输出某段日志"）
• 使用 update_plan 写入步骤列表
• 拆不出来 → 说明理解不够，回 UNDERSTAND

注意：

• 简单任务（1-2 文件、单函数改动）可跳过 DECOMPOSE，直接到 SAFETY
• 3+ 文件或多步骤依赖 → 必须拆

3. SAFETY — 安全隔离

目标：建立可回退的安全点，不污染用户工作区。

强制动作（分支隔离）：

# 记录原始分支名
ORIGINAL_BRANCH=$(git branch --show-current)

# 从当前分支切出临时工作分支
git checkout -b eng-mode-$(date +%s)

禁止：

• git add -A（会夹带脏数据）
• git stash（冲突风险）
• 跳过 SAFETY 直接改

4. EXECUTE — 最小改动

目标：一个逻辑变更，最小修改集。

强制动作：

• 使用 edit（首选）或 write 做精确修改
• 一次只做一个逻辑变更
• 不改无关代码（格式化、重构除非是本步目标）

禁止：

• 边改边加新功能
• 顺带重构无关代码
• 一次改多个不相关的文件

5. VERIFY — 改后必验

目标：确认改动没有破坏东西。

三级验证：

超时视为失败。详细策略见 references/validate-strategies.md

6. RECOVER — 失败恢复

目标：修一次，修不好就回退汇报。

强制动作：

1. 分析错误信息（读 stderr/stdout）
2. 检查改动：git diff
3. 修一次——仅做代码文本修改，不创建新 checkpoint
4. 重新 VERIFY

状态机互斥铁律：

• RECOVER 阶段 绝对禁止 触发 SAFETY（创建 checkpoint / 切分支）
• RECOVER 阶段 绝对禁止 触发 DECOMPOSE（重新拆任务）
• RECOVER 阶段 只能做：读错误 → 改代码 → 重验证
• 修复成功 → 回到循环，正常进入下一步的 SAFETY

回退（修复失败）：

# 动态获取最近 checkpoint（不依赖环境变量传递）
LATEST_CHECKPOINT=$(git log --grep="^checkpoint:" -1 --format=%H)
git reset --hard $LATEST_CHECKPOINT

# 或：直接切回原分支，丢弃临时分支
git checkout $ORIGINAL_BRANCH
git branch -D eng-mode-*

回退后：分析失败原因 → 报告用户 → 等待指示

详细恢复模式见 references/error-recovery.md

---

状态机互斥规则

进入下一阶段前必须确认当前阶段完成。

---

Git 提交规范

仅在 SAFETY 阶段做 checkpoint commit，格式：

checkpoint: <简短描述>

EXECUTE 后的增量提交（可选，在 VERIFY 通过后执行）：

: <简短描述>

type: feat / fix / refactor / chore / test

详见 references/commit-discipline.md

---

Reference 加载条件

按需加载，不一次性全吞：

---

不适用场景（跳过工程模式）

以下情况直接操作，不走六阶段：

• 纯聊天、回答问题、查资料
• 系统管理（改配置、重启服务、查进程）
• 甩给 CC/Codex 的任务（子代理自行管理）
• 单文件单行的简单修改（如改一个常量值、改一行注释）
• 用户明确说"不用工程模式"

判断标准：涉及 2+ 文件 或 逻辑改动 → 触发工程模式。