让 AI 一直知道你要做什么（flow2spec 讲解）

前言

用 AI 写代码这一年，你大概率遇到过同一个尴尬：

昨天刚跟它讲清楚的业务规则，今天新开一个对话，它又忘得一干二净。

于是我们不停地重复：贴规则、贴文档、贴上下文……直到把窗口塞满，AI 反而开始「读错、读多、读漏」。

Flow2Spec 想解决的，正是这件事——不是让 AI 更聪明，而是让 AI 一直知道你在做什么。

这篇文章我用一套图解（共 40 页）把它讲清楚：从「为什么需要」到「怎么用」，再到「团队怎么协作」。你不用先懂任何术语，跟着图往下看就行。

一、开场：项目知识，应该是仓库里的资产

先看结论。Flow2Spec 的核心主张只有一句：项目知识应该进入「可提交、可 review」的仓库资产，而不是只留在对话里或模型的私有记忆里。

它的做法是给项目建一张「知识图谱」——把 .Knowledge/（多层知识库）、rules / AGENTS（执行约束）、f2s-* skills（专业能力）、.task/（任务状态）编排在一起。当你说一句「实现用户登录功能，并补充测试用例」时，系统会路由匹配出这次真正需要的知识，按需读取，让知识随代码一起持续演进。

一句话：记忆不再是聊天记录，而是长在代码仓库里、能被 diff 的东西。

二、这次分享讲什么

整篇内容分成八块，逻辑是层层递进的：先讲为什么需要，再讲体系原理，然后是怎么接入、五类日常场景、真实效果、团队协作，最后补上配置冷知识和后期规划。

用一句话串起来就是：从「AI 会忘」，到「项目知识成为基础设施」。 下面我们从第一个问题开始。

三、第一章：为什么需要它

这一章要回答一个直觉上有点反常的问题。很多人以为，AI 写不好代码是因为「喂的上下文不够多」。但真实的痛点恰恰相反——信息太多、太杂，才是失控的开始。

我们要做的，是从「一股脑塞上下文」，走向「可路由的项目记忆」。

上下文越多，为什么反而更容易失控？

看左边这只抓狂的 AI：长规则、长文档、检索结果、无关信息、重复内容、过时文档、冲突事实、噪声数据……全都一起怼给它，结果就是上下文过载与漂移。

右边给出了对策，也是整个 Flow2Spec 的思想原点：

长规则、长文档与检索结果会造成过载；
项目事实需要路由、组合、校验和持续更新；
问题不是「记得少」，而是每次读错、或读太多。

所以结论是：需要的不是更多记忆，而是更好的路由。 记住这句话，后面所有设计都是围绕它展开的。

它已经用在了哪些项目上

光讲理念容易空泛，先给点实在的。这是四个已接入的生产仓库的统计：合计 1326 个文件、16.5 万行代码、103 个 topic、98 个 matcher、193 篇沉淀文档、80 个归档任务。

其中主仓 A 规模最大——27 位作者、3 个月 2786 次 commit，沉淀了 43 个 topic。而无论仓库大小，每次任务只加载命中的那几百行 topic，不会把整个知识库都塞进去。这就是「可路由」带来的直接好处：大项目也能只读一小块。

四、第二章：它是怎么运转的

第二章讲原理。别担心，不涉及代码，只讲三件事：四环架构、知识分层、渐进式路由。

Memory Coding：把项目记忆编码进仓库

Flow2Spec 把项目记忆拆成四个「环」，围绕中心的 Memory Coding 理念转：

知识环 .Knowledge/：项目事实住在这里；
任务环 .task/：记录每个任务做到哪一步；
规则环：约束 AI「必须怎么做、不能怎么做」；
技能环 f2s-*：一组可调用的专业能力。

四个环最终都落进 Git，于是可 diff、可 review、可协作——这正是「Memory Coding」这个词的含义：像写代码一样管理记忆。

知识层不是一堆 Markdown，而是 L0–L3 记忆结构

很多人做「项目知识库」就是堆一堆 Markdown，结果 AI 还是不知道该读哪篇。Flow2Spec 把知识分成四层，像一张地图：

