SpecForge V3 发布：功能级 Skill 的一次彻底重做
前言
之前发布了 SpecForge V2 版本，感谢大家的支持。这段时间一直在用这套工作流实际开发项目，用到最后发现了一个根本性的问题，V2 的 Skill 太像操作手册了，人读着费劲，AI 执行起来又太僵硬。于是花了不少时间，对功能级的五个 Skill 进行了近乎完全的重做，形成了 V3 版本。
项目级 Skill 本次没有更新，这次更新完全集中在功能级，也就是你日常开发中使用频率最高的部分。
一、更新了什么
1. 设计理念变了
V2 的 Skill 本质上是操作手册，步骤一做什么、步骤二做什么，写了九步，AI 从头到尾走一遍。对话格式也是预设好的，选项 A 怎样、选项 B 怎样、推荐哪个，不管什么场景都是这套格式。同一条规则还在好几个地方重复写，措辞还不一样。
V3 换了个思路。不再一步步教 AI 做什么，而是告诉它：你是什么角色、你要关注哪几个方面、你的底线在哪。至于具体先做什么后做什么、怎么跟用户沟通，让它自己判断。
简单说就是从操作手册变成了角色设定。
2. 编码阶段引入了 TDD
V2 的编码是按方案写代码，写完检查。V3 改成了 TDD，也就是 Red-Green-Refactor 循环：先写一个会失败的测试，再写刚好能让测试通过的代码，最后在测试保护下重构。
TDD 的影响不止于编码阶段。因为编码时必须先写测试，AI 就必须知道测什么。测什么来自验证标准，验证标准来自技术方案，技术方案来自需求。这意味着前面每个阶段的 AI 都会自动把精度拉上去，用户不需要操心这些，你说「我要个评论功能」就够了，AI 会在需求阶段通过对话帮你补全细节，在技术方案阶段自己把接口定义写清楚，在任务规划阶段自己把验证标准写具体。
换句话说，不是要求用户写得更精确，而是 TDD 倒逼 AI 在每个阶段都不敢糊弄，因为它知道最后要靠这些信息来写测试。
3. AC 贯穿了整条链路
AC 就是验收标准，V2 里也有，但各阶段各写各的，没有严格的对应关系。V3 要求每条 AC 必须在后续每个阶段都能找到落点。
举个例子，需求阶段产出了一条 AC：
AC-001: Given 用户已登录，When 发布评论，Then 评论出现在列表顶部
那后续每个阶段都必须有它的着落：技术方案里要写清楚这条 AC 用什么接口实现、数据怎么存、排序逻辑是什么；任务规划里要有具体的任务来落地它；编码时要有测试来证明它确实做到了。
如果某条 AC 在技术方案的覆盖汇总表里找不到对应的设计点，说明有需求被遗漏了。如果任务规划里没有任务覆盖某条 AC，说明有东西没人做。每个阶段都在检查上一个阶段有没有漏东西，链路本身就是检查机制。
4. 输出模板大幅精简
V3 对模板做了大幅精简：
| 模板 | V2 行数 | V3 行数 | 缩减幅度 |
|---|---|---|---|
| 任务规划模板 | 303 行 | 84 行 | -72% |
| 阶段完成报告模板 | 178 行 | 55 行 | -69% |
| 功能迭代模板 | 190 行 | 126 行 | -34% |
砍的不只是篇幅，更重要的是去掉了固定的分类结构。V2 的任务规划模板预设了数据层、表现层、业务逻辑层、Mock 数据、异常处理五个阶段，还附带了 Task-01 到 Task-08 的完整示例。问题是假如一个纯前端功能哪来的数据层？一个简单的工具函数需要五个阶段吗？AI 只能硬套模板，输出一堆「无」和「N/A」的占位内容。
V3 的模板只给结构骨架，阶段名称写的是 {{阶段名称}}，具体分几个阶段、叫什么名字，由 AI 根据功能实际情况来定。不涉及的部分直接跳过，不写占位。
阶段完成报告也一样，V2 有 8 个章节，含测试覆盖率统计、AC 验证清单、后续行动计划等。V3 砍到 6 个，因为 TDD 循环本身已经保证了测试覆盖，不需要在报告里再重复证明一遍。
5. 各 Skill 的具体变化
| Skill | V2 → V3 关键变化 |
|---|---|
| 需求澄清 | 四步线性问卷 → 五维自然对话，去掉预设提问模板 |
| 技术方案 | 九步线性流程 → 四维并行思考，规则去重 |
| 任务规划 | 测试是独立任务 → 测试融入 TDD 执行，新增通俗解释字段和验证标准质量要求 |
| 编码实现 | 写代码+检查 → 强制 TDD，去掉机械确认仪式 |
| 功能迭代 | 固定选项分类 → 自然对话 + 70% 阈值判断 |
二、为什么要这么做
V2 把 Skill 写成了详细的操作手册，试图控制 AI 的每一个动作。看起来很严谨，实际用下来发现了三个问题，V3 逐一解决。
第一，AI 被锁死在固定路径上。九步线性流程，不管面对的是一个简单的按钮还是一个复杂的支付系统，AI 都走同样的九步。真正有经验的人不会这样工作。V3 改成列出 AI 需要关注的几个维度，先做什么、挖多深，由实际情况决定。
第二，预设模板导致千篇一律的输出。选项 A 怎样、选项 B 怎样、推荐 A 理由是什么，不管什么场景，AI 都输出一模一样的格式化内容，对话变成了问卷调查。V3 只告诉 AI 当有多种方案时给出选项和推荐理由，具体怎么表达由它根据场景判断。
第三，规则重复导致权威模糊。同一条规则在三个地方说三遍，措辞还不完全一样，AI 不知道哪个版本是对的。V3 每条规则只在最合适的位置写一次，完整表述，不重复不分散。
除了解决这三个问题，V3 还带来两个额外的好处。一是通用性更强，V2 的模板带有明显的项目特征，预设了数据层、表现层这些分类，换个项目就不适用，V3 去掉了这些假设，几乎适用于任何项目。二是 TDD 带来了可靠的质量保障，不再是写完代码自己看看对不对，而是每一行实现代码都有测试兜底。
三、完整项目流程教程
下面以开发一个搜索功能为例，完整走一遍功能级工作流。
第一步：把想法变成需求
Skill: feature-requirements-clarification
你带着一个模糊的想法来找 AI，比如「我想给文章列表加个搜索」。这一步 AI 的角色是你的产品搭档，通过自然对话帮你把想法变成具体可测试的需求。
它会同时关注五个维度：场景与用户、核心流程、边界与异常、业务规则、范围。但这不是执行顺序，而是它脑子里同时在转的几个问题。你说「搜标题就行」，它可能会追问「正文要不要搜？标签呢？」；你提到「支持筛选」，它会接着聊筛选条件之间是什么关系、能不能组合；你说「先不做搜索历史」，它就把这个划到范围外，不再纠缠。全程不聊技术，只聊用户能做什么。
这个阶段最重要的产出是验收标准 AC，每条用 Given-When-Then 格式描述一个具体场景：
AC-001: Given 用户在文章列表页，When 在搜索框输入关键词并回车，Then 列表只显示标题包含该关键词的文章
AC-002: Given 用户搜索了一个不存在的关键词，When 结果为空，Then 显示「没有找到相关文章」的提示
产出文件：specs/features/搜索功能.md
第二步：把需求变成技术方案
Skill: feature-tech-design
需求搞清楚了，现在想怎么实现。AI 这时候的角色是技术搭档，要做的是真正的设计决策，而不是填模板。
比如搜索功能就涉及几个决策：用数据库 LIKE 查询还是接 Elasticsearch？搜索要不要做防抖？筛选条件怎么传给后端，拼 query string 还是用 POST body？这些决策如果沿用项目已有的做法，AI 会直接定，不问你。但如果需要引入新依赖或者有多种可行方案，它会暂停让你确认。
方案末尾有一张 AC 覆盖汇总表，一眼就能看到每条 AC 是否都有对应的技术设计点。
产出文件：specs/features/搜索功能_技术方案.md
第三步：把方案拆成任务
Skill: feature-task-planning
技术方案不能直接丢给 AI 说按方案写代码，一口气做太多，上下文过长会导致质量下降。这一步 AI 的角色是技术主管，把方案拆成一个个原子任务，每个 30 分钟到 2 小时，单一职责，可独立验证。同时理清依赖关系，用 Mermaid 图展示。
这一步最关键的是验证标准的质量。因为验证标准直接就是 TDD 红灯阶段的输入，写得好，开发时就知道第一个测试该怎么写。比如：
差的写法：搜索接口返回正确数据
好的写法：GET /api/articles?q=Next.js，返回 200，body 中每篇文章的 title 都包含「Next.js」，不包含的不出现在结果中
每个任务还有一行通俗解释，用零技术术语描述用户可见的变化，比如「完成后，用户在列表顶部能看到一个搜索框，输入关键词回车后列表会刷新」。
另外，测试不是独立的任务。因为每个任务都通过 TDD 执行，测试内嵌在执行过程中。
产出文件：specs/features/搜索功能_任务规划.md
第四步：写代码
Skill: feature-implementation
前面铺垫了这么多，到这一步其实是最轻松的，AI 要做什么已经写得清清楚楚了。它的角色是一个严格践行 TDD 的开发者，逐阶段执行任务。
每个任务走 Red-Green-Refactor 循环：
- 红灯：根据验证标准写测试，运行，确认失败。失败原因应该是功能未实现，不是语法错误
- 绿灯：只写让测试通过所需的最少代码，跑全量测试防止回归
- 重构：在测试保护下优化代码，简单任务可以跳过
TDD 循环完成后根据任务性质选择验收方式。UI 任务用 Playwright 在浏览器中操作验证，纯后端任务靠单元测试覆盖，数据库变更通过查询验证。
铁律只有一条：没有失败的测试，就不写实现代码。
每个阶段完成后会生成报告，里面有个技术债务区域，用来记录开发中务实的妥协。重要的是记录下来，不是假装它们不存在。
产出文件：代码 + 更新后的任务规划（完成的打勾）+ docs/开发记录/搜索功能_阶段N_完成报告.md
番外：功能做完后又有新想法
Skill: feature-evolution
搜索做完了，用了几天觉得还想加个搜索历史，或者要支持按时间范围筛选。这种对已完成功能的增量修改，用这个 Skill。
AI 会从四个层面分析变更影响：需求层面 AC 要增删改哪些、技术层面数据库和接口要怎么动、代码层面哪些文件受影响、任务层面有没有进行中的任务被波及。
核心原则是改，不是重做。没受影响的内容原封不动，只在受影响的地方就地修改，末尾追加变更日志。
变更分三类：微调（不涉及新 AC）、扩展（新增 AC 或 API）、重构（改核心结构）。如果变更影响超过原始功能的 70%，AI 会建议你回到需求澄清重走流程，而不是硬做增量。这个劝退本身就是有价值的输出。
完成后生成增量的变更任务计划，再调用 feature-implementation 执行。
产出文件：增量更新的文档 + specs/features/搜索功能_变更任务_CR-001.md
全流程总结
你的想法：我想给文章列表加个搜索
│
▼
① feature-requirements-clarification 产品搭档，五维对话
产出：搜索功能.md（含 AC）
│
▼
② feature-tech-design 技术搭档，四维设计
产出：搜索功能_技术方案.md
│
▼
③ feature-task-planning 技术主管，原子拆分
产出：搜索功能_任务规划.md
│
▼
④ feature-implementation 开发者，TDD 执行
产出：代码 + 测试 + 完成报告
│
▼
功能上线
│
需求变更？
▼
⑤ feature-evolution 产品架构师，影响分析
产出：变更任务计划 CR-001
│
▼
回到 ④ 执行变更任务
贯穿整条链路的是 AC：需求产出 AC，技术方案映射 AC，验证标准对应 AC，TDD 测试验证 AC。任何一环断裂都会暴露。
四、写在最后
这次更新的本质，是从把 Skill 当操作手册变成了把 Skill 当角色设定。
旧版试图控制 AI 的每一个动作，结果是限制了它的能力。新版告诉 AI 它是谁、关心什么、底线在哪，然后让它在框架内自由发挥。
告诉 AI 要成为什么样的人，而不是规定它每一步要做什么动作。
GitHub 仓库：https://github.com/MingYuePop/SpecForge
