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步：输入收集与完整性检查 接收用户提供的所有材料（文字、文件路径、截图）。 识别四类输入中哪些已提供。 对缺失的可选输入，最多追问一个问题，不要连续追问。 如果已有信息足够生成文档，跳过追问直接进入下一步。 第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编码代理读取该文档后即可开始实现，无需额外澄清。