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

AI需求交付工具v4.0.0重磅升级，针对澄清漏项和Token冗余问题，重构三层架构实现精准控制。
核心内容：
1. 重构三层架构：跨阶段规则、项目路径、阶段门控
2. 解决核心问题：需求澄清漏项与Token使用优化
3. 具体规则示例：禁止字段猜测、统一文档编号等

01｜这次优化，来自后台的一条留言

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

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

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

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

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

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

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

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/ 目录。

当前包括：

Rule	作用
stage-gate	控制 9 阶段、开发子流程、子任务三层门控
no-field-guessing	禁止根据业务词随意猜数据库字段 / API 字段
no-self-invent	禁止自创表名、状态码、业务常量
ascii-flowchart	统一流程图表达，避免 Mermaid 在终端里不可读
sql-dialect	SQL 必须标注目标数据库，禁止方言混用
doc-numbering	01-09 文档编号固定，防止文档引用错乱
context-pointer	只读项目声明的上下文，缺失就问，不允许编造
goal-boundary	明确本次做到什么程度、什么不做、如何验收

这带来的变化是：

例如 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/层：

Path	作用
knowledge-path	指向业务术语、数据字典、既有流程文档
tech-stack-path	指向后端、前端、数据库、集成约束
compliance-path	指向通用合规、行业规则、隐私规则
doc-naming-path	指向项目文档命名、编号、输出目录规范

这里有一个重要设计：

这样做有三个好处。

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

第二，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，到底变了什么？

可以用一张表概括。

维度	v3.0.0	v4.0.0
核心目标	工具链增强，流程跑通	结构治理，减少漏项和 Token 浪费
规则组织	规则散落在 Skill / discipline 中	统一迁移到 canonical rules/
项目上下文	有配置思路，但入口不够统一	统一为 canonical paths/
加载方式	容易加载过多背景	选中 Skill 后只加载声明的 rules / paths
需求澄清	主要靠模板和人工确认	TASK_CONFIRM + REVIEW + 字段对齐 + 白名单签字
文档完整性	部分脚本检查	多阶段门控脚本 + goal-boundary 追踪
Token 控制	依赖人为克制	通过 thin root router 和按需加载控制
用户建议沉淀	容易停留在提示词层	可以沉淀到项目知识源，再由 paths 引入
兼容性	v3 结构	保留 legacy wrapper，逐步迁移

一个比较明显的代码层变化是：根 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：