@double-codeing/flow2spec

v3.2.0

Published

3 days ago

在业务仓库初始化「文档驱动、可写回知识库」的 AI 协作骨架：项目根 .Knowledge 承载 stock-docs/req-docs 与机读路由，.cursor/.claude/.codex 写入 f2s-* 规则与技能（含 Karpathy 式编码行为准则，init 同步 rules / Codex topics / skills）；init 只落结构与模板，业务内容由各 f2s-* 技能在对话中维护。

Flow2Spec — 让 AI 一直知道你在做什么

解决 Cursor / Claude Code 的「失忆症」——用一个命令初始化，让 AI 跨会话记住项目上下文，不用每轮重新交代。
🌐 English · 中 / EN

🎬 在线演示（13 页 HTML PPT，← → 翻页，S 演讲者模式）

🔧 快速体验：

npx @double-codeing/flow2spec@latest init

Before / After

同样一句话，两段对话：

> 改一下评价模板文案库的批量重评分

没有 Flow2Spec：

AI: 这个模块的表在哪？
AI: batchReScore 是同步还是异步？
AI: 有没有锁？幂等键是什么？
AI: 返回格式是什么？错误码是多少？
AI: （翻遍 416 个接口、796 份文件、4.7 MB 源码…）

反复介绍 · 反复翻代码 · 反复踩坑

有 Flow2Spec：

[matcher 命中] m-product-review-template-library
[加载依赖] 4 个 topic · 约 300 行
AI: 已知 — fire-and-forget
     Redis 锁 smp:product-review:template-library:batch-rescore:lock（TTL 10 分钟）
     单次最多 100 条 · 错误码 101
AI: 开始改，预计 3 处文件。

4.7 MB → 300 行 · 秒级定位到硬约束

Flow2Spec 做这些事

① 跨会话记住项目上下文 .Knowledge/ 结构化知识库：路由清单（manifest-routing.json）+ 关键词索引（matchers）+ 主题分片（topics）。AI 启动时只读该读的，4.7 MB 源码压到 300 行精准上下文。

② 路由清单让 AI 不翻仓库，只拿该拿的 每次需求命中 1~4 个 topic，约 300 行。业务的硬约束——锁的 key、错误码、上限——都在 topic 里，AI 不用从源码猜。

③ f2s- 技能改代码顺手更新知识* /f2s-kb-feat 写功能时同步写 topic，/f2s-kb-fix 修 bug 时更正 topic，/f2s-git-commit 提交前检查 topic 覆盖。改代码就是记知识，没有"单独维护文档"这件事。

④ 需求到实现全链路：澄清 → 技术方案 → 代码 /f2s-req-clarify 反问到无歧义，/f2s-req-tech 生成可直接实现的技术方案文档落到 req-docs/，AI 按方案实现，不靠口头约定。

⑤ 任务清单跨会话追踪进度 开启 changeTracking 配置后，f2s-kb-feat / f2s-kb-fix 等技能执行时自动创建带 checkbox 的 task.md，每步完成立即打钩落盘。新会话续作时自动加载剩余清单，不靠记忆、不靠口头，任务进度永远在磁盘上。用户侧的代办（执行 SQL、配环境变量、点审批）单独写入 user-todos.md，不混在 AI 步骤里。

⑥ 文档驱动：PDF / MD 一键入知识库 /f2s-kb-add 把已落地能力的源码聚合成初稿 → 终稿 → topics，/f2s-doc-final 把 PDF 或任意 MD 转成规范终稿格式。外部文档、历史方案都能变成可路由的知识。

上手成本

最小可用集是一个空骨架。

npx @double-codeing/flow2spec@latest init

1 分钟生成目录结构 + 路由配置，空的，直接跑。下次需求命中哪块，写哪块，不提前建设。

真实仓库跑了三个月的数据：

| 指标 | 数值 | |---|---| | 对外接口数 | 416 | | 源码体积 | 796 文件 / 4.7 MB / ~10 万行 | | Flow2Spec 每次加载 | ≈ 300 行（噪声切掉 99%） |

使用流程

第一步：初始化（一次性）

npx @double-codeing/flow2spec@latest init

跟着提示走完，生成 .Knowledge/ 目录结构和路由配置骨架。

第二步：建知识库（一次性）

在 Agent 工具（Cursor / Claude Code）中执行：

/f2s-doc-arch — 扫描项目架构，生成架构说明初稿，跟着流程走直到生成主题（topics）

这一步只做一次，之后日常开发不需要重复。

/f2s-kb-add <文件夹路径> — 把还没入库的功能模块路径补进来

这一步在进入开发前，发现没有某个模块能力的知识的时候选择性的去做

第三步：日常开发（每次需求）

大需求：

/f2s-req-clarify  一句话需求或粘贴 PRD    ← 需求澄清
/f2s-req-tech                          ← 生成技术方案
自然语言：实现上面的技术方案              ← AI 开始实现（开启 changeTracking 时自动建任务清单）
（调试验证）
/f2s-kb-feat  新增 xxx 能力               ← 功能缺失时补能力
/f2s-kb-fix   修复 xxx                    ← 有 BUG 时修复
/f2s-kb-sync                              ← 同步知识库
/f2s-git-commit                           ← 检查并提交

小需求 / 日常改动：

/f2s-kb-feat  新增 xxx 能力               ← 功能缺失
/f2s-kb-fix   修复 xxx                    ← 改 BUG

常用命令速查

| 命令 | 用途 | |---|---| | /f2s-req-clarify | 需求澄清 | | /f2s-req-tech | 生成技术方案 | | /f2s-kb-feat | 新增小功能 | | /f2s-kb-fix | 改 BUG | | /f2s-kb-sync | 同步知识库 | | /f2s-git-commit | 提交代码；“快捷提交”跳过知识库覆盖检查 | | /f2s-kb-add <路径> | 接口模块入知识库 |

更多命令详见使用说明 · 命令说明

什么时候别用

一次性脚本 — 写完就删的东西，直接丢几个 Markdown 给 AI 更快
单人小项目 — 一份 CLAUDE.md 就够，路由和分片的开销大于收益
团队不愿同步 .Knowledge/ — 工具不能替代纪律

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme