# Yy Mode Spec

> 规格优先开发模式。当用户输入 /yy-mode-spec 命令或需要在编码前制定详细规格说明时调用。 不用于仅给出粗粒度执行计划、直接实施代码变更，也不用于已有功能的代码审核或修复。

- Skill: `bulls-cows/yy-mode-spec` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add bulls-cows/yy-mode-spec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/bulls-cows/yy-mode-spec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: bulls-cows (https://skillmd.com/u/bulls-cows)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/bulls-cows/yy-mode-spec

---


# yy-mode-spec

## 描述

规格优先开发模式，要求在实施前完成详细规格文档编写，确保需求、设计、任务分解和验证标准全部明确后再开始编码。

## 使用场景

- 用户输入 `/yy-mode-spec` 命令
- 用户需要在编码前制定详细规格说明
- 用户要求先写规格文档再开发

不应触发：

- 用户直接要求执行某个任务，未提及规格文档
- 用户只是询问项目信息

## 指令

### 步骤 0. 检查续接状态

检测当前对话上下文中是否存在已有的规格进度：

- **用户提供了规格目录路径**：读取该目录下的 handoff.md（如有），展示续接状态并询问是否继续
- **用户未提供路径**：扫描项目 specs/ 目录（如 `{工具目录}/specs/`）查找最新的 handoff.md，如有则展示续接状态并询问是否继续
- **无 handoff.md 或用户选择重新开始**：进入步骤 1

### 步骤 1. 理解需求

分析用户需求，判断需求清晰度：

- **需求明确**：直接进入步骤 3
- **需求不明确**：进入步骤 2 澄清

### 步骤 2. 澄清需求

当需求存在歧义、缺失关键信息或多种理解时，向用户提问：

- 列出理解上的歧义点，而非默默选择其中一种
- 提出具体问题，而非笼统问"还有什么要求"
- 每次提问控制在 1-3 个核心问题，避免信息过载

**循环条件**：用户回答后重新评估需求清晰度，仍不明确则继续提问，直到需求足够清晰可编写规格。

### 步骤 3. 评估复杂度与方案确定性

评估需求复杂度与方案确定性，判断是否跳过展示方案方向步骤：

- **需求复杂度低且方案很确定**：跳过"展示方案方向"，直接进入编写规格内容（步骤 5）
- **需求不明确或方案待决策**：进入"展示方案方向"（步骤 4）

评估标准：

- **低复杂度**：单文件修改或少量文件变更，功能单一，逻辑清晰，不涉及架构变更
- **方案确定**：实现方式没有歧义，无需用户做技术选型决策

### 步骤 4. 展示方案方向

仅在需求不明确或方案待决策时执行。在细化规格前，先向用户展示方案的方向和方法：

- 目标：一句话说明将要完成的内容
- 方法：高层策略（1-3 句）
- 涉及范围：将要修改的文件或模块
- 待确认点：仍需用户决策的关键选择（如有）

等待用户确认方向正确后再细化。如果用户调整方向，回到步骤 1 重新理解。

### 步骤 5. 编写规格内容

根据需求编写规格文档，包含以下要素：

- **功能概述**：核心价值和目标
- **需求分析**：功能性需求和非功能性需求
- **技术设计**：架构设计、API 规格、数据模型
- **核心代码示例**：关键函数签名、数据结构定义、核心逻辑片段，让使用者直观看到预期变更
- **任务分解**：有序的实施任务列表、依赖关系、验收标准
- **验证清单**：实施前、实施中、实施后的检查项

### 步骤 6. 确定输出方式

**简单需求**：直接在对话中展示规格内容。

**复杂需求**：创建规格文件，执行以下步骤：

1. 确定工具目录：按 `.agents` > `.claude` > `.opencode` > `.trae` 顺序检测，或使用用户指定的 `--tool-dir` 参数
2. 创建规格目录：`{工具目录}/specs/{时间戳}_{需求目录}/`
3. 生成四个文件，以 `spec.md` 为核心入口：
   - **spec.md**：核心入口文件，包含文件关系说明，链接到 tasks.md、checklist.md 和 handoff.md
   - **tasks.md**：任务分解，按依赖顺序排列的实施任务
   - **checklist.md**：验证清单，实施前后的质量检查项
   - **handoff.md**：交接文档，记录当前进度，用于中断后恢复
4. 在规格目录中执行 yy-handoff 技能生成 handoff.md（已有则删除后重建）

- **时间戳**：`YYYYMMDD_HHMMSS` 格式（如 `20260324_153045`），必须通过执行 shell 命令或脚本语言获取系统时间生成，禁止手动编写
- **需求目录名**：使用简短中文，能表达需求核心含义即可，如 `实时通知系统`、`用户权限重构`、`数据导出模块`

**完整示例**：

```text
specs/20260324_153045_实时通知系统/
specs/20260324_153045_用户权限重构/
specs/20260324_153045_数据导出模块/
```

### 步骤 7. 展示规格并等待确认

向用户展示规格内容，等待确认。

### 步骤 8. 处理用户反馈

- **用户确认**：
  1. 在规格目录中删除旧 handoff.md，重新执行 yy-handoff 技能生成 handoff.md，记录"规格已确认，即将开始实施"的状态
  2. 开始执行实施
- **用户拒绝**：根据反馈调整规格，重新展示
- **用户要求调整**：修改对应部分，重新展示

### 步骤 9. 执行实施

用户确认后执行：

1. 创建待办事项列表
2. 按任务分解顺序执行，每完成一个阶段或独立任务，在规格目录中删除旧 handoff.md 并重新执行 yy-handoff 技能生成 handoff.md，记录当前已完成任务和待完成任务
3. 完成后运行验证清单

### 步骤 10. 输出结果

#### 方案方向（步骤 4）

```markdown
## 方案方向

**目标**：[一句话描述]
**方法**：[高层策略]
**涉及范围**：[文件或模块列表]

**待确认点**：（如有）

- [需要用户决策的问题]

---

请确认方向是否正确，或提出调整意见。
```

#### 规格结果（步骤 7）

```markdown
## 规格已创建

**规格目录**：[规格文件路径]

### 规格摘要

[功能概述和关键需求]

### 任务概览

[任务数量和阶段划分]

---

请确认是否执行此规格。
```

## 安全边界

- 规格确认前只允许创建规格文件，不得修改项目代码或其他文件
- 不跳过用户确认步骤直接执行实施
- 不执行与规格无关的操作

## 相关资源

本技能包含以下辅助资源：

- `examples/input.md`：输入示例，展示用户如何请求制定规格
- `examples/output.md`：输出示例，展示规格文件的预期格式
- `templates/spec-template.md`：规格文档模板
- `templates/tasks-template.md`：任务分解模板
- `templates/checklist-template.md`：验证清单模板