req-to-ai-spec

name	req-to-ai-spec
description	将零散的产品需求（文字描述、原型截图、现有代码库）转换为结构化的、AI友好的需求规格文档。 任何AI编码代理读取输出文档后即可高效完成开发实现。 触发关键词：req-to-ai-spec、需求转换、需求分析、需求文档生成、需求转AI规格、AI spec

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步：输入收集与完整性检查

1. 接收用户提供的所有材料（文字、文件路径、截图）。
2. 识别四类输入中哪些已提供。
3. 对缺失的可选输入，最多追问一个问题，不要连续追问。
4. 如果已有信息足够生成文档，跳过追问直接进入下一步。

第2步：项目适配检测

1. 检查当前环境可用的skill列表，寻找项目专用的概览skill。
2. 匹配*-overview命名模式（如ados-overview、myproject-overview）。
3. 如果找到：调用Skill工具加载，获取项目领域知识（模块划分、术语体系、核心数据表），提升后续代码探索和约束发现的精准度。
4. 如果没找到：跳过，仅依赖代码探索。
5. 绝不在本skill中硬编码任何项目专属知识。 所有领域上下文必须来自动态加载的overview skill或代码探索。

第3步：代码探索（自主执行，内部消化）

本步骤静默执行。发现的信息用于辅助分析，不会原文引用到输出文档中。

1. 根据需求关键词，用Grep和Glob工具搜索代码库中的相关Controller、Service、Repository、Model、配置文件。
2. 沿调用链追踪最多3层（如Controller → Service → Mapper/Repository）。
3. 目标：
   • 理解现有模式（命名规范、分层架构、响应包装）
   • 发现数据结构（表结构、实体字段、枚举值）
   • 找到类似功能，推断新功能应遵循的模式
   • 识别需求文字中未提及的边界情况 → 这些将成为输出中的[推断]项
4. 如果代码库为空、不可访问或无关 → 跳过，仅基于文字和截图工作。
5. 收集到足够上下文后停止，不要过度探索。

第4步：需求分析与结构化

1. 融合所有输入：文字描述 + 截图观察 + 代码理解 → 统一认知。
2. 决定Task粒度：
   • 整个需求能用一个Task表达？→ 保持一个。
   • 有多个独立交付物？→ 拆分为多个Task。
   • 单个Task的核心规则超过8条？→ 考虑继续拆分。
3. 识别隐含规则：用户没提但代码库暗示的东西（如软删除模式、审计日志、权限检查）。
4. 识别跨Task依赖：标注哪些Task依赖其他Task。
5. 决定可选章节：根据输出模板的条件包含规则，判断是否需要术语表、全局约束、实现顺序。

第5步：输出文档生成

1. 读取references/output-template.md（与本SKILL.md同目录）获取标准文档结构和逐字段写作指引。
2. 严格按模板生成规格文档，包括：
   • YAML元数据（生成日期、源材料、工作区路径、skill版本）
   • 所有适用章节（概述、术语表、全局约束、实现顺序、Task）
   • 不适用的可选章节完全省略（不要留空章节）
3. 通过代码探索发现的边界情况标记[推断]，提示用户确认。
4. 输出前执行模板中的质量检查清单。
5. 将文档写入指定输出路径。

第6步：用户确认

1. 向用户展示生成的文档（或确认写入的文件路径）。
2. 问："请review这份需求文档，有需要调整的地方告诉我"
3. 根据用户反馈修改，重复直到用户满意。
4. 不要自动进入编码、计划或任何下一步。 规格文档是本skill的最终交付物。

行为规则

文档生成规则

1. 输出语言跟随用户语言。 用户用中文描述需求则全文中文输出，用英文则英文输出。包括所有章节标题、规则、验收标准、术语表。
2. 规则必须无歧义。 每条核心规则只表达一个逻辑分支。禁止使用"大概"、"可能"、"一般来说"、"酌情"、"适当处理"等模糊词。
3. 主动补全边界情况。 从代码探索中推断的边界条件标记[推断]，供用户确认。
4. 不发明需求。 只能结构化和补全用户已表达的意图或代码库暗示的内容，推测必须标记。
5. 截图提取业务规则，不描述UI实现。 提取"允许用户执行X操作"，而非"增加一个标记为X的按钮"。

Task拆分规则

1. 每个Task必须可独立实现和测试。
2. 单个Task的核心规则超过8条时考虑拆分。
3. Task之间的依赖必须在"依赖"字段中明确标注。
4. 多个Task存在先后顺序时，必须包含"实现顺序"章节并说明理由。

交互规则

1. 一次只问一个问题，不要列出问题清单。
2. 信息足够时不强制追问，直接生成文档。
3. 生成文档后必须请用户review。
4. 不要自动进入实现、任务创建或任何后续动作。

项目适配机制

本skill通过检测机制动态适配任何项目：

1. 检测：激活时扫描环境中可用的skill，匹配*-overview命名模式。
2. 加载：找到后通过Skill工具调用，注入项目领域知识（模块边界、命名规范、核心数据表、公共工具）。
3. 收益：更精准的代码探索、正确使用领域术语、更好地发现项目特有的约束和模式。
4. 降级：无overview skill时，正常走代码探索和用户提供的上下文。

本skill零项目硬编码知识，所有适配均为动态。

限制（v1）

• 不支持增量更新。 每次调用从头生成，修改已有规格需重新走完整流程。
• 仅Markdown输出。 不支持PDF、Confluence等格式。
• 截图提取为尽力而为。 质量取决于图片分辨率和视觉模型能力。
• 代码探索深度有限。 最多追踪3层调用链，深层嵌套逻辑可能无法完全捕获。

输出

• 成功：一份自包含的Markdown规格文档，写入指定输出路径（默认docs/YYYY-MM-DD-<slug>-spec.md）。
• 文档遵循references/output-template.md中定义的结构和质量标准。
• 任何AI编码代理读取该文档后即可开始实现，无需额外澄清。