Appearance
Prompt Engineering for Code：编程场景的提示词方法论
最后更新：2026-08-11
Prompt Engineering（提示词工程）在编程场景下有一个独特的特点：你是在指挥一个动作系统，而不是问答系统。你不是在问"这段代码对不对"，而是在说"帮我做成这件事"。
一、编程 Prompt 与其他场景的本质区别
| 维度 | 通用 Prompt | 编程 Prompt |
|---|---|---|
| 目标 | 获取正确答案 | 产生正确且可运行的代码 |
| 上下文 | 问题本身即可 | 需要项目结构、技术栈、编码规范 |
| 验证 | 人工判断对错 | 编译通过、测试通过、lint 通过 |
| 副作用 | 无 | 文件修改、命令执行 |
| 失败后果 | 再问一次 | 代码被改坏、构建失败、生产事故 |
编程 Prompt 的核心难题不是"怎么写得让 AI 理解"，而是**"怎么写得让 AI 产生可验证的正确输出"**。
二、编程 Prompt 的三要素框架
好的编程 Prompt 包含三个要素，缺一个就可能跑偏：
2.1 Context（上下文）—— 告诉 AI "我们在哪"
❌ "帮我加个登录功能"
✅ "在 @src/auth/ 下，用已有的 JWT 验证中间件，
新增一个 POST /auth/refresh 路由，
输入 refreshToken，输出新的 accessToken + refreshToken"上下文清单：
| 你要告诉 AI 的 | 例子 |
|---|---|
| 文件位置 | @src/services/user.ts |
| 技术栈版本 | "Express 4.19 + TypeScript 5.5" |
| 已有基础设施 | "已有 authMiddleware，validateBody 中间件" |
| 数据模型 | "User 模型有 id, email, passwordHash, refreshToken 字段" |
2.2 Task（任务）—— 精确到行为层面
❌ "重构用户模块" ← AI 不知道"重构"是什么意思
❌ "优化这段代码" ← AI 看不懂"优化"的标准
✅ "把 UserController 的 3 个方法提取到 UserService，
保留 Controller 的 HTTP 层逻辑"
✅ "把 for 循环改成 Array.map，不改变逻辑"任务描述公式：
对
[哪个文件/模块]，执行[什么操作]，输入[什么]，输出[什么]，[什么标准算成功]。
2.3 Constraint（约束）—— 画好边界线
✅ "不要改 User 模型的字段名"
✅ "不要引入新的 npm 包"
✅ "保持和 authMiddleware 的调用方式一致"
✅ "新的路由前缀也是 /api/v1"三、三大场景的策略差异
场景 1：写新代码（Write Code）
核心矛盾：AI 不知道你项目中的"局部风格"，倾向于写"主流写法"。
策略：先喂约束，再让写
# 一阶段：让 AI 理解你的约束
"看 @src/api/users/ 下的代码，总结以下约定：
路由注册方式、错误处理方式、输入验证方式"
# 二阶段：写新代码
"按照你总结的约定，在 @src/api/products/ 下创建 CRUD 路由"写作模板：
在 [目录/文件] 中创建 [功能名]。
参考 [已有代码] 的风格和模式。
输入: [参数/请求体格式]
输出: [响应格式]
不引入新的 [依赖/模式/库]。场景 2：阅读与理解代码（Read Code）
核心矛盾：AI 一次能读的内容有限，大项目需要分步探索。
策略：先广度后深度，先结构后细节
# 第一轮：广度扫描
"梳理 src/ 下的目录结构，画出模块依赖图"
"列出所有对外暴露的 API 路由"
# 第二轮：特定模块深入
"解释 @src/auth/login.ts 的完整流程"
"这个中间件链的顺序为什么重要？"
# 第三轮：细节追问
"refreshToken 为什么不是存数据库而是存在内存？"写作模板：
先全局：[梳理/列出] [项目/模块] 的 [结构/入口/依赖]
再局部：[解释/追踪] [具体文件/函数] 的 [完整流程]
最后问：[为什么/有什么问题/怎么改进]场景 3：重构代码（Refactor）
核心矛盾：重构最容易"改出bug"，AI 改完后看似对了实际逻辑变了。
策略：小步改，每步验证
# ❌ 一步到位（容易出错）
"把 User 模块重构为 Clean Architecture"
# ✅ 小步迭代
"第一步：把 UserController 的数据库查询逻辑提取到 UserRepository，
不改变任何行为，改完后跑 npm test -- -t 'user'"
"第二步：确认上一步通过后，
把 UserRepository 改为依赖注入，通过构造函数传入"写作模板：
第一步：[小范围改动]，不改变行为，验证: [跑什么测试]
第二步：确认通过后，[下一步改动]，验证: [跑什么测试]
...四、反例集：这些 Prompt 会翻车
4.1 太模糊
| 你说的话 | AI 的理解范围 | 实际需要的 |
|---|---|---|
| "加个缓存" | 可能用 Redis / Memcached / 文件 / 内存 | "在 @src/middleware/cache.ts 中加内存 LRU 缓存，key 是请求 path" |
| "优化性能" | 可能改算法 / 加缓存 / 改数据库索引 / 用 CDN | "把 for 循环的 O(n²) 改成 O(n) 用 Map" |
| "改成微服务" | 完全不知道从哪下手 | "把 @src/payment/ 模块拆成独立 Express 服务，通过 HTTP 通信" |
4.2 缺少验证标准
❌ "重构 auth 模块，保持功能不变"
→ AI 改完，测试全挂，但 AI 已经"完成"了
✅ "重构 auth 模块：
1. 不改 User 模型的字段名
2. 不改 API 返回格式
3. npm test -- -t 'auth' 全部通过
4. npm run lint 零报错"4.3 上下文污染
❌ 在同一个对话中：
"帮我搭建 Express 项目"
"写用户注册逻辑"
"换个思路，用 Fastify 重写吧"
→ AI 混淆了 Express 和 Fastify 的 API
✅ /clear 清空历史，重新开始 Fastify 相关任务
或者用 /compact 压缩后明确说：
"以下全部基于 Fastify，忽略之前的 Express 建议"4.4 让 AI 做价值判断
❌ "这个设计好不好？" ← AI 没有审美
❌ "有什么更好的方案？" ← AI 会给出"看起来高级"但不符合你场景的方案
❌ "怎么优化这个函数？" ← AI 不知道"优化"的维度（速度/内存/可读性？）
✅ "这个函数每次调用分配了 3 次临时字符串，怎么减少分配？"
✅ "不考虑可读性，只考虑执行速度，这个排序有没有更快的方法？"
✅ "在保持接口签名不变的前提下，怎么改内部实现？"五、进阶技巧
5.1 让 AI 先出计划再执行
# 对复杂任务非常有效
"先不要改代码，给我一个重构 User 模块的方案，分步骤，
每步预期改哪些文件，改完怎么验证。"
# AI 出计划后你审阅，确认再执行
"方案 OK，按你的计划一步步执行，每一步跑测试确认"5.2 用"反例"画边界
"添加一个 POST /login 路由。
不是 OAuth，不是 SSO，就是普通的邮箱+密码登录。
不要改 User 表的结构，不要引入 passport 库。"5.3 管道模式：一次对话做好一件事
对话1: "梳理 src/auth/ 的结构" → /clear
对话2: "重构 login.ts 的验证逻辑" → /clear
对话3: "给 auth 模块加单元测试" → /clear5.4 参考文件模式
"用和 @src/api/users/create.ts 相同的结构，创建 createProduct.ts，
但字段改成 name, price, category。"5.5 错误反馈模式
"刚才改的代码编译报错：
TypeError: Cannot read property 'id' of undefined
at UserController.login (src/auth/login.ts:42)
请根据这个错误修复，不要改整体逻辑。"六、量化：好 Prompt 节省的时间
| Prompt 质量 | 迭代次数 | 总耗时 | 说明 |
|---|---|---|---|
| "加个登录" | 5-8 轮 | 15-30 min | AI 反复猜，你反复纠正 |
| "在 src/auth/ 下用 JWT 加邮箱密码登录" | 2-3 轮 | 5-10 min | 大方向对了，细节需要微调 |
| 三要素完整 + 参考文件 + 验证标准 | 1 轮 | 2-5 min | 一次通过或微小调整 |
写 Prompt 多花 30 秒，后面少花 10 分钟纠正。这 30 秒的投资回报率是 20:1。
七、和本仓库其他文档的关系
| 文档 | 内容 | 与本文的关系 |
|---|---|---|
| CLAUDE.md 编写指南 | 持久化的项目记忆 | CLAUDE.md 是"写一次管所有的 prompt"，本文是"每次对话必写的 prompt" |
| Agent vs Skill 解析 | Agent 和 Skill 的触发机制 | Prompt 是触发 Agent/Skill 的入口，description 字段本质是 prompt 匹配器 |
| Claude Code CLI 教程 | Claude Code 的使用方法 | 本文是"怎么说"，那里是"在哪说" |
| AI 编程工具效率量化 | 实际效率数据 | 好的 Prompt 直接体现在效率数字上 |
一句话总结
编程 Prompt 不是在问问题，是在下指令：Context 告诉 AI"我们在哪"，Task 告诉它"干什么"，Constraint 告诉它"不能干什么"——三要素越完整，AI 跑偏的概率越低。写 Prompt 多花 30 秒，后面少纠正 10 分钟。