ai-engineer-workflow-v5

name: ai-engineer-workflow-v5 description: V5 + OpenSpec 集成。强化验证、防止蔓延、架构反思、需求完整性、TDD铁律、BDD智能缺口、OpenSpec 变更管理。

AI Engineer Workflow V5 — OpenSpec + CodeGraph 集成版

强化验证、防止蔓延、架构反思、需求完整性、TDD铁律、BDD智能缺口、OpenSpec 变更管理、CodeGraph 智能索引

核心约束

完整定义见 openspec/specs/rules/spec.md → 四、核心执行约束（8 条）

本 workflow 在此约束下执行：

1. 不探索清楚不实现（Gate 1/BDD）
2. 不计划清楚不实现（Gate 2）
3. 不完整覆盖需求不实现（Gate 2/Requirements Integrity）
4. 不测试通过不提交（Gate 5）
5. 不验证成功不声明（Gate 5）
6. 三次失败必须反思（Gate 6）
7. 不见见证不变更（TDD Iron Law / Gate 3）
8. 不见场景缺口不进设计（BDD智能缺口 / Gate 1）

五系统分工

协作边界：

• workflow 负责执行流程，Gate/Loop 控制
• Karpathy 负责原则监察，违规即报
• BDD 负责缺口发现 + 用户选择，Phase 1 强制询问
• TDD 负责测试铁律，Phase 3 强制执行
• OpenSpec 负责变更管理，Phase 1 创建变更，Phase 4 归档变更
• CodeGraph 负责代码理解，Phase 2-3 加速代码探索

Karpathy 监察（全流程自动激活）

原则定义：见 openspec/specs/rules/spec.md → 一、Karpathy Guidelines

本 workflow 全程监控以下 4 项原则的遵守情况：

与 code-refactoring plugin 协调：

• 用户明确说"重构" → 调用 plugin，Surgical Changes 暂停
• 用户说"修复"/"添加功能" → Surgical Changes 生效，不调用 plugin
• 发现需重构 → 先报告获 approval → 再调用

违规处理流程：检测到违反任一原则 → 立即报告 → 用户未 approve 前不得进入下一 Phase。

Requirements Integrity 违规处理

原则定义：见 openspec/specs/rules/spec.md → 一.5 Requirements Integrity

本 workflow 的违规处理流程：

发现未经用户确认的需求裁剪
  → 立即报告
  → 用户未 approve 前不得进入 Phase 3

BDD 智能缺口（Phase 1 自动激活）

方法论定义：见 openspec/specs/rules/spec.md → 五、BDD 方法论（原则定义、缺口扫描规则、标准默认假设）

本 workflow 中 BDD 的执行流程：

Step 1：需求扫描（自动）
  读取需求 → 自动识别 Happy Path / Sad Path / Edge（扫描规则见 rules/spec.md）

Step 2：缺口发现 → AskUserQuestion（一次）
  选项: "用默认假设补充" / "手动补充具体场景" / "跳过，需求已足够清晰"

Step 3：用户选择处理
  "用默认假设" → 按 rules/spec.md 标准默认假设自动生成场景草图 → 继续
  "手动补充" → 询问具体缺口 → 补充 → 继续
  "跳过" → 记录缺口到 OpenSpec proposal.md → 继续

Step 4：生成场景草图（模型生成，用户确认）
  格式见 rules/spec.md → 五、BDD 方法论，不要求 Given-When-Then 表格

TDD 监察（Phase 3 自动激活）

方法论定义：见 openspec/specs/rules/spec.md → 六、TDD 方法论（Iron Law、Red-Green-Refactor、Verify RED/GREEN、测试质量标准、常见借口）

本 workflow 中 TDD 的执行绑定：

Phase 3 遵循 TDD Iron Law（定义见 rules/spec.md）

本 workflow 执行铁律：
  1. 确定变更范围
  2. 建立测试覆盖变更范围
  3. Verify Current State → 展示输出
  4. Make Change
  5. Verify New State → 展示输出
  6. Done

