flow — gated build harness for coding agents
实证胜于感觉。

flow

报完工过不了 gate。

给你的 coding agent 加一层带 gate 的 harness。flow 掌管 gate 与证据，从不碰 runtime。在 gate 毙掉一个弱想法，是合理产出。

只有双方都点头，gate 才会开。

NODE ≥22
npx @manhquy/flow-skill@latest
安装与首次运行

与你的 CODING AGENT 协同工作

Claude CodeCodex CLIGemini CLICursorAiderClineContinueZed

开工前的六道 gate

每个 stage 都会在你的仓库里留下一个真实文件。只有 runner 和 skill 都点头，/flow next 才会放行下一个 stage。这些文件只在你走完 gate 之后出现——刚装完时什么都没有。

  1. 01Idea
  2. 02Research
  3. 03Scope
  4. 04PRD
  5. 05ADR
  6. 06Contract
01

Idea

flow/00-idea.md

在写代码之前毙掉烂想法。

MDflow/00-idea.md拦截
1# 问题陈述
2[FILL: 描述用户问题]
3# 提议的方案
4<空>
exit: 1 · 还有 [FILL] 没填
FAIL · 毙于 GATE

过不了 gate 的东西

空文件、残留的 [FILL]、拿“tests pass”来报完工——一律拦下。弱想法在 gate 就被毙掉。

  • 空文件。
  • 文件里还留着 [FILL]。
  • 拿一句“tests pass”来报完工。
$ /flow next
refusing: flow/00-idea.md is empty (line 1)
毙掉也是有效产出。
02

Research

flow/01-research.md

拿出真实来源，否则止步于此。

MDflow/01-research.md3/3 已引用
1## 一手来源
2• [RFC-9110] §4.2 幂等方法
3• github.com/owner/repo#412 (repro)
4## 竞品对比与失败模式
URL 已核实 · ground truth 已锁定
02证据 · 一手来源

先有 ground truth，再谈架构

竞品对比、核实过的文档引用、真实的失败模式，全部记进仓库文件。

$ /flow check 01-research
✓ 3 个一手来源已引用（URL 已核实）
✓ 竞品对比与失败模式已锁定
03

Scope

flow/02-scope.md

画清边界，砍掉其余。

MDflow/02-scope.md已冻结
1范围内 S-01 CLI harness gate 循环
2范围内 S-02 证据 schema 校验器
3非目标 Telemetry / 数据采集
4非目标 自建云端守护进程
2 个交付切片 · 边界已冻结
03边界 · 非目标

non-goals 明确冻结

交付范围切成小块。范围蔓延在写代码之前就被抓住。

$ /flow check 02-scope
✓ 3 个交付切片已锁定
✓ non-goals 已明确冻结（范围蔓延被拦下）
04

PRD

flow/03-prd.md

先定好测试，再写代码。

MDflow/03-prd.md验收标准
1INV-01: spec 文件为空时 exit 1
2INV-02: 拒绝信息打到 stderr
3INV-03: 证据 JSON 符合 schema
4INV-04: 降级模式自动记一笔 debt
4 条可观察不变量 · 0 废话
04契约 · 验收

只认可观察的验收标准

每个 user story 都带着可测试的不变量。agent 不能中途改写成功的定义。

$ /flow check 03-prd
✓ 可观察的验收标准已确认
✓ 错误状态与降级路径已定义
05

ADR

flow/04-adr.md

先记录权衡，再提交。

ADRflow/04-adr.md已接受
1状态： 已接受 (2026-10-11)
2背景： 文件存仓库 vs SQLite 守护进程
3决策： 用 git 跟踪的 Markdown 文件
4后果： 可移植；不需要后台服务
可逆性已梳理 · 权衡已锁定
05决策 · 权衡

架构决策记录

开工之前，先记下背景、决策和后果。

$ /flow check 04-adr
✓ 背景、决策、后果已记录
✓ 可逆性与反例测试已梳理
06

Contract

flow/05-contract.md

双方都认可，否则寸步不让。

SIGflow/05-contract.md已解锁
[✓] 人工确认：@dev 已批准
[✓] harness 背书：sha256:7f3a..9e1b
[✓] flow doctor：READY（skill 已校验）
[✓] 双重确认：已解锁 -> 开工
契约已签署 · gate 放行开工
PASS · 就绪

装完之后

skill 已经在磁盘上。输入 /flow（Codex：$flow）。flow doctor 会打出 READY。 对空 idea 文件跑 /flow next，会带着行号拒绝你。

  • skill 文件落进 agent 的家目录。
  • 输入 /flow（Codex：$flow）。
  • doctor 能打出 READY。
  • 对空 idea 文件跑 /flow next，会带着行号拒绝你。
$ flow doctor
doctor: READY (skills/flow/SKILL.md verified)
只有双方都点头，gate 才会开。

然后是 /flow card。完成意味着拿出世间的证据： 一个已部署的 URL、一个装得上跑得起来的 CLI、一个公开 API，或一次真实的 skill 运行。

不是 AI coding agent，是套在它外面的 harness。

flow 不替你写代码。写代码的还是 agent；harness 只决定这份工作配不配往前走。

安装与首次运行读文档