DevFlow：一个让任何 AI 都能"按流程办事"的 CLI 工具

如果你用过 Superpowers 这套 AI 工作流规范，一定有过这种体验：告诉 AI “帮我修复这个 bug”，它会先读规范、再按步骤执行——先复现问题、再定位根因、最后修复验证。

这套规范确实有用。但用久了你会发现一个尴尬的问题：规范是"建议"，不是"约束"。

AI 读完了规范，仍然可能凭直觉跳步骤；你说”先写测试再写代码”，它嘴上说好，手一快就先把功能实现了；你说”修复前要先找到根因”，它试了两次没头绪，直接开始瞎猜。

问题不在 AI 不听话，而在于我们没有给规范配上一个”执行引擎”。

---

真实踩坑：规范有了，执行却失控了

以上说得还算理想化。接下来我要分享的是真实工程中的三个痛点——它们直接决定了 DevFlow 必须被设计成现在这个样子。

痛点 1：工作流文档披露太多，关键细节反而丢失

我最初在项目里放了一份 WORKFLOW.md，里面详细描述了从需求到交付的完整流程。Agent 读完后，大体的执行顺序是对的——它知道要先创建需求文档，再开发功能。

但问题出在信息量过载。

当 Agent 一次性看到全部流程（创建 REQ → 写 FEAT → TDD 实现 → 测试 → 验证），它往往只抓主线，丢掉细节。流程要求”创建 REQ 需求文档并填充内容”，Agent 创建了一个空文件就觉得”这一步完成了”，马上跳到功能开发。等到代码写完了，回头一看——REQ 文件还是空的，没有需求描述、没有验收标准。

不是 Agent 不想做对，而是一次性给太多信息，它根本抓不住重点。

痛点 2：AI 行为不可控，会擅自跳过必要步骤

更严重的问题是，Agent 会自行判断哪些步骤”不重要”然后跳过。

你规定了”修改代码前必须先写测试”，Agent 嘴上说好，手一快直接把功能实现了。你要求”提交前必须跑 lint”，Agent 觉得”这次改动很小，应该不会出错”，直接跳过。

没有强制约束的规范，本质上只是”建议”。 Agent 会根据自己的”理解”选择性执行，而人类期望的是每一步都必须完成、每一项检查都必须通过。

痛点 3：不同项目流程差异大，纯文档适配性差

我尝试给所有项目用同一份 WORKFLOW.md，但很快发现行不通。

有的项目需要跨平台打包环节，有的项目要流转到第三方系统审批，有的需要做安全扫描，有的需要性能基准测试。同一份文档不可能覆盖所有场景。

而且，当项目从 A 流程迁移到 B 流程时（比如 Debug 完成后要回到 Feature 开发的评审环节），纯文档方案只能靠 Agent”记住”之前的状态——它经常记不住。

靠 Markdown 文档来适配不同项目、管理流程切换，是死路一条。

优化思路的诞生

这三个痛点让我意识到，问题的根源在于控制权的归属：

不能让 Agent 自己决定”接下来做什么”。必须让 CLI 来编排工作流，Agent 只是流程中的执行者。

针对三个痛点，DevFlow 的解决方案是：

痛点	解决方案
信息过载，细节丢失	渐进式披露——一次只给一步，完成后再给下一步
AI 跳过步骤，行为不可控	Gate 系统 + Fail Route——没过检查就不能前进，失败自动走补救路线
项目差异大，流程切换难	控制反转 + 跨工作流引用——人类用 TOML 定义工作流，CLI 负责编排和切换

此外，为了改善人机交互，DevFlow 还提供了 Ralph Loop 自主执行模式——启动后 Agent 可以自动推进工作流，人类只需在关键节点介入，不需要每一步都手动确认。

这五个机制，就是 DevFlow 的核心设计哲学。

---

从「规范卡片」到「生产流水线」

Superpowers 本质上是一套行为规范——它告诉 AI “你应该怎么做”，但无法检查 AI “是不是真的做了”。

这就像一家公司：

