datai/docs/skill/phase5-prompt-engineering.md

# 阶段 5：提示词生成技能书

## A. 元数据 (Metadata)

**name**: `phase5-prompt-engineering`

**description**: 在 Datai 项目中，基于已创建的需求文档和设计文档，生成针对当前需求的提示词，引用真源，定义输出格式，并更新索引和会话记录。此技能确保 AI 生成的代码符合项目规范和需求。

---

## B. 触发与定位 (Triggers & Scope)

### 触发关键词
当用户输入包含以下关键词时，必须觉醒此技能：
- "提示词"、"Prompt"、"提示词生成"
- "工程化提示词"、"执行提示词"
- "进入阶段 5"、"下一阶段"
- "Prompt 设计"、"提示词设计"

### 触发场景
- 用户确认阶段 4 完成，要求进入阶段 5
- 用户要求生成提示词
- 用户询问如何设计提示词
- 用户提到"按照项目规则"或"SSOT 流程"进行提示词设计

### 操作路径
此技能涉及以下文件和目录的操作：
- **读取**: `docs/requirements/YYYY-MM-DD-00X-需求名.md` (阶段 1 创建的需求文档)
- **读取**: `docs/design/YYYY-MM-DD-00X-设计名.md` (阶段 2 创建的设计文档)
- **创建**: `docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md`
- **更新**: `docs/index.md`
- **更新**: `docs/requirements/YYYY-MM-DD-00X-需求名.md` (添加提示词引用)
- **更新**: `docs/sessions/YYYY-MM-DD-00X-session.md`
- **读取**: `.trae/rules/project_rules.md` (项目规则)
- **读取**: `docs/Prompt/0004-单一真源文档驱动架构师.md` (SSOT 架构师提示词)
- **读取**: `docs/Prompt/0000-template.md` (提示词模板)

### SSOT 依赖
必须参考以下"唯一真源"：
- [需求文档](file:///d:\idea_demo\datai\docs\requirements\YYYY-MM-DD-00X-需求名.md) - 阶段 1 创建的需求文档
- [设计文档](file:///d:\idea_demo\datai\docs\design\YYYY-MM-DD-00X-设计名.md) - 阶段 2 创建的设计文档
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) - 项目规则和阶段定义
- [0004-单一真源文档驱动架构师.md](file:///d:\idea_demo\datai\docs\Prompt\0004-单一真源文档驱动架构师.md) - SSOT 架构师提示词
- [0000-template.md](file:///d:\idea_demo\datai\docs\Prompt\0000-template.md) - 提示词模板

---

## C. 核心指令集 (Instructions)

### 架构约束

#### 1. 提示词命名规范（强制）
- 必须使用格式：`YYYY-MM-DD-00X-prompt-提示词名.md`
- `YYYY-MM-DD`：当前日期（如 2026-01-21）
- `00X`：需求编号（与阶段 1-4 保持一致）
- `提示词名`：简洁描述，使用中文，如"用户登录功能"
- **严禁**使用英文、拼音或无意义的文件名

#### 2. 提示词内容约束（强制）
提示词必须包含以下内容：
- 引用真源（需求文档和设计文档的链接）
- 需求描述
- 设计方案
- 输出格式要求
- 代码规范要求
- 测试要求

#### 3. 引用真源约束（强制）
- 提示词开头必须引用 `docs/requirements/` 和 `docs/design/` 的文件链接
- 引用格式：`[需求文档](../requirements/YYYY-MM-DD-00X-需求名.md)`
- 引用格式：`[设计文档](../design/YYYY-MM-DD-00X-设计名.md)`

#### 4. 输出格式约束（强制）
- 必须定义输出格式，如：必须包含单元测试，必须符合某设计模式
- 必须定义代码结构，如：Controller、Service、Mapper、Entity 分层
- 必须定义命名规范，如：类名、方法名、变量名的命名规则
- 必须定义注释规范，如：类注释、方法注释、字段注释

#### 5. 索引更新约束（强制）
- 必须在生成提示词后立即更新 `docs/index.md`
- 必须更新需求文档，添加提示词引用
- 采用增量更新策略，**严禁**删除现有内容
- 索引链接格式：`[文档名](./相对路径/文件名.md)`
- 必须在 `docs/index.md` 中添加到"提示词"部分

#### 6. 会话记录约束（强制）
- 必须更新 `docs/sessions/YYYY-MM-DD-00X-session.md`
- 必须更新当前阶段为"阶段 5：提示词生成"
- 必须记录提示词内容摘要
- 必须记录提示词链接

### 业务逻辑 SOP（标准操作流程）

#### 步骤 1：提示词分析（Let's think step by step）
在生成提示词前，必须执行以下分析：

1. **分析需求的核心任务**
   - 读取阶段 1 创建的需求文档
   - 识别需求的核心功能和非功能需求
   - 确定需要生成的代码类型（Controller、Service、Mapper、Entity 等）

2. **确定需要生成的提示词类型**
   - 根据需求类型确定提示词类型：
     - 功能开发提示词
     - Bug 修复提示词
     - 性能优化提示词
     - 重构提示词
   - 根据技术栈确定提示词类型：
     - Spring Boot 提示词
     - MyBatis Plus 提示词
     - 若依框架提示词
     - Salesforce API 提示词

3. **设计提示词的结构和内容**
   - 引用真源（需求文档和设计文档）
   - 需求描述
   - 设计方案
   - 输出格式要求
   - 代码规范要求
   - 测试要求

#### 步骤 2：生成提示词
1. **确定文档路径**
   - 路径：`docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md`
   - 使用 Write 工具创建文件
   - 确保目录存在（使用 LS 工具检查）

2. **填充提示词内容**
   - **引用真源**：
     ```markdown
     # 提示词：用户登录功能
     
     ## 引用真源
     - [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
     - [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)
     ```
   - **需求描述**：
     ```markdown
     ## 需求描述
     根据需求文档，实现用户登录功能，包括：
     1. 用户名和密码验证
     2. 记住密码功能
     3. 自动登录功能
     4. 登录失败提示
     5. 登录成功后跳转到首页
     ```
   - **设计方案**：
     ```markdown
     ## 设计方案
     根据设计文档，采用以下技术方案：
     1. 认证框架：Spring Security 6.x
     2. Token 生成：JWT
     3. 密码加密：BCrypt
     4. 会话管理：Redis 存储 Token
     5. 权限框架：若依权限系统
     ```
   - **输出格式要求**：
     ```markdown
     ## 输出格式要求
     1. 必须包含以下文件：
        - Controller：`SysLoginController.java`
        - Service：`SysLoginService.java`
        - Mapper：`SysUserMapper.java`
        - Entity：`SysUser.java`
        - 配置类：`SecurityConfig.java`
     2. 必须包含单元测试：
        - `SysLoginServiceTest.java`
     3. 必须符合 Spring Boot 最佳实践
     4. 必须遵循若依框架规范
     ```
   - **代码规范要求**：
     ```markdown
     ## 代码规范要求
     1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
     2. 方法命名：首字母小写，驼峰命名，如 `login`
     3. 变量命名：首字母小写，驼峰命名，如 `userName`
     4. 注释规范：
        - 类注释：使用 `/** */`，包含类功能描述
        - 方法注释：使用 `/** */`，包含方法功能、参数、返回值描述
        - 字段注释：使用 `/** */`，包含字段功能描述
     ```
   - **测试要求**：
     ```markdown
     ## 测试要求
     1. 单元测试覆盖率不低于 80%
     2. 测试用例包含正常场景和异常场景
     3. 使用 JUnit 5 和 Mockito 进行测试
     4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`
     ```

3. **提示词质量检查**
   - 使用 Read 工具读取刚创建的提示词
   - 检查是否符合提示词内容约束
   - 检查是否引用了真源
   - 检查输出格式要求是否明确
   - 检查代码规范要求是否明确
   - 检查测试要求是否明确

#### 步骤 3：更新索引和需求文档
1. **读取现有索引**
   - 使用 Read 工具读取 `docs/index.md`
   - 找到"提示词"部分
   - 如果不存在，则创建该部分

2. **添加新提示词链接**
   - 在"提示词"部分追加新提示词
   - 格式：`- [提示词名](./prompts/YYYY-MM-DD-00X-prompt-提示词名.md) - [描述]`
   - 示例：`- [用户登录功能提示词](./prompts/2026-01-21-001-prompt-用户登录功能.md) - 用户登录功能的执行提示词`

3. **更新需求文档**
   - 使用 Read 工具读取需求文档
   - 在"相关文档"部分添加提示词引用
   - 格式：`- [提示词文档](../prompts/YYYY-MM-DD-00X-prompt-提示词名.md)`
   - 使用 Write 工具更新需求文档

4. **保存索引**
   - 使用 Write 工具更新 `docs/index.md`
   - **严禁**删除现有内容，只追加新内容

#### 步骤 4：更新会话记录
1. **读取现有会话记录**
   - 使用 Read 工具读取 `docs/sessions/YYYY-MM-DD-00X-session.md`

2. **更新阶段 5 信息**
   - 更新"当前阶段"为"阶段 5：提示词生成"
   - 更新"阶段 5：提示词生成"的状态为"已完成"
   - 添加生成的提示词链接
   - 记录提示词内容摘要

3. **保存会话记录**
   - 使用 Write 工具更新会话记录

#### 步骤 5：确认与询问
1. **向用户确认**
   - 显示提示词的链接
   - 询问："提示词是否合适？"
   - 询问："是否进入下一阶段（执行代码生成）？"

2. **等待用户反馈**
   - 如果用户不满意，询问具体需要修改的地方
   - 如果用户要求回退，执行回退机制（见错误陷阱部分）
   - 如果用户确认，标记阶段 5 为已完成，准备进入阶段 6

### 工具调用

#### 必须使用的工具
1. **Read 工具**：读取现有文件
   - 使用场景：读取需求文档、设计文档、索引、会话记录、提示词模板
   - 命令：`Read(file_path="d:\\idea_demo\\datai\\docs\\requirements\\2026-01-21-001-用户登录功能.md")`

2. **Write 工具**：创建或更新文件
   - 使用场景：生成提示词、更新索引、更新需求文档、更新会话记录
   - 命令：`Write(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md", content="...")`

3. **LS 工具**：检查目录是否存在
   - 使用场景：创建提示词前检查 `docs/prompts/` 目录
   - 命令：`LS(path="d:\\idea_demo\\datai\\docs")`

4. **SearchCodebase 工具**：搜索现有提示词
   - 使用场景：查找现有提示词作为参考
   - 命令：`SearchCodebase(information_request="查找 docs/prompts 目录下的所有提示词")`

#### 可选使用的工具
1. **Glob 工具**：查找文件
   - 使用场景：查找所有提示词
   - 命令：`Glob(pattern="docs/prompts/*.md")`

2. **TodoWrite 工具**：管理任务
   - 使用场景：跟踪阶段执行进度
   - 命令：`TodoWrite(todos=[...])`

---

## D. 错误陷阱与验证 (Anti-Patterns & Checklist)

### 常见错误（Anti-Patterns）

#### 错误 1：不引用真源
**错误示例**：
```markdown
# 提示词：用户登录功能

## 需求描述
实现用户登录功能...
```

**问题**：
- 没有引用真源（需求文档和设计文档）
- 违反了 SSOT 原则

**正确示例**：
```markdown
# 提示词：用户登录功能

## 引用真源
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)

## 需求描述
实现用户登录功能...
```

#### 错误 2：输出格式要求不明确
**错误示例**：
```markdown
## 输出格式要求
请生成用户登录功能的代码。
```

**问题**：
- 输出格式要求不明确
- 没有指定需要生成的文件
- 没有指定代码规范
- 没有指定测试要求

**正确示例**：
```markdown
## 输出格式要求
1. 必须包含以下文件：
   - Controller：`SysLoginController.java`
   - Service：`SysLoginService.java`
   - Mapper：`SysUserMapper.java`
   - Entity：`SysUser.java`
   - 配置类：`SecurityConfig.java`
2. 必须包含单元测试：
   - `SysLoginServiceTest.java`
3. 必须符合 Spring Boot 最佳实践
4. 必须遵循若依框架规范
```

#### 错误 3：代码规范要求不明确
**错误示例**：
```markdown
## 代码规范要求
请遵循项目代码规范。
```

**问题**：
- 代码规范要求不明确
- 没有指定具体的命名规范
- 没有指定具体的注释规范

**正确示例**：
```markdown
## 代码规范要求
1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
2. 方法命名：首字母小写，驼峰命名，如 `login`
3. 变量命名：首字母小写，驼峰命名，如 `userName`
4. 注释规范：
   - 类注释：使用 `/** */`，包含类功能描述
   - 方法注释：使用 `/** */`，包含方法功能、参数、返回值描述
   - 字段注释：使用 `/** */`，包含字段功能描述
```

#### 错误 4：测试要求不明确
**错误示例**：
```markdown
## 测试要求
请添加单元测试。
```

**问题**：
- 测试要求不明确
- 没有指定测试覆盖率
- 没有指定测试框架
- 没有指定测试用例规范

**正确示例**：
```markdown
## 测试要求
1. 单元测试覆盖率不低于 80%
2. 测试用例包含正常场景和异常场景
3. 使用 JUnit 5 和 Mockito 进行测试
4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`
```

#### 错误 5：不更新需求文档的提示词引用
**错误示例**：
```
AI：生成提示词
AI：更新 docs/index.md
AI：完成（忘记更新需求文档）
```

**正确示例**：
```
AI：生成提示词
AI：更新 docs/index.md
AI：更新需求文档，添加提示词引用
AI：完成
```

#### 错误 6：不询问用户确认就进入下一阶段
**错误示例**：
```
AI：生成提示词
AI：进入阶段 6：执行代码生成（未询问用户）
```

**正确示例**：
```
AI：生成提示词
AI：提示词已生成：[链接]
AI：提示词是否合适？
AI：是否进入下一阶段（执行代码生成）？
```

### 验收清单（Checklist）

在完成阶段 5 前，必须检查以下项目：

#### 提示词完整性检查
- [ ] 提示词已创建在 `docs/prompts/` 目录下
- [ ] 提示词命名符合 `YYYY-MM-DD-00X-prompt-提示词名.md` 格式
- [ ] 提示词包含引用真源（需求文档和设计文档的链接）
- [ ] 提示词包含需求描述
- [ ] 提示词包含设计方案
- [ ] 提示词包含输出格式要求
- [ ] 提示词包含代码规范要求
- [ ] 提示词包含测试要求

#### 提示词质量检查
- [ ] 引用真源格式正确
- [ ] 需求描述清晰、准确
- [ ] 设计方案完整、准确
- [ ] 输出格式要求明确、具体
- [ ] 代码规范要求明确、具体
- [ ] 测试要求明确、具体

#### 索引更新检查
- [ ] `docs/index.md` 已更新
- [ ] 新提示词链接已添加到"提示词"部分
- [ ] 索引链接格式正确：`[文档名](./相对路径/文件名.md)`
- [ ] 索引更新采用增量策略，未删除现有内容

#### 需求文档更新检查
- [ ] 需求文档已更新
- [ ] 需求文档的"相关文档"部分已添加提示词引用
- [ ] 提示词引用格式正确：`[提示词文档](../prompts/YYYY-MM-DD-00X-prompt-提示词名.md)`

#### 会话记录更新检查
- [ ] 会话记录已更新
- [ ] 会话记录的"当前阶段"已更新为"阶段 5：提示词生成"
- [ ] 会话记录的"阶段 5：提示词生成"状态已更新为"已完成"
- [ ] 会话记录包含提示词链接
- [ ] 会话记录包含提示词内容摘要

#### 用户确认检查
- [ ] 已向用户显示提示词链接
- [ ] 已询问用户"提示词是否合适？"
- [ ] 已询问用户"是否进入下一阶段？"
- [ ] 已等待用户反馈

#### 回退机制检查（如果需要）
- [ ] 如果用户不满意，已询问具体需要修改的地方
- [ ] 如果用户要求回退，已删除相关文档
- [ ] 如果用户要求回退，已撤销索引更新
- [ ] 如果用户要求回退，已撤销需求文档更新
- [ ] 如果用户要求回退，已更新会话记录

### Correct vs Incorrect 代码对比

#### Incorrect（错误示例）
```markdown
# 提示词：用户登录功能

## 需求描述
实现用户登录功能，包括用户名和密码验证、记住密码、自动登录等。

## 设计方案
使用 Spring Security 和 JWT。

## 输出格式要求
请生成代码。
```

#### Correct（正确示例）
```markdown
# 提示词：用户登录功能

## 引用真源
- [需求文档](../requirements/2026-01-21-001-用户登录功能.md)
- [设计文档](../design/2026-01-21-001-用户登录功能-设计.md)

## 需求描述
根据需求文档，实现用户登录功能，包括：
1. 用户名和密码验证
2. 记住密码功能
3. 自动登录功能
4. 登录失败提示
5. 登录成功后跳转到首页

## 设计方案
根据设计文档，采用以下技术方案：
1. 认证框架：Spring Security 6.x
2. Token 生成：JWT
3. 密码加密：BCrypt
4. 会话管理：Redis 存储 Token
5. 权限框架：若依权限系统

## 输出格式要求
1. 必须包含以下文件：
   - Controller：`SysLoginController.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/controller/SysLoginController.java`）
   - Service：`SysLoginService.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/service/SysLoginService.java`）
   - Mapper：`SysUserMapper.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/mapper/SysUserMapper.java`）
   - Entity：`SysUser.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/domain/SysUser.java`）
   - 配置类：`SecurityConfig.java`（路径：`datai-modules-system/src/main/java/com/datai/modules/system/config/SecurityConfig.java`）
2. 必须包含单元测试：
   - `SysLoginServiceTest.java`（路径：`datai-modules-system/src/test/java/com/datai/modules/system/service/SysLoginServiceTest.java`）
3. 必须符合 Spring Boot 最佳实践
4. 必须遵循若依框架规范
5. 必须使用 MyBatis Plus 进行数据库操作

## 代码规范要求
1. 类命名：首字母大写，驼峰命名，如 `SysLoginController`
2. 方法命名：首字母小写，驼峰命名，如 `login`
3. 变量命名：首字母小写，驼峰命名，如 `userName`
4. 注释规范：
   - 类注释：使用 `/** */`，包含类功能描述、作者、创建时间
   - 方法注释：使用 `/** */`，包含方法功能、参数、返回值、异常描述
   - 字段注释：使用 `/** */`，包含字段功能描述
5. 代码格式：使用 4 个空格缩进，行宽不超过 120 字符
6. 导入规范：使用 import 静态导入，避免通配符导入

## 测试要求
1. 单元测试覆盖率不低于 80%
2. 测试用例包含以下场景：
   - 正常登录成功
   - 用户名不存在
   - 密码错误
   - 用户已停用
   - 验证码错误
3. 使用 JUnit 5 和 Mockito 进行测试
4. 测试用例命名规范：`test+方法名+场景`，如 `testLoginSuccess`
5. 测试数据使用 Mockito 模拟

## 注意事项
1. 必须处理 Salesforce API 的空值情况
2. 必须使用若依的 `@DataScope` 注解进行数据权限控制
3. 必须使用若依的 `@Log` 注解记录操作日志
4. 必须使用若依的 `GlobalExceptionHandler` 处理异常
```

---

## 附录：快速参考

### 文件路径速查
- 需求文档：`docs/requirements/YYYY-MM-DD-00X-需求名.md`
- 设计文档：`docs/design/YYYY-MM-DD-00X-设计名.md`
- 提示词：`docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md`
- 主索引：`docs/index.md`
- 会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`
- 项目规则：`.trae/rules/project_rules.md`
- SSOT 架构师提示词：`docs/Prompt/0004-单一真源文档驱动架构师.md`
- 提示词模板：`docs/Prompt/0000-template.md`

### 工具命令速查
```powershell
# 读取需求文档
Read(file_path="d:\\idea_demo\\datai\\docs\\requirements\\2026-01-21-001-用户登录功能.md")

# 读取设计文档
Read(file_path="d:\\idea_demo\\datai\\docs\\design\\2026-01-21-001-用户登录功能-设计.md")

# 生成提示词
Write(file_path="d:\\idea_demo\\datai\\docs\\prompts\\2026-01-21-001-prompt-用户登录功能.md", content="...")

# 读取索引
Read(file_path="d:\\idea_demo\\datai\\docs\\index.md")

# 更新索引
Write(file_path="d:\\idea_demo\\datai\\docs\\index.md", content="...")

# 搜索现有提示词
SearchCodebase(information_request="查找 docs/prompts 目录下的所有提示词")

# 查找所有提示词
Glob(pattern="docs/prompts/*.md")
```

### 阶段 5 输出清单
- [ ] 提示词文档：`docs/prompts/YYYY-MM-DD-00X-prompt-提示词名.md`
- [ ] 更新的索引：`docs/index.md`
- [ ] 更新的需求文档：`docs/requirements/YYYY-MM-DD-00X-需求名.md`
- [ ] 更新的会话记录：`docs/sessions/YYYY-MM-DD-00X-session.md`

### 下一阶段提示
如果用户确认进入下一阶段，请参考：
- [project_rules.md](file:///d:\idea_demo\datai\.trae\rules\project_rules.md) 的"阶段 6：执行代码生成"
- 准备分析需求和设计文档
- 准备确定需要生成的代码文件
- 准备加载阶段 5 生成的提示词
- 准备生成代码