一次关于 AI 需求交付Skills的优化升级

最近收到后台朋友的留言，核心反馈很直接：

需求在澄清阶段、文档完成阶段，总会有一些缺失；而且整个过程 Token 量有点大。

这其实是很多 AI 需求分析工具都会遇到的问题。

不是模型不会写，而是它太“勤快”了：

• 需求没完全澄清，它会尝试补全；
• 字段没给清楚，它会根据经验猜一个；
• 文档缺一节，它可能继续往下推进；
• 每个阶段都把所有背景重新加载一遍，Token 自然越跑越大。

所以这次我们没有只做“提示词优化”，而是把整个项目结构做了一次重构。

v4.0.0 的核心目标只有一句话：

让 AI 在该停的时候停下来，在该读的地方精准读取，在该校验的时候被机器拦住。

02｜v3.0.0 已经能跑，为什么还要做 v4.0.0？

v3.0.0 更像是一个“能把流程跑起来”的版本。

它补齐了大量工具链能力，比如：

• ASCII 流程图转 Mermaid / Draw.io；
• VSCode 扩展雏形；
• 多行业示例；
• README 和使用说明；
• 基础的 SQL、字段、QA 检查脚本。

这些能力解决了“能不能用”的问题。

但后台朋友提到的两个问题，属于另一个层面：

1. 需求澄清和文档完成容易漏项
   ：这是阶段边界和门控的问题；
2. Token 量偏大
   ：这是上下文加载模型的问题。

如果继续在 v3.0.0 上堆更多说明，短期会好一点，但长期会越来越臃肿。

所以 v4.0.0 选择把项目拆成三层：

• Rules
  ：跨阶段都必须遵守的规则；
• Paths
  ：项目自己的知识库、技术栈、合规、命名路径；
• Gates
  ：阶段推进前的机器校验和用户签字。

这三个概念，是 v4.0.0 和 v3.0.0 最大的区别。

03｜Rules：把“经验提醒”变成“跨阶段规则”

以前很多规则散落在不同 Skill 里。

比如：

• 不要猜字段；
• 不要自创表名和状态码；
• SQL 方言要对齐 Oracle / PostgreSQL / MySQL；
• 文档编号不要冲突；
• 流程图用 ASCII；
• 阶段未签字不能推进。

这些不是某一个阶段的小提示，而是整个交付过程都要遵守的“不变式”。

所以 v4.0.0 把它们统一迁移到了 rules/ 目录。

当前包括：

这带来的变化是：

规则不再靠“模型记得”，而是靠文件声明和脚本检查。

例如 dev-design 阶段需要字段、技术栈、SQL 和目标边界，就声明自己需要哪些规则；compliance-review 阶段不需要 SQL，就不会额外加载 SQL 规则。

这就是 v4.0.0 控制 Token 的第一步：只加载当前阶段需要的规则。

04｜Paths：让项目知识跟着项目走，而不是跟着工具走

光有rules是不够的，第二个变化是 paths/，没有paths是没有办法让rules走到他应该去的位置。

很多需求文档缺失，本质上不是 AI 不会写，而是它没有读到真实项目上下文。

比如：

• 真实字段在哪里？
• 数据字典在哪里？
• 技术栈约束在哪里？
• 合规条款在哪里？
• 这个项目文档到底放在哪个目录？

v3.0.0 里也有类似配置，但 v4.0.0 把它们规范成了 canonical paths/层：

这里有一个重要设计：

Paths 不存放大段知识正文，只存放“去哪里读”的指针。

这样做有三个好处。

第一，真实项目知识不会污染工具仓库。每个团队、每个项目可以有自己的知识库。

第二，Token 不会爆炸。当前阶段只读当前阶段需要的路径，不会把全部背景一次性塞进上下文。

