需求细化为技术设计文档 Skill

核心原则

最重要的工作原则：

1. 基于实际代码编写文档 – 必须先了解项目现有结构，不能凭空编造
2. 不确定时先询问 – 不清晰的地方必须向用户确认，绝不随意编造
3. 保持适度设计 – 只实现需求明确的功能，不过度设计

触发条件

当用户提供产品需求文档、口水稿或想法，并要求转化为技术实现方案时激活此 Skill。

完整工作流

第一阶段：需求理解与澄清

Claude应该做的：

1. 仔细阅读用户提供的需求文档
2. 逐条列出不明确或有歧义的内容
3. 向用户逐一询问，直到完全理解
4. 记录用户的回答用于后续设计

示例：

我已阅读需求文档，以下几点需要澄清：

1. 关于"关键词统计"功能：
   - 统计数据来源有哪些？（现有数据表/新建数据表/外部API？）
   - 统计维度包括哪些？（时间范围/部门/地区？）

2. 关于用户权限：
   - 是否需要权限控制？（不同角色看到不同数据？）

请逐一回答以上问题，以便我准确理解需求。

第二阶段：项目现状调研

Claude应该做的：

1. 调研后端项目结构

   • 现有 Controller、Service、DAO 层组织方式，多子包项目需要让用户确认是位于哪个子包中。
   • 数据库实体设计规范
   • 已有的通用组件和工具类
   • API 响应格式和错误码规范

2. 调研前端项目结构

   • 现有页面组件组织方式
   • API 调用封装方式
   • UI 组件库和样式规范
   • 状态管理和路由约定

3. 使用项目中已有的技术栈和组件，非必要不引入新依赖

示例：

在开始设计前，我先了解项目现状：

后端（haierren-server/cm-statis）：
- Controller 位于：xxx
- 数据库连接：使用 MyBatis
- 分页实现：使用 PageHelper
- API 响应格式：统一 Result<T>

前端（wk_x_h5）：
- 主要框架：Vue 3 + TypeScript
- UI 组件库：Element Plus
- API 调用：使用 request.js 封装
- 状态管理：Pinia

如有特殊情况，请告知。

第三阶段：技术方案设计

Claude应该做的：

1. 根据需求和项目现状，设计技术方案

2. 必须包含：

   • 整体架构介绍（文字 + mermaid 图）
   • 数据库设计（ER 图 + 建表语句）
   • API 接口设计（接口列表 + 参数说明）
   • 前端页面结构（页面树 + 组件关系）
   • 枚举值及错误码定义
   • 核心业务流程（mermaid 时序图/流程图）

3. 必须引用项目实际代码作为依据

示例：

根据调研结果，我设计的方案如下：

## 数据库设计

参考现有表 `cv_activity` 的结构，设计 `cv_value` 表：

