garveyhu req-to-ai-spec
将零散、模糊的产品需求转化为结构化的需求规格文档，任何AI编码代理读后即可无歧义地完成开发。
触发条件
当用户提到以下任意关键词时激活：req-to-ai-spec、需求转换、需求分析、需求文档、需求文档生成、需求转AI规格、AI spec，或描述了需要将产品需求转化为可实现规格的场景。
使用场景
- 开发者收到零散的产品笔记和Axure/Figma截图，需要在交给AI编码前生成结构化规格
- 与产品沟通后的口头讨论或聊天记录，需要转化为可实现、可测试的Task
- 团队希望在AI辅助开发前，确保边界情况和隐含规则被完整捕获
输入
| 输入 | 必需 | 形式 | 说明 |
|---|---|---|---|
| 需求描述 | 是 | 文字（可零散、非正式） | 与产品沟通后的文字笔记、聊天记录、口头总结 |
| 原型截图 | 否 | 图片文件路径 | Axure/Figma等原型截图 |
| 代码工作区 | 否（默认当前目录） | 目录路径 | 用于探索现有模式和数据结构的代码库 |
| 输出路径 | 否（默认docs/） |
文件路径 | 命名规范：YYYY-MM-DD-<slug>-spec.md |
完整性检查规则
- 需求描述是唯一必填输入。如果没有，请用户提供后再继续。
- 没有截图 → 问一次："有原型截图吗？没有也可以继续"。用户说没有就直接继续。
- 没有指定工作区 → 使用当前工作目录。
- 没有指定输出路径 → 默认
docs/YYYY-MM-DD-<slug>-spec.md。 - 有什么用什么，不要因为等待可选输入而阻塞流程。
工作流
第1步：输入收集与完整性检查
- 接收用户提供的所有材料（文字、文件路径、截图）。
- 识别四类输入中哪些已提供。
- 对缺失的可选输入，最多追问一个问题，不要连续追问。
- 如果已有信息足够生成文档，跳过追问直接进入下一步。
第2步：项目适配检测
- 检查当前环境可用的skill列表，寻找项目专用的概览skill。
- 匹配
*-overview命名模式（如ados-overview、myproject-overview）。 - 如果找到：调用Skill工具加载，获取项目领域知识（模块划分、术语体系、核心数据表），提升后续代码探索和约束发现的精准度。
- 如果没找到：跳过，仅依赖代码探索。
- 绝不在本skill中硬编码任何项目专属知识。 所有领域上下文必须来自动态加载的overview skill或代码探索。
第3步：代码探索（自主执行，内部消化）
本步骤静默执行。发现的信息用于辅助分析，不会原文引用到输出文档中。
- 根据需求关键词，用Grep和Glob工具搜索代码库中的相关Controller、Service、Repository、Model、配置文件。
- 沿调用链追踪最多3层（如Controller → Service → Mapper/Repository）。
- 目标：
- 理解现有模式（命名规范、分层架构、响应包装）
- 发现数据结构（表结构、实体字段、枚举值）
- 找到类似功能，推断新功能应遵循的模式
- 识别需求文字中未提及的边界情况 → 这些将成为输出中的
[推断]项
- 如果代码库为空、不可访问或无关 → 跳过，仅基于文字和截图工作。
- 收集到足够上下文后停止，不要过度探索。
第4步：需求分析与结构化
- 融合所有输入：文字描述 + 截图观察 + 代码理解 → 统一认知。
- 决定Task粒度：
- 整个需求能用一个Task表达？→ 保持一个。
- 有多个独立交付物？→ 拆分为多个Task。
- 单个Task的核心规则超过8条？→ 考虑继续拆分。
- 识别隐含规则：用户没提但代码库暗示的东西（如软删除模式、审计日志、权限检查）。
- 识别跨Task依赖：标注哪些Task依赖其他Task。
- 决定可选章节：根据输出模板的条件包含规则，判断是否需要术语表、全局约束、实现顺序。
第5步：输出文档生成
- 读取
references/output-template.md（与本SKILL.md同目录）获取标准文档结构和逐字段写作指引。 - 严格按模板生成规格文档，包括：
- YAML元数据（生成日期、源材料、工作区路径、skill版本）
- 所有适用章节（概述、术语表、全局约束、实现顺序、Task）
- 不适用的可选章节完全省略（不要留空章节）
- 通过代码探索发现的边界情况标记
[推断]，提示用户确认。 - 输出前执行模板中的质量检查清单。
- 将文档写入指定输出路径。
第6步：用户确认
- 向用户展示生成的文档（或确认写入的文件路径）。
- 问："请review这份需求文档，有需要调整的地方告诉我"
- 根据用户反馈修改，重复直到用户满意。
- 不要自动进入编码、计划或任何下一步。 规格文档是本skill的最终交付物。
行为规则
文档生成规则
- 输出语言跟随用户语言。 用户用中文描述需求则全文中文输出，用英文则英文输出。包括所有章节标题、规则、验收标准、术语表。
- 规则必须无歧义。 每条核心规则只表达一个逻辑分支。禁止使用"大概"、"可能"、"一般来说"、"酌情"、"适当处理"等模糊词。
- 主动补全边界情况。 从代码探索中推断的边界条件标记
[推断]，供用户确认。 - 不发明需求。 只能结构化和补全用户已表达的意图或代码库暗示的内容，推测必须标记。
- 截图提取业务规则，不描述UI实现。 提取"允许用户执行X操作"，而非"增加一个标记为X的按钮"。
Task拆分规则
- 每个Task必须可独立实现和测试。
- 单个Task的核心规则超过8条时考虑拆分。
- Task之间的依赖必须在"依赖"字段中明确标注。
- 多个Task存在先后顺序时，必须包含"实现顺序"章节并说明理由。
交互规则
- 一次只问一个问题，不要列出问题清单。
- 信息足够时不强制追问，直接生成文档。
- 生成文档后必须请用户review。
- 不要自动进入实现、任务创建或任何后续动作。
项目适配机制
本skill通过检测机制动态适配任何项目：
- 检测：激活时扫描环境中可用的skill，匹配
*-overview命名模式。 - 加载：找到后通过Skill工具调用，注入项目领域知识（模块边界、命名规范、核心数据表、公共工具）。
- 收益：更精准的代码探索、正确使用领域术语、更好地发现项目特有的约束和模式。
- 降级：无overview skill时，正常走代码探索和用户提供的上下文。
本skill零项目硬编码知识，所有适配均为动态。
限制（v1）
- 不支持增量更新。 每次调用从头生成，修改已有规格需重新走完整流程。
- 仅Markdown输出。 不支持PDF、Confluence等格式。
- 截图提取为尽力而为。 质量取决于图片分辨率和视觉模型能力。
- 代码探索深度有限。 最多追踪3层调用链，深层嵌套逻辑可能无法完全捕获。
输出
- 成功：一份自包含的Markdown规格文档，写入指定输出路径（默认
docs/YYYY-MM-DD-<slug>-spec.md）。 - 文档遵循
references/output-template.md中定义的结构和质量标准。 - 任何AI编码代理读取该文档后即可开始实现，无需额外澄清。