循环引用：RED → Verify RED → GREEN → Verify GREEN → REFACTOR（完整定义见 rules/spec.md）

OpenSpec 集成

变更生命周期

Phase 1 (CLARIFY) → /opsx:explore 或 /opsx:propose
  - 探索需求，创建变更提案
  - 生成 proposal.md + specs/ + design.md + tasks.md

Phase 2 (PLAN) → 细化 OpenSpec 变更
  - 完善 tasks.md 任务清单
  - 完善 specs/ 增量规格
  - 完善 design.md 技术方案

Phase 3 (EXECUTE) → /opsx:apply
  - 按 tasks.md 任务清单实施
  - 每个任务完成后勾选

Phase 4 (COMPLETE) → /opsx:archive
  - 归档完成的变更
  - 增量规格合并到 specs/

与 openspec-assistant 同步

同步时机：
  - /opsx:propose 后 → assistant 同步任务到 .claude/docs/tasks.md
  - /opsx:apply 后 → assistant 更新 tasks.md 状态
  - /opsx:archive 后 → assistant 从 tasks.md 移除已完成任务

同步方式：
  - assistant 读取 openspec/changes/<name>/tasks.md
  - 同步到 .claude/docs/tasks.md（标记来源 change）
  - 保持双向一致性

CodeGraph 集成

Phase 中使用 CodeGraph

Phase 2 (PLAN) — Plan Agent + CodeGraph:
  - codegraph_status → 检查索引健康
  - codegraph_explore → 理解现有代码结构
  - codegraph_impact → 评估改动影响
  - codegraph_callers/callees → 追踪依赖关系

Phase 3 (EXECUTE) — 委托时强制使用 CodeGraph:
  - 子 agent 提示词必须包含："用 codegraph_explore 理解代码，不要用 Read + Grep"
  - 遵循 CodeGraph 调用守则（先 explore，再 node/callers/callees）
  - 不要开 Explore 子 agent 读文件
  - 看到 ⚠️ stale banner 时，对那一个文件直接 Read

CodeGraph 工具速查

Gate 4 review 中使用 CodeGraph

两阶段 Review 中增加 CodeGraph 增强:

Stage 1: Spec compliance
  - codegraph_impact {改动符号} → 检查实际影响范围与 specs 一致
  - codegraph_callers {改动符号} → 检查所有调用者

Stage 2: Code quality
  - codegraph_explore {模块} → 整体结构审查
  - codegraph_node {关键函数} → 实现细节审查

六个门控（GATES）

Gate 1: Design Approval + BDD Check

位置：Phase 1 结束 → Phase 2 前

检查项：
  ✅ brainstorming skill 完成
  ✅ AskUserQuestion 已询问（场景缺口）
  ✅ 用户已回答
  ✅ 生成了 Scenario Sketch（模型生成）
  ✅ OpenSpec 变更已创建（/opsx:propose 或 /opsx:explore）

触发：用户说 "approved" / "继续" / "开始计划"

Gate 2: Requirements Completeness

位置：Phase 2 结束 → Phase 3 前

❌ 不开始实现、不执行 task、不调用 executing-plans
✅ Lite Plan Check → Requirements Completeness Check → 用户 approve Completeness
✅ OpenSpec tasks.md 已完善
✅ OpenSpec specs/ 已完善
✅ OpenSpec design.md 已完善

Requirements Traceability Matrix：

Status：
  ✅ = Covered
  ⚠️ = Simplified（需用户 approval）
  ❌ = Missing（必须修复）

Gate 2 通过：所有 ✅、所有 ⚠️ 已获 approval、无 ❌

Gate 3: Test Witness

位置：每个 task 开始前

遵循 TDD Iron Law（见 TDD 监察）

✅ 确定变更范围
✅ 存在测试覆盖变更范围
✅ Verify Current State 已展示输出
✅ 当前状态符合预期（RED/GREEN）

不符合 → 必须先建立测试

