write-spec

name	write-spec
description	将用户需求与 CLAUDE.md 项目架构上下文结合，生成一份结构化的 Spec 技术规格文档。当用户要求"写 spec"、"生成规格文档"、"需求转技术方案"、"帮我设计实现方案"时触发。
allowed-tools	Read(*), Bash(ls:*, find:*, cat:*, head:*, tail:*), Write(*), Edit(*), Glob(*), Skill(write-project-context)
metadata	{"author":"tangjiahui","version":"1.0.0"}

Write Spec

将用户需求与项目架构（CLAUDE.md）结合，生成结构化的技术规格文档（Spec），输出到 .claude/tmp/spec/。

触发条件

当用户提到以下内容时调用此 skill：

• "写 spec / 生成 spec"
• "生成规格文档 / 技术规格"
• "帮我设计一个方案"
• "需求转技术方案"
• "分析需求，输出实现方案"

前置条件

必须存在 CLAUDE.md

开始执行前，必须检查项目根目录下 CLAUDE.md 是否存在：

test -f ./CLAUDE.md && echo "EXISTS" || echo "NOT_FOUND"

• 如果存在：读取 CLAUDE.md，作为项目架构上下文
• 如果不存在：立即报错并停止

❌ 错误：项目架构信息文件 CLAUDE.md 不存在。

请先执行以下命令生成 CLAUDE.md：
  「请帮我生成 CLAUDE.md」

或手动运行 write-project-context skill 初始化项目上下文。

注意：不应在 write-spec 内自动调用 write-project-context。由用户自行决定是否先生成 CLAUDE.md。

执行流程

1. 收集输入

确认以下信息：

输入	来源	说明
用户需求	用户描述	功能需求、改动目标、问题描述
CLAUDE.md	项目根目录	项目架构上下文（技术栈、目录结构、架构模式）

如果用户需求描述不够清晰，用 1-2 个问题确认核心目标和边界范围。

2. 分析需求

对照 CLAUDE.md 中的架构信息分析：

• 影响范围：需求涉及哪些模块/目录/组件
• 技术可行性：当前技术栈是否支持，是否需要新增依赖
• 复用机会：能否复用已有组件/hooks/utils
• 架构一致性：实现方式是否符合项目既有架构模式

3. 生成 Spec

按以下章节生成 spec 文档，输出到 .claude/tmp/spec/<feature-slug>.md。

Spec 文档结构

# [需求标题]

> 创建时间: YYYY-MM-DD | 状态: draft | 关联: CLAUDE.md

## 一、需求概述

- **目标**：一句话描述要达成什么
- **背景**：为什么需要这个功能/改动（1-2 句）
- **用户故事**：作为 [角色]，我期望 [行为]，以便 [价值]

## 二、功能拆分

将需求拆分为独立的功能点，每个功能点标注：

| 序号 | 功能点 | 优先级 | 说明 |
|------|--------|--------|------|
| 1 | xxx | P0 | ... |
| 2 | xxx | P1 | ... |

优先级定义：
- **P0**：必须实现，否则核心功能不可用
- **P1**：应该实现，提升体验
- **P2**：锦上添花，可后续迭代

## 三、技术方案

### 3.1 整体思路

一段话说明实现的整体思路和核心设计决策。

### 3.2 涉及模块

从 CLAUDE.md 的目录结构中提取相关模块：

| 模块/目录 | 改动类型 | 说明 |
|-----------|----------|------|
| src/engine/xxx | 新增 | ... |
| src/components/xxx | 修改 | ... |
| src/pages/xxx | 修改 | ... |

### 3.3 数据流

描述数据如何流转（如有新增状态/接口）：

[触发] → [处理] → [状态变更] → [视图更新]

### 3.4 关键实现细节

对每个功能点给出实现要点，包括：
- 涉及的关键文件
- 推荐复用的已有函数/组件（注明文件路径）
- 需要注意的边界情况

## 四、文件变更清单

| 文件路径 | 操作 | 说明 |
|----------|------|------|
| src/engine/xxx.ts | 新增 | ... |
| src/components/xxx/index.tsx | 修改 | ... |
| src/**/__tests__/xxx.test.ts | 新增 | 单元测试文件 |

## 五、实现步骤

按依赖关系排序，每步可独立验证：

1. **Step 1: [步骤名]**
   - 做什么：
   - 涉及文件：
   - 验证方式：

2. **Step 2: [步骤名]**
   - ...

> 最后一步必须是**编写单元测试**（参见下方「八、单元测试」）。

## 六、边界与约束

- **边界条件**：空数据、加载态、错误态如何处理
- **兼容性**：是否影响已有功能，是否需要迁移
- **性能考量**：大数据量、高频操作等场景的处理

## 七、验证方案

- **单元测试**：通过 `vitest run` 全部通过
- **手动验证**：关键操作路径和预期结果
- **边界测试**：需要关注的异常场景
- **回归检查**：可能受影响的已有功能

## 八、单元测试

### 8.1 测试范围

列出需要编写单元测试的函数/模块，标注测试类型：

| 模块/函数 | 测试类型 | 说明 |
|-----------|---------|------|
| ... | 纯函数 / 组件 / hook | ... |

### 8.2 测试框架

本项目使用 **Vitest** + **@testing-library/react** 作为测试框架（如项目尚未安装，在 Plan 的「前置准备」中安排安装）。

### 8.3 测试用例设计

对每个被测模块列出关键测试用例，覆盖：
- **正常路径**：核心功能按预期工作
- **边界条件**：空值/极值/异常输入
- **错误处理**：合理的错误情况

示例：

describe('xxx', () => { it('正常路径：...', () => { ... }) it('边界条件：...', () => { ... }) it('错误处理：...', () => { ... }) })

### 8.4 测试配置

测试文件放在 `src/**/__tests__/xxx.test.ts`（与源码同级），useScript 相关测试放 `tests/` 目录。

文件命名规范

Spec 文件以 kebab-case 命名，放在 .claude/tmp/spec/ 下：

.claude/tmp/spec/<feature-slug>.md

示例：

• add-component-rotate.md
• refactor-event-system.md
• fix-drag-resize-boundary.md

注意事项

1. Spec 必须基于 CLAUDE.md 的架构信息，不能凭空设计
2. 涉及文件必须给出实际路径，不要泛指"某组件"
3. 复用优先：优先引用已有模块/hooks/utils，避免重复造轮子
4. 边界情况必须覆盖：空数据、加载中、错误状态、极端数据
5. 步骤可验证：每个实现步骤必须有明确的验证方式
6. 篇幅适中：根据需求复杂度调整，简单改动 80-150 行，复杂功能 150-300 行
7. 不要过度设计：只设计当前需求所需，不做不必要的抽象