一次关于 AI 需求交付Skills的优化升级
AI需求交付工具v4.0.0重磅升级，针对澄清漏项和Token冗余问题，重构三层架构实现精准控制。核心内容：1. 重构三层架构：跨阶段规则、项目路径、阶段门控2. 解决核心问题：需求澄清漏项与Token使用优化3. 具体规则示例：禁止字段猜测、统一文档编号等
01｜这次优化，来自后台的一条留言
最近收到后台朋友的留言，核心反馈很直接：
需求在澄清阶段、文档完成阶段，总会有一些缺失；而且整个过程 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 检查脚本。
这些能力解决了“能不能用”的问题。
但后台朋友提到的两个问题，属于另一个层面：
- ：这是阶段边界和门控的问题；
需求澄清和文档完成容易漏项
- ：这是上下文加载模型的问题。
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 | 指向项目文档命名、编号、输出目录规范 |
这里有一个重要设计：
Paths 不存放大段知识正文，只存放“去哪里读”的指针。
这样做有三个好处。
第一，真实项目知识不会污染工具仓库。每个团队、每个项目可以有自己的知识库。
第二，Token 不会爆炸。当前阶段只读当前阶段需要的路径，不会把全部背景一次性塞进上下文。
第三，后台朋友、团队成员、业务方提出的建议，都可以沉淀进项目自己的知识源，再通过 paths/*.md 引入。
例如：
- 有人反馈“字段经常写错”，可以把字段映射表补进
knowledge-path指向的数据字典； - 有人反馈“PRD 验收标准太虚”，可以把验收模板补进项目知识库，并由
goal-boundary门控检查； - 有人反馈“合规评审漏了隐私条款”，可以在
compliance-path里启用隐私规则文档； - 有人反馈“文档命名不符合团队习惯”，可以在
doc-naming-path中覆盖默认文件名。
也就是说，用户建议不是临时加进提示词，而是可以变成项目资产。
05｜门控：不再让 AI “感觉差不多就继续”
第三个关键词是门控。
v4.0.0 里，门控分成三类：
- ：上一个阶段没有签字，不能进入下一个阶段；
阶段门控
- ：文档缺章节、缺验收、缺字段对齐，不能通过；
内容门控
- ：没有说清楚“本次做到什么程度”，不能往后写。
目标边界门控
这次重点补强的是需求澄清和文档完成两个位置。
需求澄清阶段：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。
它不再试图塞进所有规则，而只做四件事：
- 选择具体 Skill；
- 读取该 Skill 声明的
Required rules； - 读取该 Skill 声明的
Required paths； - 禁止一次性全量加载所有规则和路径。
这就是 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 消耗还有进一步压缩空间。
都可以继续留言。
接下来我会优先把这些反馈分成两类处理：
- ：沉淀进
通用规则
rules/，变成所有项目都能复用的约束； - ：通过
项目知识
paths/引入，让每个团队保留自己的上下文和规范。
一句话总结 v4.0.0：