Gate 4: Two-Stage Review

位置：每个 task 完成后

严格顺序：
  1. Spec compliance review（先）
  2. Code quality review（后）

❌ spec compliance ✅ 前开始 code quality
❌ 有 open Critical/Important issues 时继续下一 task

Issue 级别：
  Critical：立即修复
  Important：下一 task 前修复
  Minor：记录，稍后处理

Gate 5: Evidence-Based Verification

位置：任何声明工作状态时

NO COMPLETION CLAIMS WITHOUT FRESH VERIFICATION EVIDENCE

步骤：
  1. IDENTIFY：什么命令证明？
  2. RUN：执行完整命令
  3. READ：完整输出 + exit code
  4. EXTRACT：展示关键输出片段 ← 强制展示证据
  5. VERIFY：输出确认声明？
  6. ONLY THEN：做出声明

验证格式（强制）：

禁止：只说 "tests pass" 无输出证据、使用 "应该/大概/似乎"

Gate 6: Stop-On-Blocker + 3-Failure Reflection

位置：Phase 3 全程监测

三次失败架构反思：

同一问题修复尝试 ≥ 3 次仍未解决：

→ 强制切换到架构分析模式：
   1. STOP 当前修复
   2. 记录：每次修复的尝试方法和失败症状
   3. 架构检查：
      - 每次修复暴露新的 shared state/coupling？
      - 需要"大规模重构"才能实现？
      - 每次修复在其他地方产生新症状？
   4. 决策：
      - 任一为 YES → 架构问题，讨论重构
      - 全为 NO → 回 Phase 1（需求理解错误）

禁止：
❌ 继续第 4、5 次相同类型的修复尝试
❌ 不记录失败历史就盲目 retry

五个循环（LOOPS）

Loop 1: Clarification（Phase 1）

Explore → Decompose → Gap Scan → AskUserQuestion（一次）→ Scenario Sketch → /opsx:propose → [Gate 1]

Loop 2: Plan Revision（Phase 2）

Plan Agent → Lite Plan Check → Requirements Completeness Check → Task Mapping → Self-review → User review → [Gate 2]

Loop 3: Red-Green-Refactor（每个 task）

[变更范围确认] → [Gate 3] → TDD 循环（见 TDD 监察）→ [Gate 5] → [Gate 4]

Loop 4: Review-Fix

Stage 1: Spec compliance → Issues? → Fix → Re-check
                              ↓ ✅
Stage 2: Code quality → Issues? → Fix → Re-check
                              ↓ ✅
                   [Gate 5] → Fresh verification evidence
                              ↓ ✅
                   Task complete → Mark completed

分歧 > 2 轮 → 提交用户裁决

Loop 5: Complete Decision

Run test → [Gate 5] → 0 failures → 声明 → /opsx:archive → 4 options → Execute
                    → N failures → Fix → Loop

4 Options：Merge locally / Create Pull Request / Keep branch / Discard（需 typed confirmation）

Phase 流程

Phase 1: CLARIFY

调用：brainstorming skill + /opsx:explore 或 /opsx:propose
Announce："Phase 1: 需求探索 + OpenSpec 变更创建"
输出：Approved Requirements List + Scenario Sketch + OpenSpec 变更

Phase 2: PLAN

调用：Plan Agent + writing-plans skill
Announce："Phase 2: 计划细化 + OpenSpec 完善"
流程：Plan Agent → Lite Plan Check → Requirements Completeness Check → Self-review → User review → [Gate 2] → Phase 3

如果计划太长请分步写入

Phase 3: EXECUTE

模式：Inline（简单任务） / Subagent（复杂任务、并行）

调用：
  Inline：executing-plans skill
  Subagent：subagent-driven-development skill
  OpenSpec：/opsx:apply
  CodeGraph：codegraph_explore/callers/callees/impact