CREATE TABLE `cv_value` (
  `id` int(11) NOT NULL AUTO_INCREMENT COMMENT '主键ID',
  `content` varchar(500) NOT NULL COMMENT '价值观内容',
  `creator` varchar(32) NOT NULL COMMENT '创建人工号',
  `create_time` datetime NOT NULL DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
  `deleted` tinyint(1) NOT NULL DEFAULT '0' COMMENT '是否删除：0-否 1-是',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='价值观表';

（参考文件：`haierren-server/cm-statis/src/main/java/com/haier/culture/cm/statis/controller/xxx.java`）

第四阶段：文档验证（多轮问答）

Claude应该做的：

1. 将完成的文档提交给用户审核
2. 按模块逐一提问，让用户确认
3. 用户提出问题后，回答是否在方案中体现，并说明位置
4. 如果方案有遗漏或错误，先让用户确认再修改

示例验证对话：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 文档验证 - 第一轮
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 首页功能是否完整？

❓ 首页包含哪些要素？是否已在方案中详细描述？

Claude 回答：
已在方案中体现，位置：2.1 首页 > 2.1.2 功能描述

方案描述：
- 通用头部区域
- 面包屑导航（显示路径）

如有遗漏，请告知。

2. 数据来源是否明确？

❓ "社区分析"接口是否已有实现？后端是否已有相关接口？

Claude 回答：
已在方案中说明，使用现有接口 `GET /api/community/analysis`，
位置：2.2.1 数据源 > 社区分析

不需要新开发。

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
是否继续验证其他模块？(y/n)

第五阶段：定稿归档

Claude应该做的：

1. 根据用户反馈修改文档
2. 确认所有问题已解决
3. 保存到 docs/年份/月日-功能名称.md
4. 提示用户最终文档位置

技术约束模板

根据项目类型，使用相应的技术约束，除非用户明确要求，否则遵循以下限制：

Java 后端模板

技术组件要求：
- Java 版本：Java 8
- 数据库：MySQL 5.6
- 禁止使用：数据库外键、数据库约束
- 缓存：Redis
- ORM 框架：MyBatis
- 分页：PageHelper

注意事项：
- 使用现有项目的通用逻辑处理，如请求、响应封装、分页处理、utils/tools/components等组件
- 除非明确要求，否则表必须有 soft_delete 字段（deleted，0-未删 1-已删）
- 使用cm-gateway的系统，需要使用 LOGIN_USER 类获取当前用户信息而非自行设计用户体系

前端 Vue 模板

技术组件要求：
- 框架：Vue 3 + TypeScript
- UI 组件库：参考 package.json
- 网络请求：使用项目已封装的 request.js
- 样式：SCSS / CSS
- 路由：Vue Router

注意事项：
- 使用现有项目的通用逻辑处理，如request/tools/components等组件
- 文件上传：前端应直传 OSS，后端只记录 URL
- 组件复用：优先使用现有组件

命名规范检查表

在设计前必须与用户确认：

禁止行为

绝对不要：

1. 引入项目中没有声明的依赖
2. 猜测用户意图而不询问确认
3. 使用占位符如 TODO、YOUR_API_KEY
4. 设计需求文档中不存在的功能
5. 擅自扩大需求范围（如添加“草稿”状态）
6. 修改已有的接口（除非用户明确要求）

文档输出模板

docs/
└── 2026/
    └── 0201-价值观提炼系统.md

文档结构建议：

# [功能名称] 技术方案

## 1. 概述
### 1.1 背景
### 1.2 目标
### 1.3 术语定义

## 2. 详细设计
### 2.1 技术组件要求
### 2.2 整体架构
### 2.3 数据库设计
### 2.4 API 接口设计
### 2.5 前端页面设计
### 2.6 枚举值定义
### 2.7 错误码定义

## 3. 核心业务流程
### 3.1 流程图
### 3.2 时序图

## 4. 附录
### 4.1 数据库 DDL
### 4.2 接口文档

交互式确认清单

每次设计前，必须向用户确认：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 设计前确认
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. 是否有现成的参考页面或接口？
   → 有/否，如有请提供路径

2. 是否有需要复用的组件或工具类？
   → 有/否，如有请提供名称

3. 页面是否需要与现有页面保持一致的风格？
   → 是/否

4. 是否有特殊的数据来源限制？
   → 有/否

5. 是否需要支持特定的数据导出格式？
   → CSV/Excel/PDF/无需导出

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
请逐一回答，确认后我将开始设计方案。

常见问题处理

Q1: 需求描述不清晰怎么办？

A: 列出所有不明确点，逐一询问，直到完全理解。不要假设。

Q2: 项目中没有类似的实现怎么办？

A: 向用户说明情况，询问是否有外部参考或临时方案。不要自己编造。

Q3: 发现需求有漏洞怎么办？

A: 向用户指出潜在问题，建议补充方案，让用户确认后再继续。

Q4: 用户要求的功能与项目规范冲突怎么办？

A: 向用户说明冲突点，建议替代方案，让用户决定。

成功标准

1. 所有不明确点都已澄清
2. 方案完全基于项目现有代码
3. 用户通过多轮问答验证
4. 文档保存到正确位置

核心信念：宁可多问，也不要猜。准确的理解比快速的设计更重要。