datai/docs/archive/skill/0006-prompt-engineering.md

---
name: 0006-prompt-engineering
description: 提示词资产化，基于 Prompt 模板编写执行提示词
---

# 技能：提示词资产化 (Prompt Engineering)

## 元数据 (Metadata)

- **name**: prompt-engineering
- **description**: 提示词资产化，基于 Prompt 模板编写执行提示词
- **version**: 1.0.0
- **author**: SSOT Architect
- **lastUpdated**: 2026-01-15

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

### 触发条件 (Triggers)
当以下情况发生时，AI 应当"觉醒"本技能：

1. **架构决策完成**: 完成架构决策后，需要编写执行提示词
2. **新功能开发**: 需要为特定功能创建提示词
3. **提示词优化**: 发现现有提示词效果不好，需要优化
4. **代码生成**: 需要生成特定类型的代码
5. **工作流阶段 3**: 用户进入工作流的"提示词资产化"阶段

### 定位范围 (Scope)
- **适用模块**: 所有 Datai 项目模块
- **影响文件**: `docs/prompts/PROMPT-XXX.md`, `docs/index.md`
- **相关技能**: skill-architecture-decision, skill-context-anchoring

## 核心指令集 (Instructions)

### 架构约束 (Architecture Constraints)

1. **Treat Prompts as Code 原则**:
   - 提示词必须有输入变量
   - 提示词必须有输出定义
   - 提示词必须有版本号
   - 提示词必须可重复调用

2. **提示词必须包含**:
   - Goal: 该提示词解决什么具体问题？
   - Context Links: 引用了哪些 docs（必须是相对链接）
   - Inputs: 需要用户提供哪些变量？
   - Prompt Content: 实际的提示词内容（Markdown Code Block）
   - Output Definition: 期望的输出格式（JSON/Markdown/Code）
   - Version: 提示词的版本号

3. **引用真源规则**:
   - 提示词开头必须引用 `docs/requirements/` 和 `docs/design/` 的文件链接
   - 必须明确引用的上下文文件
   - 必须说明引用的原因

4. **搜索策略规则**:
   - 在 Prompt 中明确规定接下来需要查找哪些文件作为参考
   - 必须指定搜索的关键词和文件类型
   - 必须说明搜索的目的

### 业务逻辑 SOP (Business Logic SOP)

#### 步骤 1: 分析提示词目标
```markdown
## 提示词目标分析

### 要解决的问题
[该提示词解决什么具体问题？]

### 使用场景
[在什么情况下使用这个提示词？]

### 预期效果
[使用这个提示词后期望达到什么效果？]

### 目标用户
[谁会使用这个提示词？]
```

#### 步骤 2: 确定上下文链接
```markdown
## 上下文链接分析

### 必须引用的文档
- [REQ-XXX](../../requirements/REQ-XXX.md) - [引用原因]
- [DES-XXX](../../design/DES-XXX.md) - [引用原因]
- [ADR-XXX](../../decisions/adr/ADR-XXX.md) - [引用原因]

### 参考文档
- [文档1](../../path/to/doc1.md) - [引用原因]
- [文档2](../../path/to/doc2.md) - [引用原因]

### 代码参考
- [类1](../../path/to/Class1.java) - [引用原因]
- [类2](../../path/to/Class2.java) - [引用原因]
```

#### 步骤 3: 定义输入变量
```markdown
## 输入变量定义

### 必填变量
| 变量名 | 类型 | 说明 | 示例 | 默认值 |
|--------|------|------|------|--------|
| [变量名] | [类型] | [说明] | [示例] | [默认值] |

### 可选变量
| 变量名 | 类型 | 说明 | 示例 | 默认值 |
|--------|------|------|------|--------|
| [变量名] | [类型] | [说明] | [示例] | [默认值] |
```

#### 步骤 4: 定义输出格式
```markdown
## 输出格式定义

### 输出格式
[JSON/Markdown/Code]

### 输出结构
[详细的输出结构说明]

### 输出要求
- [要求1]
- [要求2]
- [要求3]

### 输出示例
```json
{
  "field1": "value1",
  "field2": "value2"
}
```
```

#### 步骤 5: 编写提示词内容
```markdown
## 提示词内容

### 角色设定
你是 [角色描述]。

### 任务描述
[任务描述]

### 上下文信息
基于以下文档：
- [REQ-XXX](../../requirements/REQ-XXX.md)
- [DES-XXX](../../design/DES-XXX.md)
- [ADR-XXX](../../decisions/adr/ADR-XXX.md)

### 搜索策略
在开始执行前，请搜索以下文件作为参考：
1. 搜索关键词：[关键词]，文件类型：[文件类型]
2. 搜索关键词：[关键词]，文件类型：[文件类型]

### 执行步骤
1. [步骤1]
2. [步骤2]
3. [步骤3]

### 输出要求
- [要求1]
- [要求2]
- [要求3]

### 输出格式
[输出格式说明]
```

