第 8 章
开发者 Prompt 工程——30个真实场景模板，直接复制使用
第8章：开发者 Prompt 工程——30个真实场景模板，直接复制使用
Prompt 工程不是玄学，是有规律可循的技术。好 Prompt 和坏 Prompt 的差距，不是措辞华丽不华丽，而是信息是否完整、约束是否明确、期望是否具体。本章给出30个开发者最常用场景的即用模板，6大类，每类5个，直接复制修改使用。
为什么大多数 Prompt 不够好
坏 Prompt 的共同特征：
- 只描述"想要什么"，不说"有什么约束"
- 没有给错误信息、没有给当前代码
- 不说清楚上下文（什么框架、什么版本、什么项目背景）
对比示例：
坏的 Prompt：
写一个登录功能
好的 Prompt：
@src/routes/auth.ts @src/services/UserService.ts
在现有的 Express + TypeScript 项目里添加登录接口：
POST /api/auth/login
请求体：{ email: string, password: string }
验证：用 zod 验证格式；bcrypt 验证密码；成功返回 JWT（7天有效期）
失败：统一返回 { error: "Invalid credentials" }，不区分用户不存在和密码错误
约束：不修改 UserService 的接口，只在 auth.ts 里添加路由处理
差距在于：好的 Prompt 给了文件路径、具体的接口规格、错误处理要求、约束条件。AI 有了这些信息，才能生成可直接使用的代码。
30 个即用模板
第一类：理解代码（1-5）
模板 1：理解陌生函数
@文件路径
解释 [函数名] 这个函数：
1. 它做了什么（一句话总结）
2. 输入参数的含义和有效范围
3. 返回值的结构
4. 关键的处理逻辑（3-5个步骤）
5. 可能的边界情况和异常
模板 2：理解复杂业务逻辑
@文件路径1 @文件路径2
我需要理解 [功能名称] 的完整处理流程。
请从 [入口点] 开始，追踪数据流转：
- 每一步做了什么转换
- 哪些地方有条件分支
- 最终结果是什么格式
用编号步骤描述，不要用代码，要用自然语言。
模板 3：对比两种实现
@文件A @文件B
这两个文件都实现了 [相同功能]，对比分析：
1. 核心实现思路的区别
2. 性能上的差异（如果有的话）
3. 各自的优缺点
4. 你建议保留哪个，为什么
模板 4：找出潜在问题
@文件路径
仔细阅读这段代码，找出：
1. 可能的 bug（特别是边界条件、空值、并发问题）
2. 安全隐患（如果有）
3. 性能瓶颈（如果有）
4. 可读性问题
每个问题说明：位置（行号）、风险级别（高/中/低）、原因。
只报告真实存在的问题，不要泛泛而谈。
模板 5：重建设计意图
@文件路径
这段代码没有注释，帮我推断设计意图：
1. 这个类/模块要解决什么问题
2. 为什么这样设计而不是更简单的做法
3. 哪些地方的设计决策值得保留
4. 哪些地方可能是历史债务
基于代码本身推断，不要猜测。
第二类：修复 Bug（6-10）
模板 6：精准定位 Bug
@相关文件
发现 bug：
- 触发条件：[具体操作步骤]
- 期望行为：[应该发生什么]
- 实际行为：[实际发生什么]
- 错误信息：[完整错误堆栈，如果有]
- 环境：[Node 18 / Python 3.11 / 浏览器版本等]
请：
1. 定位 bug 的根本原因（不只是表象）
2. 给出修复代码
3. 说明为什么这样修能解决问题
4. 建议是否需要添加测试来防止回归
模板 7：修复类型错误
@文件路径
TypeScript 报错：
[完整报错信息]
我想保持类型安全，不要用 `any` 来绕过。
请分析报错原因，给出正确的类型修复方案，并解释为什么你的方案是正确的。
模板 8：修复异步问题
@文件路径
这段异步代码有问题，症状是 [描述症状]。
怀疑是 [竞争条件/Promise 链处理错误/await 位置错误] 导致的。
请：
1. 分析异步执行顺序
2. 找出问题所在
3. 给出修复后的完整代码
模板 9：修复性能问题
@文件路径
性能问题描述：
- 操作：[什么操作]
- 数据量：[多少条记录]
- 当前耗时：[多少秒/毫秒]
- 可接受目标：[多少秒/毫秒]
分析可能的性能瓶颈，给出优化方案。
如果是数据库查询问题，给出优化后的查询和建议添加的索引。
模板 10：处理第三方库问题
@Web
使用 [库名] [版本号] 时遇到问题：
- 操作：[具体操作]
- 错误：[错误信息]
- 我的代码：[相关代码片段]
搜索最新的解决方案（这个库版本比较新，可能有 breaking change）。
给出：根本原因、正确用法示例、是否需要版本升级。
第三类：开发新功能（11-15）
模板 11：完整功能实现
@技术栈相关文件 @现有类似功能文件
在 [项目/模块] 里实现 [功能名称]：
需求规格：
- [具体需求1]
- [具体需求2]
技术要求：
- 使用 [指定技术/库]
- 参考 @现有功能文件 的代码风格
- 错误处理：[具体要求]
约束：
- 不修改 [哪些文件/接口]
- 不引入新依赖（或只允许引入 [特定依赖]）
模板 12：API 端点实现
实现 API 端点：[HTTP方法] [路径]
请求：
- 认证：[需要/不需要] JWT
- Body：[字段和类型]
- 验证规则：[验证要求]
响应：
- 成功 [状态码]：[响应格式]
- 错误情况：[各种错误的处理]
数据库操作：[需要做什么 CRUD]
参考已有的端点实现风格。
模板 13：数据库模型设计
设计数据库模型，需要满足以下业务需求：
[业务需求描述]
要求：
- 主键类型：UUID / 自增整数
- 时间戳字段：createdAt, updatedAt
- 软删除：[是/否] deletedAt
- 关联关系：[描述实体间关系]
请给出：
1. 数据模型定义（用 [Prisma/SQLAlchemy/Go struct]）
2. 建议的索引（说明原因）
3. 需要注意的约束条件
模板 14：前端组件实现
实现 React 组件：[组件名]
功能：[组件做什么]
Props 接口：
- [prop名]: [类型] — [说明]
交互逻辑：
- [用户操作1] → [触发什么效果]
- [用户操作2] → [触发什么效果]
样式：用 Tailwind，参考 @现有组件文件 的风格。
不需要 Storybook，只需要主文件。
模板 15：工具函数实现
实现工具函数 [函数名]：
功能：[一句话描述]
输入：[参数及类型]
输出：[返回值类型和格式]
边界情况处理：
- 输入为空/null：[期望行为]
- 输入超出范围：[期望行为]
- 并发调用（如果适用）：[期望行为]
要求：纯函数，无副作用，包含 JSDoc 注释，同时给出单元测试。
第四类：代码重构（16-20）
模板 16：提取公共逻辑
@文件A @文件B @文件C
这几个文件都有类似的 [功能描述]，存在重复代码。
请：
1. 找出可以提取的公共逻辑
2. 设计一个合适的接口（参数、返回值）
3. 实现提取后的共享函数/模块
4. 修改现有调用方，展示改动后的代码
5. 说明是否需要修改测试
模板 17：重构大函数
@文件路径
这个函数超过 [N] 行，可读性差。在保持完全相同行为的前提下重构：
1. 识别可以提取的子逻辑块
2. 为每个子逻辑命名（命名要能自我说明意图）
3. 给出重构后的完整代码
4. 重构后外部接口必须完全不变
不要改变任何行为，只改结构。
模板 18：改善错误处理
@文件路径
这个模块的错误处理不完善。改进要求：
1. 所有可能抛出异常的地方要有 try/catch
2. 错误要有合适的日志记录（用 structlog/winston）
3. 面向用户的错误信息不暴露内部细节
4. 每类错误要有合适的 HTTP 状态码（如果是 API）
给出完整的重构后代码。
模板 19：添加 TypeScript 类型
@文件路径
这个 JS 文件需要迁移到 TypeScript。要求：
1. 为所有函数参数和返回值添加类型
2. 为所有对象添加接口定义
3. 不使用 any（除非真的没有其他办法，要加注释说明）
4. 使用 unknown + 类型守卫而不是 as 强转
给出完整的 TypeScript 版本。
模板 20：性能优化
@文件路径
分析性能问题并优化：
当前情况：[操作描述，数据量，耗时]
目标：[期望耗时]
检查方向：
- 是否有 N+1 查询
- 是否缺少必要的缓存
- 是否有不必要的循环或重复计算
- 是否可以并行处理串行操作
给出优化方案和预期效果。
第五类：测试（21-25）
模板 21：单元测试
@文件路径
为 [函数/类] 编写单元测试：
测试框架：[Jest/pytest/Go test]
要覆盖：
1. 正常路径（happy path）
2. 边界情况：[空输入、最大值、最小值等]
3. 错误情况：[各种可能的错误]
测试要真实有用，不要只测"函数被调用了"，要验证实际的输出和副作用。
模板 22：集成测试
@路由文件 @服务文件
为 [API路径] 编写集成测试：
- Mock 外部依赖（数据库/第三方 API）
- 覆盖成功场景和各种失败场景
- 验证响应格式、状态码、数据库状态变更
用 [Supertest/pytest/httptest] 实现。
模板 23：补充测试覆盖率
@文件路径 @测试文件路径
现有测试覆盖率不足。分析未覆盖的代码路径：
1. 哪些分支没有被测试
2. 哪些边界情况缺失
3. 哪些错误路径没有测试
给出补充测试用例，和现有测试文件风格保持一致。
模板 24：Mock 复杂依赖
@文件路径
这段代码依赖 [外部服务/数据库]，写测试时需要 mock。
实现：
1. Mock [依赖名称] 的方法：[方法列表]
2. 模拟成功返回的数据结构
3. 模拟各种失败情况（超时、权限不足、网络错误）
4. 展示如何在测试中使用这些 mock
模板 25：测试重构
@测试文件路径
这个测试文件有问题：[描述问题，如重复代码多、测试相互依赖、setup 太复杂]
重构目标：
1. 提取公共的 setup/teardown 逻辑
2. 每个测试应该独立，不依赖其他测试的副作用
3. 测试名称要能描述测试的意图
保持测试覆盖率不变，只改结构。
第六类：文档和工具（26-30）
模板 26：生成 API 文档
@路由文件
为这个 API 模块生成 OpenAPI/Swagger 文档：
- 每个端点的路径、方法、描述
- 请求参数和请求体的 Schema
- 响应格式（成功和错误）
- 认证要求
用 YAML 格式输出。
模板 27：代码注释
@文件路径
为这段代码添加注释：
- 复杂逻辑的 why（为什么这样做，不是做了什么）
- 公共函数的 JSDoc/docstring
- 非显而易见的数据结构说明
- 已知的边界情况和已知的技术债务
注释要有实际价值，不要写"这个函数返回用户列表"这种废话。
模板 28：生成 CHANGELOG
@Git
根据最近的 git 提交记录，生成 v[版本号] 的 CHANGELOG：
- 格式：## [版本] - [日期] / ### Added / ### Changed / ### Fixed
- 面向用户，不是面向开发者（不要列内部重构）
- 合并相关的小 commit 成一条
- 按重要性排序
模板 29：生成 README
@src/ @package.json @README.md（如果已有）
为这个项目生成完整的 README：
- 项目简介（一句话）
- 功能列表（用户视角）
- 快速开始（5分钟内跑起来所需的最少步骤）
- 环境变量说明（从 .env.example 或代码里提取）
- 开发指南（如何运行测试、如何贡献）
Markdown 格式，保持简洁，不要废话。
模板 30：生成 Makefile/脚本
为这个项目生成 Makefile，包含常用命令：
- make dev：启动开发环境
- make test：运行测试
- make lint：代码检查
- make build：生产构建
- make clean：清理构建产物
- make help：显示所有命令说明
参考 @package.json 里的 scripts，转化成 Make targets。
多轮对话节奏
好的 Prompt 工程不只是一次提问，而是有节奏的多轮对话：
- 第一轮：理解和确认——描述需求，让 AI 复述理解并确认方向
- 第二轮：生成草稿——基于确认的方向生成代码
- 第三轮：迭代细节——针对具体问题做精细调整
- 第四轮：验证和测试——让 AI 帮你想边界情况，生成测试
每轮保持专注，不要在一轮里解决所有问题。
本章要点
- Prompt 质量的关键不是措辞，是信息完整度：文件路径、具体错误、约束条件——缺一不可
- 30个模板覆盖6大场景：理解代码、修复 Bug、开发功能、重构、测试、文档——直接复制修改
- 多轮对话比单轮更有效：理解 → 草稿 → 迭代 → 验证，每轮聚焦一件事
- 约束条件和期望结果同样重要："不修改函数签名""不引入新依赖"这类约束要明确写出
- 给 AI 足够的上下文判断：不说清楚技术栈、框架版本、项目背景，AI 只能用通用假设