kris/datai
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
3d290a8dd1
datai/docs/archive/skill/0006-prompt-engineering.md

9.4 KiB
Raw Blame History

name description
0006-prompt-engineering 提示词资产化，基于 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: 分析提示词目标

## 提示词目标分析

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

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

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

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

步骤 2: 确定上下文链接

## 上下文链接分析

### 必须引用的文档
- [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: 定义输入变量

## 输入变量定义

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

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

步骤 4: 定义输出格式

## 输出格式定义

### 输出格式
[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: 创建提示词文档

---
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]

输出示例

[输出示例]

版本历史 (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 示例

## 上下文链接 (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 示例

## 上下文
参考需求文档和设计文档

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

## 输出
Java 代码

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

相关文档 (Related Documents)