L0 manifest-routing.json：路由总入口，定义「什么任务该读什么」；
L1 matchers/*.json：关键词分片，做初步匹配；
L2 topics/*.md：核心知识主题，提供结构化的项目事实；
L3 stock-docs / req-docs：兜底的长文档与需求文档，前面几层不够用时才下钻。

关键在于那句话：Agent 不是自由翻找，而是按协议走。 从入口到长文档，一层层收窄，避免「翻遍全仓」。

运行时的四步：match → expand → verify → act

有了分层，运行时就有了固定动作，只有四步：

match：命中一个 matcher 分片；
expand：展开它依赖的 topics；
verify：检查知识有没有缺口，缺了先补证据；
act：确认没问题，才动手执行。

这套流程的意义是——上下文按任务取用正确事实，而不是一次性全灌进去。

命中一个 topic 还不够：依赖链

这里有个容易踩的坑。你可能觉得「命中一个相关主题不就够了？」——不够。

看左边的红框：改功能时读了业务 topic，却漏了提交规则；生成方案时读了需求，却没读边界；做任务规划时，忘了读 .task/ 追踪规则。错误往往不是因为 AI 不读知识，而是它只读了一个局部，漏了前置约束。

右边的解法是 topicDependencies：把主题之间的依赖关系显式编码成一张有向图。 主题一旦声明了依赖，读取时就会自动把前置规则一起带出来。一次声明，所有任务复用。

举个例子：改「商品评价」页面，还要读什么

抽象的依赖链，用一个具体业务就懂了。假设你要改「商品评价」这个页面：

① 命中本域：商品评价的模板库（Redis 锁、AI 评分、本域例外）；
② 前置一：C 端白名单（UID 隔离、错误码）；
③ 前置二：平台上下文（业务子域、三仓分工、别名约定）；
④ 前置三：公共模块约定（ctx、responseData、QMQ、DB 字段规范）。

如果只读本域，很可能漏掉权限与公共约定。所以要先补齐前提，再检查是否足够执行。注意右下角那句提醒：这里说的是「知识读取依赖」，不是页面运行时的调用链——别搞混。

五、第三章：怎么接入和初始化

原理讲完，进入实操。接入其实很轻：装个 CLI，初始化骨架，生成项目架构。

不用先写完文档，知识随开发增长

很多团队一听「建知识库」就头大——是不是得先把文档写完？不用。 流程是这样的：

flow2spec init 初始化骨架；
f2s-doc-arch 生成项目架构；
doc-final → kb-build 形成可路由知识；
日常开发（feat / fix / sync / distill）持续反哺。

之后下次任务就能直接命中。核心理念是那句话：不需要先写完文档，从当前需求或模块开始就行。 知识是「长」出来的，不是「攒」出来的。

一个需求，如何变成可复用的交付

这张图是整个体系的「全景闭环」，信息量大，但主线很清晰。左边是四个角色（用户、Agent、知识库、代码仓），中间是一条更真实的开发闭环：

用户提需求 → 澄清（f2s-req-clarify）→ 出技术方案（f2s-req-tech）→ Agent 按知识库渐进读取并实现代码 → changeTracking 记录任务进度 → f2s-kb-sync 同步新知识 → f2s-git-commit 提交前检查。

右边把它归纳为五个阶段：澄清 → 技术方案 → 实现或修复 → 知识同步 → 提交前检查。 每一步都留下可追踪的资产。目标不是让 AI 更聪明，而是让它每次都能读到正确、可验证、能持续演进的项目事实。

核心技能：覆盖日常开发主路径

上面出现了不少 f2s-xxx，其实你不用背。它们按「需求 / 实现 / 知识 / 提交」四类分组，最常用的就 10 个：

需求：req-clarify（澄清）、req-tech（技术方案）；
实现：req-plan（规划并实现）、kb-feat（新增能力）、kb-fix（修正问题）；
知识：kb-add、kb-addRules、kb-sync、kb-distill（各种入库方式）；
提交：git-commit（检查并提交）。

在对话里，技能名统一省略 f2s- 前缀，说人话就能触发。

按需技能：补齐知识的全生命周期

除了每天都用的 10 个，还有 8 个「按需技能」，用来补齐知识的全生命周期，加起来一共 18 个：

建库与规范化：doc-arch、doc-final、kb-build；
维护与协作：kb-merge（合并冲突）、kb-rm（移除主题）、kb-upgrade（升级模板）；
资料与回顾：doc-pdf（PDF 转 MD）、doc-milestone（生成里程碑）。

注意：这里是按使用频率分层，不代表重要性。用到哪个学哪个就好。

六、第四章：五类日常使用场景

理念和技能都齐了，最实用的部分来了——从你正在做的事进入，让每次工作都留下可复用的结果。

一张表看懂：从哪里开始，走哪条路

先给张总览。日常开发无非五种情况，每种都有固定路径：

大需求：澄清 → 方案 → 任务 → 实现 → 验收与待办 → 同步 → 提交；
Fix：描述问题 → 修复 → 自动同步 → 提交；
Feat：描述能力 → 创建任务 → 实现 → 自动同步 → 提交；
老模块：知识缺失 → kb-add → 可路由知识 → 再开发；
普通问答：提问 → 回答 → 提示沉淀并确认 → topic → 下次命中。

下面挨个展开。

场景 1：大需求，从澄清到提交

一句业务描述，怎么变成可验收、可复用的工程交付？八步：

描述需求 → f2s-req-clarify（出澄清文档）→ f2s-req-tech（出技术方案）→ f2s-req-plan（创建任务）→ 实现功能 → acceptance.md + user-todos.md（完成验收与待办）→ kb-sync（同步知识库）→ git-commit（提交）。

比如「新增一个批量重算功能，要支持失败重试且避免重复执行」——每一步都落下一份可追踪的产物，而不是做完就散。

场景 2：Fix 与 Feat 的最短闭环

不是每个需求都那么重。日常最高频的其实是修 bug 和加小功能，它们走最短闭环：

Fix（f2s-kb-fix）：描述问题 → 修复实现 → 自动同步知识 → 提交；
Feat（f2s-kb-feat）：描述能力 → 创建任务 → 实现功能 → 自动同步知识 → 提交。

两者共同的收口是一致的：代码改变，知识同步，提交交付。 区别只在于——Fix 修正已有行为，Feat 增加新能力。

场景 3：改老模块前，先补可路由知识

接手祖传代码是最难受的。Flow2Spec 的做法是：先补知识，再动手。

发现旧模块知识缺失 → f2s-kb-add src/旧模块 → 扫描已有代码和文档 → 走「初稿 → 终稿 → topic + matcher」→ 沉淀成可路由知识。之后再开发时，按路由直接读取模块事实；下次改同一个模块，直接命中，不用再重新翻一遍代码。

先定位知识缺口，再定向解析旧模块——这一步的价值，用过一次就回不去了。

场景 4：普通问答，也会留下可复用答案

这个场景最容易被忽略，却很妙。平时你随口问 AI 一个问题，它答完就没了，下次还得重新查。

Flow2Spec 的流程是：用户提问 → AI 基于现有知识回答 → f2s-kb-distill 提示「要不要沉淀」→ 用户确认后新建或补充 topic → 下次直接命中。

对比很明显：反复 grep、全仓找代码，耗时、容易漏、成本高；而可路由事实是一次确认，多次复用，准确、高效。注意底部那行红线：沉淀由用户确认，不是未经确认就自动写入。

场景 5：验收清单与 UserTodo，让任务真正收口

任务「做完了」到底谁说了算？Flow2Spec 用 .task/ 目录把这件事管起来：

todo.json（活跃任务索引）、task.md（执行 checklist）、context.md（文件与上下文）；
acceptance.md（验收清单：失败重试符合预期、防重复执行，通过才算验收）；
user-todos.md（外部待办：DDL、开关、发版这类只能由你亲手做的事）。

收口顺序是：步骤完成 → 验收通过 → 外部待办完成 → 归档。中途断了也不怕，说一句「继续」就能恢复任务现场。 这一点对多天跨度的需求特别关键。

七、第五章：真实的使用效果

讲了这么多机制，到底好不好用？这一章是真实体验、个人效率和交付案例，不吹参数。

使用感受：从「带新人」到「给老员工交代工作」

作者本人的体感是这样一句话：从带新人，到给老员工交代工作。

讲业务：已有概念与历史知识 → 不用从头补背景；
澄清需求：结合项目约束追问 → 问题更容易问到点上;
推进实现：沿已有规范与边界开发 → 少肛细节、少打补丁。

分工也变清晰了：我负责目标、关键澄清和验收，AI 负责持续推进。 当然前提是——你熟悉项目、知识也在持续维护。

个人效率案例：5 天排期，3 天做完

一个具体案例：原本排期 5 天的需求，实际开发 2 天 + 测试 1 天，合计 3 天完成。

省下来的时间去哪了？靠的是三件事：先提炼产品需求、只澄清关键问题、按既有知识实现。作者的原话很有意思：「做需求的那几天，反而成了我更轻松的几天。」 需要说明的是，这是个人单次案例，不是对照实验，也不代表所有需求。

真实需求，效率提升了多少

再看两个带口径的真实数据：

乐赚贴（一批需求，4 张新表、25 个新接口、admin 净增 5494 行）：纯手工约 1 个月，普通 AI 辅助约 2 周，Flow2Spec 3 天——对比纯手工约 10×；
盲盒次卡（后端需求，3 张新表、7 个新 handler）：纯手工 8–12 工作日，普通 AI 4–6 天，Flow2Spec 2 工作日——对比纯手工 4–6×，对比普通 AI 也有 2–3×。

倍数会因需求和熟练度而异，但方向是明确的：沉淀得越多，后面越快。

八、第六章：团队怎么协作

一个人用爽了，多人一起用会不会乱？这一章的主题是：个人任务有边界，团队知识可演进。

真实团队规模下，如何不「串戏」

主仓 A 的规模是真实的压力测试：3 个月、27 位作者、2786 次 commit、43 个归档任务。怎么保证大家不互相打架？

个人工作区：.task/<developerId>/ 按人隔离，各自维护自己的任务、验收与外部待办，互不干扰；
共享知识：.Knowledge/ 通过 Git / PR 共享，配上 kb-delta.json + topic revision；
delta + revision 门禁：只有 revision 匹配才能合入，冲突时重读最新知识，避免静默覆盖别人的改动。

简单说：任务是你的，知识是大家的，合并有门禁。

团队收益：让知识留在项目里，而不只在人脑里

这套机制带来的团队收益，其实是在对抗一个老问题——「人一走，知识就没了」：

核心成员离开：历史决策与业务规则已入库 → 减少知识随人流失；
新人加入：通过 Agent 理解能力与边界 → 更快建立项目全貌；
持续协作：变更同步知识、共享版本 → 让交接建立在同一份事实之上。

归根结底：把个人经验，变成团队可以持续使用的项目资产。 前提依然是知识持续更新并经审核，没沉淀的经验还是得人工交接。

知识库合并冲突，用 f2s-kb-merge

多人协作难免撞车。比如同事 A 补了「失败重试规则」，同事 B 补了「幂等约束」，Git 合并后出现冲突——这时候 f2s-kb-merge 一键发起上下文合并，保留双方独有事实、去重对齐索引，复核后再提交。

规则也分得很清楚：上下文类冲突可自动合并，互斥事实需人工确认；而实现代码、依赖与部署冲突则展示差异、等待确认。特别提醒：topic revision 冲突要重读最新知识，那不是 Git 冲突。

九、第七章：几个实用的配置与冷知识

这一章是「彩蛋」，讲配置、冷知识与常用命令——都是容易忽略但很实用的东西。

很多工作规范，都可以配置

项目根目录的 flow2spec.config.json 能控制不少行为：

Agent 如何工作：subAgent（是否允许拆子 Agent）、switchAgentVerification（按技能约定交叉校验）、intentRecognition（高置信意图自动分流）；
任务如何记录：changeTracking.feat / fix / implement（分别控制三类变更追踪）、collaboration.enabled / developerId（控制个人任务目录隔离与身份）、locale（模板语言）、updateCheck.enabled（版本更新提示）。

默认值值得记一下：feat 开启、fix 关闭、implement 开启。 开关按技能约定生效，并不是所有行为都有开关。

几个容易忽略、但很实用的细节

四个小坑，提前知道能少走弯路：

init ≠ 业务知识已更新：init 只对齐骨架，业务事实要靠知识技能维护；
req-plan 始终维护任务：它不受 feat / fix 追踪开关影响；
kb-rm ≠ 删除业务代码：它只移除知识主题与路由，源文档还在；
同名 build，职责不同：f2s-kb-build 从终稿提炼知识，flow2spec kb build 从 topic 元数据归一化路由。

冷知识：主题过长时，主动拆分

业务持续迭代，单个 topic 可能越来越长。虽然已有长度、分类与职责边界的约束，但仍需持续维护。

当前做法是手动让 AI 按业务职责拆分：主 topic 保留入口与业务闭环，子 topic 承担可独立命中的职责，同步调整 matcher、索引与 topicDependencies，最后核验路由、依赖与事实是否完整。未来会考虑提供专用的拆分 skill（尚未推出）。

CLI 命令：诊断、校验与安全合库

注意区分：这些是在终端运行的命令，不是聊天里的 f2s-* 技能。分三组：

接入与版本：init（初始化骨架）、version（查看本地版本）、update --check（检查更新）；
诊断与校验：doctor（只读体检，只诊断不修复）、kb status（看知识库与 delta 状态）、kb check --strict（严格校验）；
安全合库：kb plan <delta.json>（预演合入与冲突）、kb apply <delta.json>（应用已通过的变更）、kb build（按 topic 元数据重建路由）。

这些命令统一加 flow2spec 前缀；apply / build 会写盘，用之前心里有数。

十、第八章：后期还会做什么

最后一章是规划中的方向，目标是让全链路可追溯，并补上前后端自动化测试。

一个索引 ID，串起一次需求的全部产物

设想一下：每次需求生成一个索引 ID，用独立 JSON 记录关联关系，把需求澄清、技术方案、topic、终稿、初稿、task 这些产物全都挂在同一个 ID 下。

之后再做 Web 展示——看团队成员的工作情况、每个节点的产物与状态、沿着一次需求查看完整交付过程。思路是：先建立可追溯索引，再建设团队可视化。当前这块还没实现。

完善前后端自动化测试环节

另一个方向是补齐测试：前端验证页面行为与关键交互，后端验证接口行为与业务逻辑，再加一层联调与回归，补齐跨端关键链路的自动化验证。

目标很朴素：让验收更可重复，让问题更早暴露，用完善的测试执行与结果反馈来支撑交付质量。

结尾：让项目知识成为团队可演进的基础设施

绕了一圈，回到最初那句话——不是让 AI 更聪明，而是让 AI 一直知道你在做什么。

上手也就三步：

安装 CLI：npm install -g @double-coding/flow2spec；
flow2spec init 初始化项目知识库与工作流配置；
从当前需求或一个模块开始，不需要先写完文档。

或者更快——一条命令 npx flow2spec init，就能开启你的项目知识基建。它尤其适合长期多人协作、上下文漂移成本高的项目。

项目仓库：@double-coding/flow2spec

写在最后

如果说过去一年 AI 编程工具解决的是「怎么把上下文塞进去」，那 Flow2Spec 想往前走一步：让项目知识变成能路由、能验证、能随代码一起演进的资产。

它不追求「AI 更聪明」这种玄乎的说法，而是踏踏实实地回答一个工程问题——怎么让每一次对话、每一个需求，都为下一次省下重复劳动。

四十张图看下来，你会发现它的每一个设计，都在还那句开场白的债：让 AI 一直知道，你在做什么。

兰涛开发日志

让 AI 一直知道你要做什么 （flow2spec 讲解）

前言