• 有员工手册（规范）
• 但没有打卡系统、没有审批流程、没有质量检查

结果就是：有人按规矩来，有人凭感觉来，交付质量完全看运气。

我们需要的是一套”生产流水线”：AI 每做完一步，必须经过客观检查（Gate），通过了才能进入下一步；没通过，就自动进入补救流程。整个开发过程从”自由发挥”变成”强制流程”。

这就是 DevFlow 要解决的问题。

---

DevFlow 是什么？

DevFlow 是一个与 Agent 无关的 AI 开发工作流 CLI 工具。它用 TOML 配置文件定义开发流程，通过渐进式披露（Progressive Disclosure）让 AI 一次只看一步，配合 Gate 系统进行客观验证。

核心定位：Superpowers 解决”AI 应该知道什么”，DevFlow 解决”AI 必须做什么、怎么确认做了”。

维度	Superpowers	DevFlow
本质	行为规范（软约束）	执行引擎（硬约束）
形式	Markdown 技能文档	TOML 工作流 + CLI 工具
验证方式	靠 AI 自觉	Gate 系统客观检查
适用范围	特定 Agent 插件	任何 AI Agent 都能用
用户指令	“请先读规范”	devflow current → devflow done

---

核心设计：五个机制管住流程

1. 渐进式披露（Progressive Disclosure）

传统方式是扔给 AI 一份完整的开发规范（比如 20 页的流程文档），AI 看了前面忘了后面，或者跳着看。

DevFlow 的做法是一次只暴露一个步骤：

AI: devflow current
CLI: [显示当前步骤的指令和 Gate 条件]

AI: [执行指令]

AI: devflow done
CLI: [检查 Gate → 通过 → 推进到下一步]

AI 永远只看到当前该做什么，不会提前看到后面的步骤，也不会漏掉前面的步骤。

2. Gate 系统：客观验证

每个步骤都配有 Gate 条件，只有满足条件才能通过。常见的 Gate 类型：

Gate 类型	说明	示例
file_exists	文件必须存在	docs/REQ-001.md 已创建
file_contains	文件必须包含特定内容	需求文档包含 status: approved
command_success	命令必须成功退出	pytest 全部通过
user_approved	需要人工确认	devflow approve DESIGN-001

核心规则：没过 Gate，就 advance 不了。 这不是建议，是程序上的硬拦截。

3. Fail Route：失败不卡死

如果 Gate 检查失败怎么办？传统方式是 AI 原地重试，可能陷入死循环。

DevFlow 的解决方案是 Fail Route——根据失败次数自动路由到不同的处理步骤：

flowchart TD
    A[debug-fix
执行修复] --> B{Gate检查
测试通过？}
    B -->|通过| C[debug-verify
验证修复]
    B -->|失败 1-2 次| D[debug-root-cause
重新分析根因]
    B -->|失败 3+ 次| E[debug-question
升级到人工介入]
    D --> A
    E --> D

AI 不需要自己决定”接下来怎么办”，流程已经定义好了。

4. 跨工作流引用

不同场景用不同的工作流：

• MODE-A：Feature 开发（需求 → 设计 → 实现 → 测试 → 交付）
• MODE-B：Debug（根因分析 → 假设验证 → 修复 → 验证）

关键是：Debug 完成后，自动切回 MODE-A 的 Plan 阶段，进入完整的评审循环。

flowchart LR
    subgraph MODE-B
        B1[debug-finish
Debug完成]
    end
    subgraph MODE-A
        A1[write-plan
重新进入评审]
    end
    B1 -->|跨工作流引用| A1

这意味着 AI 不需要”记住”之前在做哪个功能，流程本身会带它回到正确的位置。

5. Ralph Loop：人机协作的自主执行

前面四个机制解决的是”流程怎么管”，Ralph Loop 解决的是”人机怎么协作”。

在没有自主执行的情况下，每完成一步都需要人类手动输入 devflow done 来推进——这在复杂项目中非常繁琐。

Ralph Loop 的模式是：

# 启动自主执行循环
devflow run [--tool local] [--max-iterations 10]

