AI 编码代理的提示词工程实战指南

原创。提示词工程不是玄学，而是一套可复用的方法和技巧。本文分享让 AI 编码代理产出高质量代码的实战经验，每种模式都附有可直接使用的提示模板。

很多人用 AI 编码代理的方式是直接把需求扔进去："帮我写一个用户登录功能"。结果呢？AI 返回了一堆代码，能跑，但耦合度高、没错误处理、也不符合你的代码风格。不是 AI 不行，是你的提示方式太粗糙。

AI 编码代理跟人一样，需要理解你的意图、项目上下文和质量标准。区别在于，它不会反过来问你"你用的是 Vue 2 还是 Vue 3？"——它直接猜，大概率猜错。

好的提示词工程能消除这种不确定性。下面分享五种实战模式，每种都包含可以直接使用的模板。

模式一：角色+背景+任务+约束

这是最基础也最重要的提示结构，适用于绝大多数编程任务。四个要素缺一不可：

你是一名[角色]，正在[项目背景]。
任务：[具体要做什么]
约束：[技术限制、代码风格、框架版本等]

一个反例和一个正例的对比：

粗糙的提示： "帮我写一个导出 CSV 的功能"

结构化的提示： "你是一名 Python 后端开发者，我们正在用 FastAPI 构建一个数据分析 API。任务是为 /api/reports/export 端点添加 CSV 导出功能，支持按日期范围筛选数据。约束：使用 Python 3.11+、异步处理大文件（可能超过 100MB）、输出格式兼容 Excel 中文编码（UTF-8 BOM）、遵循项目已有的错误处理模式（自定义 Exception + 全局异常处理器）。"

同样让 AI 写代码，第二个提示得到的结果质量差距是巨大的。第一个提示的 AI 可能给你一个同步的 Flask 写法，跟你的 FastAPI 项目完全不搭。

模式二：示例驱动（Few-shot）

AI 擅长模仿模式。给它一个"对"的例子，它大概率能产出对的内容。这是最有效的控制输出质量的手段。

适用场景：

• 代码风格一致性要求高
• 需要遵循特定的设计模式
• 输出格式有严格要求

模板：

以下是项目中已有的 [XX 功能] 实现模式：

```python
# 已有代码示例

请按照完全相同的模式，实现 [新功能]。注意：变量命名风格、错误处理方式、注释格式都要跟示例保持一致。

比如在写 React 组件时，给它看一个现有组件的写法，它就能自动沿用同样的 hooks 调用方式、状态管理风格和 CSS 方案，不会突然跑偏到另一个模式。

模式三：分步拆解（Chain of Thought）

对于复杂任务，别指望 AI 一次搞定。把一个大问题拆成多个小步骤，逐步推进。

模板：

我们分三步来完成这个功能：

第一步：分析需求
- 列出这个功能涉及的所有数据模型和 API 端点
- 指出可能存在的边界情况和异常场景

第二步：设计方案
- 基于第一步的分析，给出三个可选的技术方案
- 每个方案列出优缺点和实现成本
- 推荐一个方案并说明理由

第三步：实现
- 按推荐的方案编写代码
- 每段代码附带注释说明做了什么和为什么这么做

这种模式的好处是：你可以在 AI 做完第一步后审阅结果，如果不满意就及时纠正，而不是等它写了 500 行代码才发现方向错了。

模式四：上下文锚定

AI 编码代理的最大短板是"记性差"——它在回答当前问题时可能已经忘了你十分钟前说过的话。需要主动给它锚定关键上下文。

模板：

提醒你几个关键的项目约束（请牢记）：
- 框架：Next.js 14 (App Router)，不是 Pages Router
- 数据库：Prisma + PostgreSQL
- 认证：NextAuth.js v5，使用 GitHub 和 Google 两个 Provider
- 样式：Tailwind CSS，项目使用 design system 中的预设颜色（primary: blue-600）
- 状态管理：React Query 用于服务端状态，zustand 用于客户端状态

基于以上约束，开始实现：[任务描述]

每次重要对话开始时都锚定一次上下文，能显著减少 AI 的"幻觉"——比如它不会突然塞给你一个你在用 Prisma 的项目里用 Mongoose 写的数据访问层。

模式五：审查清单

让 AI 完成后自行检查，比自己 review 一遍更高效。

模板：

代码写完后，按照以下清单自我审查：

性能检查：
- 有无不必要的重复计算
- 有无 N+1 查询问题
- 大文件/大数据集是否用了流式处理

安全检查：
- 用户输入是否经过验证和消毒
- SQL 是否使用参数化查询（预防注入）
- 敏感信息有无硬编码

维护性检查：
- 是否有魔法数字需要提取为常量
- 函数是否遵循单一职责原则
- 错误信息是否有足够的上下文

代码风格检查：
- 命名是否符合项目约定
- 注释是否有价值（不说"显而易见"的事）
- 有无已废弃的 API 调用

请以清单形式输出审查结果，标记每条是 ✅ 通过还是 ❌ 有问题，有问题的需要说明修改方案。

组合使用

五种模式不是孤立的，可以灵活组合。一个高级的工作流示例：

1. 用上下文锚定告诉 AI 项目的技术栈和规范
2. 用分步拆解让 AI 先分析再做
3. 分析阶段用示例驱动确保方案方向正确
4. 实现阶段用角色+背景+任务+约束保证代码质量
5. 完成后用审查清单让 AI 自己查漏补缺

这听起来步骤多，但实际操作起来每次只需要多花 30 秒写提示词，就能把 AI 的输出质量从"能用"提升到"可直接合并"的水平。

常见误区

误区一：提示词越长越好 不是。关键是信息密度，不是长度。"遵守项目约定"五个字比五百字的泛泛要求更有用。

误区二：一次说完所有需求 AI 在生成长代码时，后面的约束可能会被前面的内容稀释。关键约束在实现前再强调一次。

误区三：不检查直接合并 即使是特别好的提示词产生的代码，也应该 review。AI 擅长局部正确，整体架构的一致性需要人来把关。

误区四：永远用一个提示模板 不同的任务类型需要不同的提示结构。写新功能、修 bug、重构代码、写测试——每种任务的提示策略都应该有所区别。

写在最后

提示词工程不是魔法，它本质上是一种沟通技巧。你跟 AI 沟通得越清晰、越结构化，它就能产出更好的结果。花在写提示词上的时间，会在 review 和修复阶段十倍地赚回来。

以上技巧适用于主流的 AI 编码代理——Claude Code、Cursor、GitHub Copilot、Windsurf、Aider 等。底层逻辑都是相通的：AI 需要知道你是谁、你要什么、怎么做、什么不能做。把这些交代清楚，它就能成为你最好的编程搭档。

快速参考：任务类型与提示模板对照

为了方便日常使用，这里提供一个快速对照表，不同任务类型直接选用对应的提示策略：

把这张表保存到你的笔记里或者放在 CLAUDE.md 中，每次开始新任务时快速选一个模板，30 秒就能写出一个有效的提示。