Prompt 工程指南
在 AI 辅助编程的时代，Prompt 工程（提示词工程） 是一项核心技能。编写高质量的提示词，可以帮助 Opencode 更准确地理解你的意图，生成更符合需求的代码。
什么是 Prompt 工程？
Prompt 工程是指通过设计和优化输入给 AI 模型的文本（即"提示词"），以引导模型生成特定输出的过程。
在 Opencode 中，这意味着如何用自然语言描述你的编程任务，让 AI 能够：
- 准确理解你的需求
- 生成符合规范的代码
- 考虑边界条件和错误处理
- 遵循项目的编码风格
基本原则
1. 清晰明确（Be Clear）
避免模棱两可的描述，提供具体的细节。
❌ 不好的提示词：
写个函数处理数据
✅ 好的提示词：
编写一个 Python 函数 process_csv_data，功能：
- 接收一个 CSV 文件路径作为参数
- 读取文件内容
- 过滤掉空行
- 返回一个包含所有数据行的列表
- 如果文件不存在，抛出 FileNotFoundError
2. 提供上下文（Context is Key）
告诉 AI 你正在做什么项目，使用了什么技术栈。
❌ 不好的提示词：
创建一个登录组件
✅ 好的提示词：
这是一个使用 React 18 + TypeScript + Tailwind CSS 的项目。
请创建一个登录组件，要求：
- 使用函数组件和 Hooks
- 包含邮箱和密码输入框
- 使用 Tailwind CSS 样式
- 添加表单验证
- 使用 React Hook Form 管理表单状态
3. 指定输出格式（Specify Output）
如果你需要特定的格式，请明确指出。
✅ 指定格式的提示词：
分析这段代码的时间复杂度，以 Markdown 表格的形式列出：
- 操作名称
- 时间复杂度
- 说明
✅ 只要代码：
实现一个二分查找算法。
只返回代码，不需要解释。
4. 分步指导（Step by Step）
对于复杂任务，将其拆分为多个简单的步骤。
✅ 分步提示词：
帮我重构这个用户认证模块，按以下步骤：
1. 首先分析现有代码的问题
2. 提出改进方案
3. 将认证逻辑提取到单独的服务类
4. 添加单元测试
5. 更新相关文档
每完成一步，等待我确认后再继续下一步。
5. 提供示例（Few-Shot Learning）
给出几个输入输出的例子，让 AI 模仿。
✅ 提供示例的提示词：
编写一个函数，将驼峰命名转换为下划线命名。
示例：
- camelCase → camel_case
- myVariableName → my_variable_name
- HTTPSConnection → https_connection
请实现这个函数。
常用场景示例
代码生成
基础代码生成：
使用 Python 实现一个 LRU 缓存，要求：
- 支持 get 和 put 操作
- 时间复杂度 O(1)
- 使用字典和双向链表实现
- 包含完整的类型注解
组件生成：
创建一个 Vue 3 的分页组件，功能：
- 显示当前页码和总页数
- 上一页、下一页按钮
- 页码跳转输入框
- 每页显示数量选择器
- 使用 Composition API
- 使用 TypeScript
- 样式使用 Tailwind CSS
API 接口生成：
使用 Express.js 创建一个 RESTful API，管理用户信息：
- GET /api/users - 获取所有用户
- GET /api/users/:id - 获取单个用户
- POST /api/users - 创建用户
- PUT /api/users/:id - 更新用户
- DELETE /api/users/:id - 删除用户
要求：
- 使用 TypeScript
- 添加输入验证
- 添加错误处理
- 使用 async/await
代码解释
解释复杂逻辑：
解释这段代码的工作原理，特别是：
1. 递归的终止条件
2. 状态如何传递
3. 为什么使用 memo 优化
[粘贴代码]
解释设计模式：
这段代码使用了什么设计模式？
请说明：
- 模式名称
- 为什么使用这个模式
- 有什么优缺点
- 是否有更好的替代方案
[粘贴代码]
代码重构
提高可读性：
重构这个函数，使其更具可读性：
- 提取重复的逻辑为辅助函数
- 使用有意义的变量名
- 添加注释说明关键步骤
- 简化嵌套的 if 语句
[粘贴代码]
性能优化：
优化这段代码的性能：
- 分析当前的时间复杂度
- 找出性能瓶颈
- 提出优化方案
- 实现优化后的代码
- 说明优化后的时间复杂度
[粘贴代码]
错误修复
调试错误：
我遇到了这个错误：
[粘贴错误信息]
相关代码：
[粘贴代码]
请帮我：
1. 分析错误原因
2. 找出问题所在
3. 提供修复方案
4. 解释如何避免类似问题
修复 Bug：
这段代码有 Bug，在某些情况下会返回错误的结果：
[粘贴代码]
测试用例：
- 输入：[示例输入]
- 期望输出：[期望结果]
- 实际输出：[实际结果]
请找出并修复 Bug。
测试生成
单元测试：
为这个函数编写单元测试：
[粘贴代码]
要求：
- 使用 Jest 框架
- 覆盖正常情况
- 覆盖边界条件
- 覆盖异常情况
- 测试覆盖率达到 100%
集成测试：
为这个 API 端点编写集成测试：
[粘贴代码]
要求：
- 使用 Supertest
- 测试成功场景
- 测试失败场景
- 测试输入验证
- 测试权限控制
文档生成
API 文档：
为这个 API 生成文档，使用 OpenAPI 3.0 格式：
[粘贴代码]
包含：
- 端点描述
- 请求参数
- 响应格式
- 错误码说明
- 使用示例
代码注释：
为这段代码添加详细的注释：
- 函数功能说明
- 参数说明
- 返回值说明
- 使用示例
- 注意事项
[粘贴代码]
进阶技巧
1. 角色扮演（Role Playing）
让 AI 扮演特定的角色，会得到更专业的回答。
✅ 使用角色扮演：
你是一位资深的前端架构师，精通 React 和性能优化。
请审查这个组件的代码，从以下角度分析：
1. 性能问题
2. 可维护性
3. 可访问性
4. 最佳实践
[粘贴代码]
2. 约束条件（Constraints）
明确指出限制条件，让 AI 在约束内工作。
✅ 指定约束：
实现一个排序算法，约束条件：
- 不能使用内置的 sort 方法
- 空间复杂度必须是 O(1)
- 必须是稳定排序
- 代码行数不超过 50 行
3. 思维链（Chain of Thought）
引导 AI 展示思考过程。
✅ 使用思维链：
解决这个算法问题，请展示你的思考过程：
1. 首先分析问题的本质
2. 列出可能的解决方案
3. 比较各方案的优劣
4. 选择最优方案并说明理由
5. 实现代码
6. 分析时间和空间复杂度
问题：[描述问题]
4. 迭代改进（Iterative Refinement）
通过多轮对话逐步完善。
✅ 迭代改进流程：
第一轮：
"创建一个基础的用户管理系统"
第二轮：
"添加用户角色和权限管理"
第三轮：
"添加用户活动日志记录"
第四轮：
"优化数据库查询性能"
5. 对比分析（Comparison）
让 AI 比较不同的方案。
✅ 对比分析：
比较以下三种状态管理方案在 React 项目中的应用：
1. Redux
2. MobX
3. Zustand
从以下维度对比：
- 学习曲线
- 性能表现
- 代码量
- 适用场景
- 生态系统
以表格形式呈现，并给出推荐。
使用 AGENTS.md 增强上下文
在项目根目录创建 AGENTS.md，让 AI 记住项目规范：
# 项目规范
## 技术栈
- 前端：React 18 + TypeScript + Vite
- 后端：Node.js + Express + PostgreSQL
- 样式：Tailwind CSS
- 测试：Jest + React Testing Library
## 编码规范
- 使用 ESLint + Prettier
- 组件使用函数式 + Hooks
- 使用 TypeScript 严格模式
- 所有函数必须有类型注解
## 命名规范
- 组件：PascalCase (UserProfile.tsx)
- 函数：camelCase (getUserData)
- 常量：UPPER_SNAKE_CASE (API_BASE_URL)
- 文件：kebab-case (user-profile.tsx)
## 目录结构
- `/src/components` - 可复用组件
- `/src/features` - 功能模块
- `/src/hooks` - 自定义 Hooks
- `/src/utils` - 工具函数
- `/src/types` - TypeScript 类型定义
## API 规范
- 使用 RESTful 风格
- 统一使用 `/api/v1` 前缀
- 错误使用标准 HTTP 状态码
- 响应格式：`{ success: boolean, data: any, error?: string }`
## 提交规范
- feat: 新功能
- fix: Bug 修复
- refactor: 重构
- docs: 文档更新
- test: 测试相关
- chore: 构建/工具相关
有了 AGENTS.md，你只需要说：
创建一个用户列表组件
AI 会自动：
- 使用 React + TypeScript
- 遵循项目的命名规范
- 放在正确的目录
- 使用 Tailwind CSS 样式
- 添加类型注解
详细了解：智能体与 AGENTS.md
常见错误与改进
错误 1：描述过于简单
❌ 错误：
写个登录功能
✅ 改进：
实现用户登录功能，要求：
- 使用 JWT 认证
- 支持邮箱和密码登录
- 密码使用 bcrypt 加密
- 登录失败 3 次后锁定账号 15 分钟
- 返回用户信息和 token
错误 2：没有指定技术栈
❌ 错误：
创建一个 API 接口
✅ 改进：
使用 Express.js + TypeScript 创建一个 API 接口，
获取用户列表，支持分页和搜索
错误 3：没有说明边界条件
❌ 错误：
写个函数计算平均值
✅ 改进：
写一个函数计算数组的平均值，要求：
- 如果数组为空，返回 0
- 如果数组包含非数字，抛出错误
- 保留两位小数
- 添加类型注解
错误 4：一次要求太多
❌ 错误：
创建一个完整的电商系统，包括用户管理、商品管理、
订单管理、支付系统、物流跟踪、评论系统...
✅ 改进：
第一步：创建用户管理模块的数据库表结构
完成后，我会继续下一步。
实用模板
功能开发模板
功能：[功能名称]
需求：
1. [需求 1]
2. [需求 2]
3. [需求 3]
技术要求：
- 语言/框架：[具体技术]
- 设计模式：[如果有]
- 性能要求：[如果有]
约束条件：
- [约束 1]
- [约束 2]
请先给出设计方案，确认后再实现。
Bug 修复模板
Bug 描述：[简要描述]
复现步骤：
1. [步骤 1]
2. [步骤 2]
3. [步骤 3]
期望结果：[期望的行为]
实际结果：[实际的行为]
相关代码：
[粘贴代码]
错误信息：
[粘贴错误]
请分析原因并提供修复方案。
代码审查模板
请审查以下代码：
[粘贴代码]
审查重点：
1. 代码质量和可读性
2. 性能问题
3. 安全漏洞
4. 最佳实践
5. 潜在 Bug
请给出详细的审查报告和改进建议。
总结
好的 Prompt 应该：
- ✅ 清晰明确 - 避免歧义
- ✅ 提供上下文 - 说明项目背景
- ✅ 指定格式 - 明确输出要求
- ✅ 分步指导 - 复杂任务拆分
- ✅ 提供示例 - 让 AI 模仿
- ✅ 说明约束 - 明确限制条件
- ✅ 迭代改进 - 逐步完善
下一步
- 工作流最佳实践 - 学习高效的开发流程
- Agent 配置指南 - 配置 AI 团队
- 智能体与 AGENTS.md - 让 AI 记住项目规范
掌握 Prompt 工程，让 AI 成为你最得力的编程助手！