第三，后台朋友、团队成员、业务方提出的建议，都可以沉淀进项目自己的知识源，再通过 paths/*.md 引入。

例如：

• 有人反馈“字段经常写错”，可以把字段映射表补进 knowledge-path 指向的数据字典；
• 有人反馈“PRD 验收标准太虚”，可以把验收模板补进项目知识库，并由 goal-boundary 门控检查；
• 有人反馈“合规评审漏了隐私条款”，可以在 compliance-path 里启用隐私规则文档；
• 有人反馈“文档命名不符合团队习惯”，可以在 doc-naming-path 中覆盖默认文件名。

也就是说，用户建议不是临时加进提示词，而是可以变成项目资产。

05｜门控：不再让 AI “感觉差不多就继续”

第三个关键词是门控。

v4.0.0 里，门控分成三类：

1. 阶段门控
   ：上一个阶段没有签字，不能进入下一个阶段；
2. 内容门控
   ：文档缺章节、缺验收、缺字段对齐，不能通过；
3. 目标边界门控
   ：没有说清楚“本次做到什么程度”，不能往后写。

这次重点补强的是需求澄清和文档完成两个位置。

需求澄清阶段：TASK_CONFIRM 必须完整

v4.0.0 增加并强化了 task-confirm-check.py。

它会检查：

• 状态字段是否已经确认；
• 是否还残留 TBD / TODO / 待确认等红线词；
• TASK_CONFIRM 是否包含必要章节；
• REVIEW 文档里是否还有未关闭的问题；
• 字段对齐里是否还有红色阻断或未知项。

并且，进入 BRD 需要用户明确签字。

不是“好”“继续”“OK”就自动通过，而是要使用白名单话术，例如：

• 我已全部确认，可以进入下一步；
• 确认通过，进入 BRD；
• 全部完成，继续；
• approved, proceed to next stage。

这样做不是为了麻烦用户，而是为了防止 AI 把模糊回复误判为授权。

文档完成阶段：目标边界必须可验收

另一个新增重点是 goal-boundary。

很多 PRD 写到最后会失控，是因为一开始没有明确：

• 最终业务目标是什么；
• 本次交付完成定义是什么；
• 成功指标怎么量化；
• 明确不解决哪些问题；
• 如果分阶段，MVP / Phase 1 / Phase 2 分别交付什么。

v4.0.0 会把这些内容前置到 TASK_CONFIRM，并在 PRD、测试用例、HANDOVER 中继续追踪。

这意味着一个需求不能只写“做完核心流程”。

它必须变成类似这样的表达：

本次交付：完成收货主流程 MVP。
不解决：报表导出、批量导入、复杂权限配置。
验收指标：主流程 E2E 通过，关键接口 P95 < 3s，字段对齐阻断项为 0。

这就是门控的价值：

把“看起来写完了”变成“可以被检查地完成了”。

06｜v4.0.0 相比 v3.0.0，到底变了什么？

可以用一张表概括。

一个比较明显的代码层变化是：根 SKILL.md 被压缩成 thin router。

它不再试图塞进所有规则，而只做四件事：

1. 选择具体 Skill；
2. 读取该 Skill 声明的 Required rules；
3. 读取该 Skill 声明的 Required paths；
4. 禁止一次性全量加载所有规则和路径。

这就是 v4.0.0 对 Token 的核心处理方式。

07｜一个更实际的例子

假设我们要做一个“收货管理优化”。

在 v3.0.0 里，AI 可能会把大量项目背景、规则说明、工具说明一起读进来，然后开始写需求文档。

在 v4.0.0 里，流程会更像这样：

用户提出需求 │ ▼选择 grill-task 阶段 │ ├─ 读取 Required rules: │ stage-gate / no-field-guessing / context-pointer / goal-boundary │ ├─ 读取 Required paths: │ knowledge-path / doc-naming-path │ ▼生成 TASK_CONFIRM + REVIEW │ ▼运行 task-confirm-check / goal-boundary-check │ ├─ 通过：用户明确签字，进入 BRD │ └─ 不通过：停下来补齐，不自动推进

注意这里没有加载 sql-dialect、tech-stack-path、compliance-path。

因为需求澄清阶段暂时不需要它们。

等进入开发设计阶段，才会加载 SQL、技术栈、数据模型相关规则。

这就是按需加载带来的直接收益：

• 上下文更短；
• 输出更聚焦；
• 漏项更容易被定位；
• 用户建议更容易被沉淀到正确位置。

08｜这次优化想解决的，不只是“写文档”

很多人会把 AI 需求工具理解为“帮我写 BRD / PRD”。

但实际做项目时，真正痛的不是写，而是：

• 哪些信息没问清楚；
• 哪些边界没锁住；
• 哪些字段是猜的；
• 哪些验收标准不可测；
• 哪些文档看起来完成，其实不能交付；
• 哪些项目经验没有沉淀，下次还会再错。

v4.0.0 想解决的是这些问题。

所以它不是单纯加了几个脚本，而是把工作流从“生成文档”往“可控交付”推进了一步。

09｜最后：欢迎继续把问题丢给我

这次 v4.0.0 的优化，起点就是后台朋友的一条留言。

如果你在使用过程中也遇到类似问题，比如：

• 某个阶段经常漏项；
• 某类字段总是被猜错；
• 某个行业合规规则需要加入；
• 某种文档格式希望固定下来；
• 某个门控太松或太严；
• Token 消耗还有进一步压缩空间。

都可以继续留言。

接下来我会优先把这些反馈分成两类处理：

1. 通用规则
   ：沉淀进 rules/，变成所有项目都能复用的约束；
2. 项目知识
   ：通过 paths/ 引入，让每个团队保留自己的上下文和规范。

一句话总结 v4.0.0：

少一点“AI 自己发挥”，多一点“项目真实约束”；少一点“文档看起来完整”，多一点“每一步都能被检查”。