前言
推荐一种新的SSD辅助编码思想。 解决的是项目过大时，agent噪音过大、知识库渐进式读取、知识库新增负担等问题。
如果能帮助到各位麻烦点个start。欢迎提出更有建设性的意见。拜谢了！
Flow2Spec
Flow2Spec 把配置根里的知识库（rules/、skills/、docs-index.md、stock-docs/ 等）与业务代码串成一条可日复一日的闭环：先落盘可加载的约定与索引 → 日常提问与实现都优先就着知识库走 → 随时可用 f2s-kb-feat / f2s-kb-fix 扩展或纠错并写回规则与技能；实现后（或阶段收尾）再用 f2s-kb-sync 将会话/现状沉淀进知识库，下一轮对话立刻继承，少在聊天与零散文档里重复对齐口径。
闭环为什么省事：能力拆成一组 f2s-* 技能（skills/<标识>/SKILL.md），按「当前在闭环的哪一环」选用即可；init 一次把目录与模版备好，后续主要是对话里触发技能 + 确认大纲/路径，不必自己拼一套文档治理流程。
渐进式读取带来的开发体验：main.mdc（唯一 alwaysApply）先给总览与入口；docs-index.md 虽不进自动上下文，但 main 生成时会写入「先打开 docs-index 再按表找 Rule/Skill」的必读约定**，从而先索引、再专题规则/技能、再 **stock-docs/` 长文、必要时才下钻业务代码；上下文层层加深而非整仓硬塞，更省 token、更少噪声，回答更贴已写进知识库的约定与模块边界。
在配置根的父目录执行 flow2spec init 写入所选 AI 工具目录（默认 .cursor/，亦可 .claude/、.codex/ 等）。命令与顺序见 README-命令说明，目录分工见 目录与路径约定，对话示例见 Flow2Spec-使用案例-模拟对话。
快速开始
# 在目标代码仓库（配置根的父目录）执行（默认仅写入 .cursor/）
npx @double-codeing/flow2spec init
# 指定 AI 工具配置目录（可多选）
npx @double-codeing/flow2spec init claude
npx @double-codeing/flow2spec init cursor claude codex
# 或全局安装后
npm install -g @double-codeing/flow2spec
flow2spec init
- 模板按所选 agent 写入对应配置根（如
.cursor/、.claude/、.codex/）下的rules/、skills/、template/与预建stock-docs/（存量上下文源）、req-docs/（需求与技术方案，按代码实现）。目录分工见 目录与路径约定。 - 工作流说明在
skills/<标识>/SKILL.md；在 Cursor 中由 Agent 按场景加载对应 Skill。 - 可用
flow2spec --help查看全部 agent 名称与示例。
init 详解：Flow2Spec使用说明 - init 做了什么。
能力与入口（速览）
| 环节 | 典型技能 / 用法 |
|---|---|
| 沉淀知识库 | f2s-doc-arch → f2s-doc-final → f2s-ctx-build（终稿进 stock-docs/，产出 Rules、Skills、索引） |
| 按方案写代码 | req-docs/ 下技术方案 MD + implement-tech-design；仅有 PDF 时可用 f2s-doc-pdf |
| 纠错与扩展 | f2s-kb-feat、f2s-kb-fix（任意时机） |
| 实现后写库 | f2s-kb-sync（会话/现状 → 大纲确认后写库） |
更细的入参、输出与顺序：README-命令说明 · 使用手册：Flow2Spec使用说明 · 使用案例：Flow2Spec-使用案例-模拟对话。
原理与流程图解
下图与「闭环日常流」「渐进式读取」一一对应；技能标识以 f2s-* 为准，与图不一致处以 README-命令说明 为准。
命令明细（名称、作用、使用时机与频率）
日常操作与项目仓库（知识库与业务代码）
init 与配置根结构（以 .cursor 为例）
main.mdc 与 docs-index.md
简述：知识库与代码闭环
文档导航
| 文档 | 说明 |
|---|---|
| Flow2Spec使用说明 | 使用手册：init、目录约定、推荐顺序、典型流程、技能与工作流、常见问题 |
| Flow2Spec-使用案例-模拟对话 | 对话版式与场景：真实输入、命令解释、渐进读取与 f2s-* 示例 |
| README-命令说明 | 各命令入参/输出、按使用顺序查找、快速参考 |
| README-目录与路径约定 | 配置根下 stock-docs/、req-docs/ 等结构、路径与链接约定、文档产物阶段 |
| README-体系与原理 | 架构、设计原则、main 与 docs-index 区别 |
CLI
| 命令 | 说明 |
|---|---|
flow2spec init [agent ...] | 将模板写入所选配置根（默认 cursor → .cursor/）；详见 flow2spec --help |
flow2spec --help | 查看用法、可选 agent（cursor / claude / codex）与示例 |
技能列表与速查见 Flow2Spec使用说明。
Flow2Spec 使用案例（模拟日常对话）
统一版式（后文每段相同）：你里只放真实会发给 AI 的内容（常以 /技能名 或 技能名 开头，后接路径或自由简述）；紧接 （命令解释，非用户输入） 告诉读者这句在做什么（勿复制进对话）；再 Agent（示意） ；必要时一行 说明（Skill 级注意点）。
配置根 .cursor/ ，仓库根已 flow2spec init。顺序总表：README-命令说明 · 按使用顺序查找。
文档：Flow2Spec使用说明 · README-命令说明 · README-目录与路径约定 · README-体系与原理
| 项 | 假设 |
|---|---|
| 项目 | 后端服务「订单服务」 |
| 仓库布局 | 业务代码与 .cursor/ 在同一仓库；stock-docs/ 放终稿类材料，req-docs/ 放按方案实现的 MD |
| 你的目标 | 先落架构上下文，再按方案改代码，最后按需写回知识库 |
场景一：架构初稿 → 终稿 → 上下文
你
/f2s-doc-arch 先帮我出一份架构初稿，侧重订单创建、支付回调、幂等与消息投递这几块，对应文件是 xxxx、xxx。
（命令解释，非用户输入）
「对应文件是 …」：让 AI 优先按所列路径读/扫再写初稿，避免无边界扫仓。**「侧重……」**可自由描述、简述或概述。
xxxx、xxx换成真实路径或目录。
Agent（示意）
按 f2s-doc-arch 结合你给的
xxxx、xxx，产出stock-docs/订单服务架构说明_初稿.md（文件名以实际为准）。
说明：无路径、拟扫全仓时，Skill 会先请你确认再扫。
你
/f2s-doc-final stock-docs/订单服务架构说明_初稿.md
（命令解释，非用户输入）
初稿已确认，本条触发 f2s-doc-final：把初稿收成
_终稿.md（路径/方案名以本轮输出为准）。
Agent（示意）
已生成
stock-docs/<方案名>_终稿.md（以实际文件名为准）。
你
f2s-ctx-build stock-docs/订单服务架构说明_终稿.md
（命令解释，非用户输入）
「f2s-ctx-build」 + 终稿路径：用该终稿刷新
main.mdc、专题rules/*.mdc、skills/、docs-index.md等（路径与上一步生成的_终稿.md对齐即可）。
Agent（示意）
已按该终稿路径更新或生成 main / rules / skills / docs-index。
你（日常业务提问，不必提 main / docs-index）
支付回调如果第三方重复推送同一条，我们这边怎么保证幂等的？会动哪些表或状态？
（命令解释，非用户输入）
普通业务问句：用户不触发 f2s-*；Agent 依赖已注入的
main.mdc约定，经docs-index.md找到专题 Rule/Skill，再按需下钻stock-docs/终稿长文（必要时才看代码），渐进查齐再回答。
Agent（示意）
（示意）按 main 的入口说明打开 docs-index，定位到支付/回调相关 rule；对照
stock-docs/里订单与支付章节后回答：幂等键、去重或落库策略、状态如何迁移（具体以你们仓库终稿与代码为准）。
场景二：按方案改代码
你
按方案实现：
.cursor/req-docs/订单支付改造_技术方案.md只改PaymentCallbackHandler，不要动其它模块。
（命令解释，非用户输入）
「按方案实现」 +
req-docs/下方案 MD：触发implement-tech-design。后面是范围/约束，可自由简述，不必固定话术。
Agent（示意）
已按
rules/implement-tech-design.mdc，以该req-docs/文件为准改代码。
场景三：PDF → MD → 按方案
你
/f2s-doc-pdf /Users/me/Downloads/订单流程_v3.pdf
（命令解释，非用户输入）
把 PDF 转成
req-docs/下 MD（具体文件名以 SKILL 与约定为准），便于再走「按方案实现」。
Agent（示意）
已生成
req-docs/订单流程_v3.md（示例名，以实际为准）。
你
按方案实现：
.cursor/req-docs/订单流程_v3.md
（命令解释，非用户输入）
与场景二相同：方案路径 + 「按方案实现」；上一段 PDF 已落成 MD 后接本条。
Agent（示意）
已按该
req-docs/MD 与 implement-tech-design 实现。
场景四：任意时机 · 新约定（f2s-kb-feat）
你
/f2s-kb-feat 对外 API 的 requestId 统一从 Header
X-Request-Id透传并打日志，请同步 rules/skills。
（命令解释，非用户输入）
f2s-kb-feat 任意时机可用；后面是新能力/新约定的自由描述，不必等「实现后」。本技能通常要求 代码与文档/知识库一起对齐：既改实现，也同步
rules/、skills/（及stock-docs/等说明类 MD、docs-index / main 中相关表述），避免「只写代码、规则仍写旧口径」。
Agent（示意）
已按 f2s-kb-feat 补实现或对齐现有代码，并同步增补或修订
rules/、skills/（及必要时 docs-index / main、相关stock-docs/段落）。
场景五：实现后或收尾 · 写库（f2s-kb-sync）
你
/f2s-kb-sync 支付失败重试队列命名、死信表字段、监控告警口径——先给知识库更新大纲，我确认后再写。
（命令解释，非用户输入）
f2s-kb-sync 典型在实现后或阶段收尾；「先大纲」 明确要走「大纲 → 你确认 → 再写入」流程。
Agent（示意）
先输出更新大纲；你确认后再写入
rules/、skills/、docs-index.md等。
场景六：任意时机 · 纠错（f2s-kb-fix）
你
/f2s-kb-fix
OrderService里new RestTemplate()，规则要求用注入的 Bean；请改代码并同步架构说明和对应 rule。
（命令解释，非用户输入）
f2s-kb-fix 任意时机；须点明违规点与期望；后面可自由补「还要同步哪些文档」。与 f2s-kb-feat 同理，通常 代码与文档/知识库一起对齐：修正实现的同时，把
rules/、skills/及stock-docs/等说明里仍写错口径的地方一并改掉，避免修完代码、规则仍误导后续对话。
Agent（示意）
已按违规点修正代码，并同步
rules/、skills/及你点名的架构说明等文档（及必要时 docs-index / main、相关stock-docs/段落），消除不一致。
场景七：merge / rebase 后 · 知识库冲突（f2s-kb-merge）
你
/f2s-kb-merge
.cursor/docs-index.mdrules/payment.mdc里还有冲突标记，知识库能自动合并的请处理，业务源码我已手动合完。
（命令解释，非用户输入）
f2s-kb-merge 处理 docs-index / main / rules / skills 等知识库侧冲突；业务源码一般不在此条自动合并范围内，由你说明「已手动」即可。
Agent（示意）
已清理所列文件中的冲突标记；未授权的业务源码保持不动。
场景八：把某路径下的模块写进全局文档（f2s-kb-feat）
你
/f2s-kb-feat 将【路径】功能模块写入全局文档。
（命令解释，非用户输入）
【路径】换成仓库里真实目录或包（如
src/order/、com.example.billing所在根）。本条仍是 f2s-kb-feat：让 AI 读该路径下代码/结构，把模块职责、边界、对外接口、关键约定沉淀到全局可加载的rules/、skills/、stock-docs/（摘录或补篇）、docs-index.md/main.mdc等，与现有实现一致；若代码缺文档或规则缺块，可顺带补实现再对齐。
Agent（示意）
已按【路径】梳理模块并写入/更新
stock-docs/与rules/、skills/（及 docs-index 等），保证后续对话能通过索引渐进找到该模块说明。
速查（真实输入范式）
| 目的 | 你（示例，路径请替换） |
|---|---|
| 日常业务问答 | 自然语言直接问（不带 /f2s-*）；Agent 按 main → docs-index → Rule/Skill → stock-docs 渐进查后答，见场景一末段 |
| 架构初稿 | /f2s-doc-arch …侧重… 对应文件是 路径1、路径2 |
| 初稿→终稿 | /f2s-doc-final stock-docs/xxx_初稿.md |
| 终稿→上下文 | f2s-ctx-build stock-docs/xxx_终稿.md |
| PDF→MD | /f2s-doc-pdf PDF 绝对路径或项目内路径 |
| 按方案实现 | 按方案实现： req-docs/某.md + 自由约束简述 |
| 新约定 | /f2s-kb-feat + 自由描述（通常 代码 + rules/skills/文档 一并补齐） |
| 模块写入全局文档 | /f2s-kb-feat 将 【路径】 功能模块写入全局文档（ 【路径】 换真实目录/包） |
| 写库先大纲 | /f2s-kb-sync + 范围 + 先给大纲确认再写 |
| 纠错 | /f2s-kb-fix + 违规点 + 期望（通常 代码 + rules/skills/文档 一并校正） |
| 删某文档上下文 | f2s-ctx-rm + stock-docs/…（见命令说明 §2.4） |
| 合并知识库冲突 | /f2s-kb-merge + 文件/范围 + 边界说明 |
f2s-* 各场景在正文里都有 （命令解释，非用户输入） 段；日常业务问见场景一末段（无技能名，靠渐进读取）。
相关文档
| 文档 | 用途 |
|---|---|
| Flow2Spec使用说明 | init、目录、推荐顺序 |
| README-命令说明 | 各技能入参/输出、总表、§6 速查 |
| README-目录与路径约定 | stock-docs / req-docs、产物 |
| README-体系与原理 | main、docs-index、拆解原则 |