启动后，Agent 会自动读取当前步骤、执行指令、检查 Gate、推进到下一步。人类只需在需要确认的关键节点介入（比如 user_approved Gate），其他时候流程自动跑。

你还可以随时查看循环状态：

devflow loop-status     # 查看剩余任务和进度
devflow sync-backlog    # 从当前工作流生成任务清单

Ralph Loop 不是让人类放手不管，而是把人类的精力集中在”决策”上，把”执行”交给流程。

---

内置工作流：开箱即用

DevFlow 自带两个核心工作流：

MODE-A：Feature 开发

flowchart LR
    A[req-create
创建需求] --> B[req-approve
需求确认] --> C[brainstorm
方案探索] --> D[write-plan
拆解任务] --> E[implement-tdd
TDD实现] --> F[code-review
代码审查] --> G[test-run
运行测试] --> H[verify
收集证据] --> I[finish
交付清理]

MODE-B：Debug

flowchart TD
    A[debug-root-cause
调查根因] --> B[debug-pattern
模式分析] --> C[debug-hypothesis
假设验证]
    C -->|验证失败| A
    C --> D[debug-fix
实现修复]
    D -->|失败1-2次| A
    D -->|失败3+次| E[debug-question
质疑架构
需人工确认]
    E --> A
    D -->|修复通过| F[debug-verify
验证修复]
    F --> G[debug-finish
Debug完成]
    G -->|跨工作流切换| H[MODE-A: write-plan]

---

快速体验

DevFlow 的安装和使用非常直接。你可以让 AI Agent 通过以下链接自行了解并完成安装：

Read and follow the instructions from:
https://github.com/Dqz00116/devflow/blob/main/SKILL.md

或者手动访问项目仓库查看 README 获取详细文档。

基本使用流程：

# 初始化项目
devflow init --language python --name "My Project"

# 选择工作流
devflow select-workflow MODE-A

# 查看当前步骤指令
devflow current

# 执行完成后，检查 Gate 并推进
devflow done

---

为什么这件事很重要？

AI 编程助手正在快速普及，但行业面临一个核心问题：不同 AI、不同用户、不同项目，做出来的质量天差地别。

同样的 “帮我实现一个登录功能”：

• 有的 AI 直接写代码，测都不测
• 有的 AI 先问需求，再写测试，再实现，再验证

差异不在 AI 的能力，而在工作流程是否被强制执行。

DevFlow 的意义在于：把”好的工作习惯”从”靠 AI 自觉”变成”靠流程保证”。无论用的是 Claude、Kimi、Gemini 还是其他任何 Agent，只要接入 DevFlow，就必须按步骤走、必须过 Gate、失败必须按既定路线处理。

这不是限制 AI 的创造力，而是确保基础质量的下限。

---

与 Superpowers 的关系

DevFlow 不是 Superpowers 的替代品，而是互补的执行层：

• Superpowers 解决”AI 应该遵循什么规范”（brainstorming → TDD → debugging → verification）
• DevFlow 解决”AI 是否真的按规范执行了”（current → done → gate check → advance）

两者结合，形成一个完整的闭环：规范定义纪律，流程强制执行纪律。

---

总结

DevFlow 的核心价值可以用一句话概括：把 AI 开发从”自由发挥”变成”按流程办事”。

它不提供新的 AI 能力，而是为已有的 AI 能力套上一条标准化的生产线：

• 每一步做什么，流程说了算
• 做没做完，Gate 系统说了算
• 失败了怎么办，Fail Route 说了算
• 做完了接下来去哪，工作流配置说了算

当 AI 助手越来越强大，我们需要的不是更聪明的 AI，而是更可靠的协作方式。DevFlow 就是在做这件事。

---

项目资源：

• 🏠 项目主页：https://github.com/Dqz00116/devflow
• 📖 使用指南（SKILL.md）：https://github.com/Dqz00116/devflow/blob/main/SKILL.md
• 🌟 Superpowers 原项目：https://github.com/obra/superpowers