yy-mode-spec

规格优先开发模式，要求在实施前完成详细文档编写。

触发条件

用户在聊天中输入 /yy-mode-spec 命令。

核心规则

1. 规格优先

在用户明确确认执行之前：

• 禁止进行任何编辑（规格文件除外）
• 禁止运行任何非只读工具
• 禁止对系统进行任何更改
• 禁止以"任务简单"或"意图明显"为由跳过展示规格、等待确认的步骤

2. 规格文件

简单需求可跳过文件创建，直接在对话界面输出内容供用户确认，仍需等待用户明确确认后才可开始执行。

复杂需求需创建三个规格说明文件：

1. spec.md - 主规格文档

   • 功能概述
   • 需求（功能性与非功能性）
   • 技术设计
   • API 规格
   • 数据模型

2. tasks.md - 任务分解

   • 有序的实施任务列表
   • 任务间依赖关系
   • 预估复杂度
   • 验收标准

3. checklist.md - 验证清单

   • 实施前检查项
   • 实施中检查点
   • 实施后验证
   • 质量门禁

3. 用户确认

1. 完成全部规格文档
2. 使用 NotifyUser 通知用户审核
3. 等待用户明确确认执行

4. 规格确认后

• 仅在用户明确确认后开始开发
• 仅在所有规格完成并验证后终止

5. 规格被拒绝时

• 继续编辑和优化规格说明
• 回应用户反馈
• 再次通知用户等待批准

规格文件位置

规格文件将按照以下规则创建：

目录选择优先级

1. 用户手动指定（最高优先级）

   • 用户可指定工具目录和需求目录
   • 格式：--tool-dir <目录> --requirement-dir <目录>

2. 自动检测

   • 按以下优先级顺序检查项目根目录：
     • .agents
     • .claude
     • .opencode
     • .trae
   • 找到第一个存在的目录即停止检测

3. 无匹配目录

   • 提示用户指定目录或创建

目录结构

{项目根目录}/
└── {工具目录}/          # 如 .claude
    └── specs/            # 固定的 specs 目录
        └── {时间戳}_{需求目录}/   # 时间戳格式：YYYYMMDD_HHMMSS；需求目录基于用户输入生成，如 "20260324_153045_实时通知系统"
            ├── spec.md
            ├── tasks.md
            └── checklist.md

时间戳前缀（精确到秒）确保目录按创建时间升序排列，最新规格始终位于目录末尾，便于查找。

路径示例

• 自动检测：.claude/specs/20260324_153045_实时通知系统/spec.md
• 用户指定：.agents/specs/20260324_153045_用户管理/spec.md

使用示例

示例 1：自动检测目录

用户: /yy-mode-spec
用户: 创建实时通知系统

AI:
1. 检测项目根目录下的工具目录（.agents > .claude > .opencode > .trae）
2. 假设检测到 .claude 目录
3. 在 .claude/specs/20260324_153045_实时通知系统/ 创建规格文件
4. 创建 spec.md 包含需求和设计
5. 创建 tasks.md 包含实施分解
6. 创建 checklist.md 包含验证步骤
7. 通知用户审核
8. **确认执行后**，按规格实施

示例 2：手动指定目录

用户: /yy-mode-spec --tool-dir .agents --requirement-dir 用户管理
用户: 创建用户认证系统

AI:
1. 使用用户指定的工具目录 .agents
2. 在 .agents/specs/20260324_153045_用户管理/ 创建规格文件
3. 创建 spec.md 包含需求和设计
4. 创建 tasks.md 包含实施分解
5. 创建 checklist.md 包含验证步骤
6. 通知用户审核
7. **确认执行后**，按规格实施

Output contract

必需文件结构

此模式要求创建以下三个规格文件：

1. spec.md - 主规格文档

# [功能名称] 规格说明书

## 1. 功能概述
[简要描述此功能的核心价值]

## 2. 需求分析

### 2.1 功能性需求
| 需求ID | 描述 | 优先级 | 验收条件 |
|--------|------|--------|----------|
| FR-01 | 用户登录功能 | P0 | 能正确验证用户名密码 |
| FR-02 | Token 刷新 | P1 | 过期前自动刷新 |

### 2.2 非功能性需求
| 需求ID | 描述 | 指标 |
|--------|------|------|
| NFR-01 | 性能 | 响应时间 < 200ms |
| NFR-02 | 安全 | 密码加密存储 |

## 3. 技术设计

### 3.1 架构设计
[架构图或文字描述]

### 3.2 API 规格
| 方法 | 路径 | 请求 | 响应 |
|------|------|------|------|
| POST | /api/auth/login | {username, password} | {token, expiresIn} |

### 3.3 数据模型
```typescript
interface User {
  id: string;
  username: string;
  passwordHash: string;
  createdAt: Date;
}

4. 外部依赖

• [依赖项列表]

2. tasks.md - 任务分解

# [功能名称] 任务分解

## 任务列表

### 阶段一：基础设施
| 任务ID | 描述 | 依赖 | 预估复杂度 | 验收标准 |
|--------|------|------|------------|----------|
| T-01 | 安装 jsonwebtoken | - | 低 | package.json 包含依赖 |
| T-02 | 创建 JWT 工具类 | T-01 | 中 | 单元测试通过 |

### 阶段二：核心功能
| 任务ID | 描述 | 依赖 | 预估复杂度 | 验收标准 |
|--------|------|------|------------|----------|
| T-03 | 实现登录接口 | T-02 | 中 | 返回有效 Token |
| T-04 | 实现验证中间件 | T-02 | 高 | 正确拦截未授权请求 |

## 任务依赖图
[依赖关系图或说明]

3. checklist.md - 验证清单

# [功能名称] 验证清单

## 实施前检查
- [ ] 代码评审通过
- [ ] 测试用例编写完成
- [ ] 开发环境就绪

## 实施中检查
- [ ] 每个任务完成后更新任务状态
- [ ] 遇到阻塞及时升级

## 实施后验证
- [ ] 所有任务完成
- [ ] 单元测试覆盖率 > 70%
- [ ] API 文档已更新
- [ ] 集成测试通过

## 质量门禁
- [ ] lint 检查通过
- [ ] TypeScript 编译无错误
- [ ] 安全扫描通过

路径格式规范

• 使用正斜杠作为路径分隔符，路径包含空格时使用引号包裹，以确保跨平台兼容性和正确解析

输出示例

## 规格已制定完成

已创建以下规格文件：
1. .claude/specs/20260324_153045_实时通知系统/spec.md - 主规格文档
2. .claude/specs/20260324_153045_实时通知系统/tasks.md - 任务分解（4个任务）
3. .claude/specs/20260324_153045_实时通知系统/checklist.md - 验证清单

请审核规格文档，确认是否执行。