#### 步骤 6: 创建提示词文档
```markdown
---
name: PROMPT-001
description: [提示词描述]
version: 1.0.0
---

# 提示词: [提示词名称]

## 元数据 (Metadata)

- **name**: [提示词名称]
- **description**: [该提示词解决什么具体问题？]
- **version**: [版本号]
- **author**: [作者]
- **lastUpdated**: [最后更新日期]

## 目标 (Goal)

[该提示词解决什么具体问题？]

## 上下文链接 (Context Links)

### 必须引用的文档
- [REQ-XXX](../../requirements/REQ-XXX.md) - [引用原因]
- [DES-XXX](../../design/DES-XXX.md) - [引用原因]
- [ADR-XXX](../../decisions/adr/ADR-XXX.md) - [引用原因]

### 参考文档
- [文档1](../../path/to/doc1.md) - [引用原因]
- [文档2](../../path/to/doc2.md) - [引用原因]

### 代码参考
- [类1](../../path/to/Class1.java) - [引用原因]
- [类2](../../path/to/Class2.java) - [引用原因]

## 输入变量 (Inputs)

### 必填变量
| 变量名 | 类型 | 说明 | 示例 | 默认值 |
|--------|------|------|------|--------|
| [变量名] | [类型] | [说明] | [示例] | [默认值] |

### 可选变量
| 变量名 | 类型 | 说明 | 示例 | 默认值 |
|--------|------|------|------|--------|
| [变量名] | [类型] | [说明] | [示例] | [默认值] |

## 提示词内容 (Prompt Content)

```markdown
[实际的提示词内容]
```

## 输出定义 (Output Definition)

### 输出格式
[期望的输出格式：JSON/Markdown/Code]

### 输出结构
[详细的输出结构说明]

### 输出要求
- [要求1]
- [要求2]
- [要求3]

### 输出示例
```json
[输出示例]
```

## 版本历史 (Version History)

| 版本 | 日期 | 变更内容 | 变更人 |
|------|------|----------|--------|
| 1.0.0 | YYYY-MM-DD | 初始版本 | [姓名] |
```

#### 步骤 7: 更新 docs/index.md
```markdown
### 💡 提示词资产 (Prompts)
| 文档 | 版本 | 描述 | 更新日期 |
|------|------|------|----------|
| [PROMPT-001](prompts/PROMPT-001.md) | v1.0.0 | [提示词描述] | 2026-01-15 |
```

### 工具调用 (Tool Usage)

1. **提示词编号生成工具**:
   - 使用 `Grep` 工具搜索 `docs/prompts/` 目录
   - 查找最大的 PROMPT 编号
   - 生成新的 PROMPT 编号

2. **上下文链接验证工具**:
   - 使用 `Read` 工具验证引用的文档是否存在
   - 使用 `LS` 工具验证引用的文件路径是否正确

3. **文件创建工具**:
   - 使用 `Write` 工具创建提示词文档
   - 确保文件路径正确

4. **索引更新工具**:
   - 使用 `Read` 工具读取 `docs/index.md`
   - 使用 `SearchReplace` 工具更新索引

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

### 常见错误 (Anti-Patterns)

1. **错误**: 提示词缺少版本号
   - **后果**: 无法追踪提示词的变更历史
   - **修正**: 必须包含版本号和版本历史

2. **错误**: 引用文档使用绝对路径
   - **后果**: 文档移动后链接失效
   - **修正**: 必须使用相对链接

3. **错误**: 输入变量定义不清晰
   - **后果**: 用户不知道需要提供什么输入
   - **修正**: 必须明确定义每个输入变量的类型、说明和示例

4. **错误**: 输出格式不明确
   - **后果**: AI 输出的格式不符合预期
   - **修正**: 必须明确定义输出格式和输出结构

5. **错误**: 提示词内容过于简单
   - **后果**: AI 无法理解任务要求
   - **修正**: 必须包含详细的任务描述、上下文信息和执行步骤

### 验收清单 (Acceptance Checklist)

- [ ] 提示词文档已创建
- [ ] 提示词编号符合规范
- [ ] 目标已明确定义
- [ ] 上下文链接已定义
- [ ] 输入变量已定义
- [ ] 输出格式已定义
- [ ] 提示词内容已编写
- [ ] 版本号已定义
- [ ] docs/index.md 已更新
- [ ] 相关文档已链接

### Correct vs Incorrect 对比

#### Correct 示例
```markdown
## 上下文链接 (Context Links)

### 必须引用的文档
- [REQ-001](../../requirements/REQ-001.md) - 用户需求
- [DES-001](../../design/DES-001.md) - 系统设计
- [ADR-001](../../decisions/adr/ADR-001.md) - 技术选型

## 输入变量 (Inputs)

| 变量名 | 类型 | 说明 | 示例 | 默认值 |
|--------|------|------|------|--------|
| className | String | Java 类名 | UserService | - |
| packageName | String | 包名 | com.datai.service | - |
| fields | Array | 字段列表 | [{name: "id", type: "Long"}] | - |

## 输出定义 (Output Definition)

### 输出格式
Java Code

### 输出结构
完整的 Java 类文件，包含：
- 包声明
- 导入语句
- 类定义
- 字段定义
- 方法定义
```

#### Incorrect 示例
```markdown
## 上下文
参考需求文档和设计文档

## 输入
- 类名
- 包名
- 字段

## 输出
Java 代码
```

**问题**: 上下文链接不明确，输入变量定义不清晰，输出格式不具体。

## 相关文档 (Related Documents)

- [工作流提示词](../prompts/03-创建工作流提示词.md#阶段-3-提示词资产化-prompt-engineering)
- [架构决策技能](./0005-architecture-decision.md)
- [上下文锚定技能](./0007-context-anchoring.md)
- [Prompt 模板](../prompts/03-创建工作流提示词.md#42-prompt-first-模板-提示词资产)