Prompt 工程规范

本文档定义了 OpenCode 教程中提示词的编写规范，确保所有模板保持一致的高质量。

---

🎯 核心原则

1. 结构化优先（Structure First）

每个模板必须包含明确的结构层次：

角色定义 → 任务说明 → 输入规范 → 输出规范 → 示例 → 约束条件

2. Few-shot 必备（Example-Driven）

复杂任务必须提供 1-2 个具体示例，让模型理解预期输入/输出格式。

3. 显式思维链（Chain of Thought）

对于推理类任务，明确引导"先分析，再输出"的步骤式思考。

4. 量化评估标准（Quantified Criteria）

任何评分/评估必须有明确的评分维度和每个分数段的定义。

5. 错误处理机制（Graceful Degradation）

模板应包含：输入不完整时如何处理、遇到歧义时如何澄清、超出能力范围时如何反馈。

6. 自检机制（Self-Verification）

复杂任务输出前进行自我检查，确保符合要求。

7. 占位符一致性（Consistent Placeholders）

全文档使用统一的占位符语法，清晰区分必填和选填。

---

📋 标准模板结构

## 角色
你是[专业身份]，擅长[核心能力]。[额外的身份锚定描述]

## 任务
[清晰描述要完成的任务]

## 输入信息
### 必填项
- 变量名：【变量说明】

### 选填项
- 变量名：【变量说明?】（默认：xxx）

## 输出规范
按以下结构输出：
1. [输出项1]
2. [输出项2]
...

## 示例

### 输入
[具体输入示例]

### 输出
[对应的理想输出]

## 约束条件
- ✅ 应该：[正面行为]
- ❌ 避免：[负面行为]

## 自检清单
完成前确认：
- [ ] [检查项1]
- [ ] [检查项2]

## 错误处理
- 如果缺少关键信息，请先询问用户
- 如果任务超出范围，说明原因并建议替代方案

---

🏷️ 占位符规范

语法

类型	语法	示例
必填变量	【变量名】	【编程语言】
选填变量	【变量名?】	【框架?】
带默认值	【变量名=默认值】	【风格=轻松】
多选一	【选项1/选项2/选项3】	【玄幻/都市/言情】
文本块	[粘贴区域描述]	[粘贴代码]

示例对比

❌ 差的写法：

类型：玄幻/都市/言情
语言：语言
粘贴代码

✅ 好的写法：

类型：【玄幻/都市/言情/悬疑/科幻】
语言：【编程语言】

[粘贴代码]

---

📊 评分标准规范

任何使用评分的模板，必须定义评分标准：

示例：代码质量评分

分数	可读性	性能	安全性	测试覆盖
9-10	命名清晰、注释完整	O(n)或更优	无漏洞	>90%
7-8	命名合理、关键注释	O(n log n)	低风险	70-90%
5-6	基本可读	O(n²)	中风险	50-70%
<5	难以理解	O(n³)+	高风险	<50%

综合得分计算：可读性×0.3 + 性能×0.3 + 安全性×0.25 + 测试覆盖×0.15

---

👤 角色定义规范

要素

1. 专业身份：你是谁
2. 核心能力：擅长什么
3. 服务对象：为谁服务（可选）
4. 风格特点：工作风格（可选）

示例

❌ 差的写法：

你是一个助手。

✅ 好的写法：

你是资深技术文档工程师，擅长将复杂代码解释得通俗易懂。
你的解释被初学者评价为"终于看懂了"。

---

⚖️ 约束条件规范

使用 ✅ 和 ❌ 明确区分正面和负面行为：

## 约束条件
- ✅ 问题要具体到行号
- ✅ 每个问题都要有修复建议
- ✅ 肯定做得好的地方
- ❌ 避免主观偏好替代客观标准
- ❌ 避免只批评不给方案

---

🔧 错误处理规范

每个模板都应该包含错误处理部分：

## 错误处理
- 如果信息不足，列出需要补充的信息并说明为什么需要
- 如果问题超出能力范围，说明并建议求助渠道
- 如果有多个独立问题，建议逐个处理

---

✅ 自检清单规范

复杂任务应包含自检清单：

## 自检清单
完成前确认：
- [ ] 每个主角都有清晰的弧线
- [ ] 起承转合节奏合理
- [ ] 核心冲突能贯穿全文
- [ ] 亮点足以吸引目标读者

---

🤖 Agent/Skill description 规范

结构模板

description: |
  [一句话说明核心能力]
  提供：[该 Skill 包含的资源]
  适用：[触发场景1]、[触发场景2]
  不适用：[边界场景1]、[边界场景2]

示例

❌ 差的写法：

description: 代码审查专家

✅ 好的写法：

description: |
  代码审查专家，专注安全漏洞、性能问题、代码质量。
  适用场景：PR 审查、代码健康检查、安全审计。
  不适用：代码生成、功能实现、测试编写。

---

📝 检查清单

发布模板前，确认以下事项：

• 有明确的角色定义
• 输入信息区分必填/选填
• 有完整的输出规范
• 复杂任务有 Few-shot 示例
• 评分类有量化标准
• 有约束条件（✅/❌）
• 有错误处理机制
• 占位符语法统一
• 无格式错误

---

相关资源

• Prompt 模板库 - 开箱即用的模板
• Agent 快速入门 - 创建 Agent
• Skill 基础 - 创建 Skill