메뉴
将用户需求与 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