流程骨架：
  Load plan → Create TodoWrite
  For each task:
    1. [变更范围确认]
       - codegraph_impact {目标符号} → 评估改动影响
    2. Mark in_progress
    3. [Gate 3] 建立测试 + Verify Current State
       - codegraph_explore {目标模块} → 理解当前实现
       - codegraph_node {具体符号} → 拉源码参考
    4. [Loop 3] TDD 循环（Iron Law + 状态见证）
    5. [Gate 5] Verify New State（展示输出片段）
       - codegraph_callers {改动符号} → 验证所有调用已更新
    6. [Gate 4 + Loop 4] Review
       - codegraph_explore {模块} → 整体复查
    7. Mark completed（仅 Gate 5 通过后）

  All tasks → Phase 4

Phase 4: COMPLETE

调用：finishing-a-development-branch skill + /opsx:archive
Announce："Phase 4: 归档变更 + 完成分支"
流程：[Loop 5] → /opsx:archive → END

Auto Mode

行为准则：见 openspec/specs/rules/spec.md → 七、Auto Mode 行为准则

本 workflow 下各场景的行为映射：

自动模式ultra：当用户说，进入完全自动模式的时候则进入完全自动模式，此时所有原本需要停止等待决策的地方不需要停止，按照方案自动进行，需要进行抉择决策的时候自动选择方案全局最优解

Skill Mapping

监察层：Karpathy 全 Phase、BDD Phase 1（缺口发现）、TDD Phase 3，违规即报

Red Flags

Phase 1:
❌ "Too simple to need design" → Gate 1 violation
❌ Code before design approved → Gate 1 violation
❌ 未询问场景缺口 → BDD violation
❌ 未创建 OpenSpec 变更 → 变更管理 violation

Phase 2:
❌ TBD/TODO in plan → Lite Plan Check violation
❌ Requirements Traceability Matrix 未完成 → Gate 2 violation
❌ Simplification 未经用户 approval → Gate 2 violation
❌ OpenSpec tasks.md 未完善 → 变更管理 violation
❌ 未用 codegraph_explore 理解现有代码 → 代码理解 violation
❌ 未用 codegraph_impact 评估改动 → 影响评估 violation

Phase 3:
❌ 无测试变更代码 → Iron Law violation
❌ 跳过 Verify Current State → Iron Law violation
❌ 跳过 Verify New State → Iron Law violation
❌ "Tests pass" without running → Gate 5 violation
❌ "Tests pass" without 输出片段 → Gate 5 violation
❌ "太简单不用测" → Iron Law violation
❌ 变更超出 PLAN 范围 → Surgical Changes violation
❌ 继续第 4 次相同修复 → 3-Failure violation
❌ 用 Read + Grep 而不用 codegraph_explore → CodeGraph 优先 violation
❌ 开 Explore 子 agent 读文件 → 浪费 violation
❌ 委托提示词中缺 codegraph_* 指令 → 委托 violation

Phase 4:
❌ 未归档 OpenSpec 变更 → 变更管理 violation
❌ 未调用 finishing-a-development-branch → Review violation
❌ 未用 codegraph_affected 找受影响的测试 → CI 集成 violation

General:
❌ "Should/probably" → Verification violation
❌ Gate BLOCK 不记录 → Workflow 违规（见 rules/spec.md）
❌ 先 grep 反向验证 codegraph 结果 → 信任 violation

Key Principles

四系统协作：
  workflow（执行）→ Karpathy（监察）→ BDD（缺口发现）→ TDD（测试）→ OpenSpec（变更管理）
  权责清晰，违规即报

Requirements Integrity 优先于 Simplicity（定义见 rules/spec.md）
Iron Law 优先于 所有借口
Gap Scan 优先于 手动填写表格

Gate 控制 Phase 进入
Loop 控制 Phase 内完成

验证铁律：必须展示输出片段
TDD 铁律：变更必须有测试见证
遇阻即停不猜测
三次失败必须反思：禁止继续第4次修复
Task Complete 条件：Gate 5 通过后才能 Mark completed

OpenSpec 集成：变更生命周期管理
Auto Mode 适配