القائمة
将用户需求与 CLAUDE.md 项目架构上下文结合，生成一份结构化的 Spec 技术规格文档。当用户要求"写 spec"、"生成规格文档"、"需求转技术方案"、"帮我设计实现方案"时触发。
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
按 Plan 文档逐步执行代码改动，每步自动 lint、git commit 并更新执行状态，支持中断续接和单步回滚。当用户要求"执行 plan"、"按计划实施"、"开始写代码"时触发。
全自动需求→实现流水线编排。串联 write-spec → refine-spec → write-plan → execute-plan → 验收，每阶段设置确认门，支持中断恢复。当用户要求"全自动实现"、"一键开发"、"按需求交付"时触发。
循环向用户提问，持续收集补充意见来打磨 Spec 文档，直到用户明确确认全部 OK 才停止并输出完整结果。当用户要求"完善 spec"、"补充需求"、"评审 spec"、"继续细化"时触发。
从 Spec 技术规格文档生成分步实施计划（Plan），包含执行记忆存储和 git commit 策略。当用户要求"写 plan"、"生成实施计划"、"spec 转 plan"、"帮我拆分实现步骤"时触发。
分析项目代码结构，生成一份 CLAUDE.md 项目架构文档，包含技术栈、目录结构、入口文件、架构模式和配置说明。当用户要求"生成 CLAUDE.md"、"写项目文档"、"分析项目架构"、"初始化项目上下文"时触发。
| 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"} |
将用户需求与项目架构（CLAUDE.md）结合，生成结构化的技术规格文档（Spec），输出到 .claude/tmp/spec/。
当用户提到以下内容时调用此 skill：
开始执行前，必须检查项目根目录下 CLAUDE.md 是否存在：
test -f ./CLAUDE.md && echo "EXISTS" || echo "NOT_FOUND"
❌ 错误：项目架构信息文件 CLAUDE.md 不存在。
请先执行以下命令生成 CLAUDE.md：
「请帮我生成 CLAUDE.md」
或手动运行 write-project-context skill 初始化项目上下文。
注意：不应在 write-spec 内自动调用 write-project-context。由用户自行决定是否先生成 CLAUDE.md。
确认以下信息：
| 输入 | 来源 | 说明 |
|---|---|---|
| 用户需求 | 用户描述 | 功能需求、改动目标、问题描述 |
| CLAUDE.md | 项目根目录 | 项目架构上下文（技术栈、目录结构、架构模式） |
如果用户需求描述不够清晰，用 1-2 个问题确认核心目标和边界范围。
对照 CLAUDE.md 中的架构信息分析：
按以下章节生成 spec 文档，输出到 .claude/tmp/spec/<feature-slug>.md。
# [需求标题]
> 创建时间: 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.mdrefactor-event-system.mdfix-drag-resize-boundary.md