# Req To AI Spec

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

- Skill: `garveyhu/req-to-ai-spec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add garveyhu/req-to-ai-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/garveyhu/req-to-ai-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: garveyhu (https://skillmd.com/u/garveyhu)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/garveyhu/req-to-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编码代理读取该文档后即可开始实现，无需额外澄清。