一套模板，让 AI 写出高质量代码

大家好，我是小悟。

一、详细描述

代码生成 Prompt 是指向 AI 模型（如 ChatGPT、Claude、Copilot 等）发出的、用于指导其生成特定代码的指令文本。一个高质量的 Prompt 能够显著提升生成代码的准确性、可读性、健壮性和可维护性。

然而，许多开发者在使用 AI 生成代码时，常常遇到以下问题：

• 生成的代码逻辑错误或不符合需求
• 代码风格混乱，缺乏注释
• 没有错误处理或边界条件考虑
• 依赖过时或错误的技术栈

这些问题往往不是 AI 能力不足，而是 Prompt 质量不高所致。一个高质量的代码生成 Prompt 应该像一个清晰的技术规格说明书，让 AI 能够准确理解你的意图、约束和质量要求。

高质量 Prompt 的核心要素

二、详细步骤

步骤 1：明确需求 —— 回答五个核心问题

在写 Prompt 之前，先用 5W1H 方法梳理需求：

1. What：要实现什么功能？（算法、接口、组件、脚本？）
2. Why：为什么需要这段代码？（帮 AI 理解上下文）
3. Who：谁会使用/维护？（影响代码可读性要求）
4. Where：运行环境是什么？（浏览器、Node、嵌入式？）
5. How：性能、安全、可靠性指标是什么？

示例：

“实现一个从 10 万条订单记录中快速查找某用户最近 30 天订单总额的函数，用于后台报表展示，需支持并发调用。”

步骤 2：构建 Prompt 结构 —— 使用“金字塔写作法”

采用从宏观到微观的结构：

[角色] + [核心任务] + [技术栈] + [详细约束] + [输入输出规格] + [边界/异常] + [输出格式] + [示例]

模板：

## 角色
你是一名精通 [语言/框架] 的高级工程师。

## 任务
[一句话描述核心功能]

## 技术约束
- 语言/版本：[如 Python 3.11]
- 框架：[如 FastAPI 0.100+]
- 依赖限制：[如 不引入第三方库]

## 输入规格
- 参数1：类型，含义，约束
- 参数2：类型，含义，约束

## 输出规格
- 成功返回：[类型和内容]
- 失败返回：[错误类型和格式]

## 必须处理的情况
- [ ] 边界条件1（如 空输入）
- [ ] 异常情况2（如 网络超时）
- [ ] 性能要求（如 时间复杂度 O(n log n)）

## 代码风格要求
- 添加完整类型注解（Type Hints）
- 添加 docstring（格式遵循 Google/NumPy 风格）
- 关键逻辑添加行内注释
- 错误处理使用 [try/catch 或 Result 类型]

## 示例（可选）
输入：[具体值] → 期望输出：[具体值]

## 输出格式要求
请只输出代码块，不要额外解释。代码块内包含必要的 import 语句。

步骤 3：逐步细化 —— 从粗略到精确

不要试图一次性写出完美 Prompt。采用迭代式方法：

1. 第 1 轮：写一个简单 Prompt，看 AI 输出
2. 第 2 轮：根据输出中的不足，补充细节
3. 第 3 轮：增加边界条件和性能要求
4. 第 4 轮：要求添加测试用例或文档

示例迭代过程：

❌ 第 1 版（太简单）：“写一个排序函数” → 输出：冒泡排序，无类型，无错误处理 ⚠️ 第 2 版（稍好）：“用 Python 写一个稳定的排序函数，输入是整数列表” → 输出：归并排序，但无空值处理 ✅ 第 3 版（高质量）： “用 Python 3.11 写一个泛型排序函数 stable_sort[T](items: list[T], key: Optional[Callable] = None) -> list[T]。要求：1) 稳定排序，2) 时间复杂度 O(n log n)，3) 输入为 None 时返回空列表，4) 支持自定义 key 函数，5) 添加完整类型注解和 docstring。”

步骤 4：加入约束和陷阱提醒

AI 不知道你不知道的事。明确告诉它不要做什么和要小心什么。

常见约束模板：

• “不要使用 eval() 或 exec()”
• “避免递归深度超过 1000”
• “不使用全局变量”
• “确保线程安全”
• “不要打印调试信息到标准输出”
• “兼容 Python 3.8+”

示例：

“实现一个缓存装饰器。注意：1) 不要使用 functools.lru_cache（我要手写实现），2) 缓存容量限制为 1000 条，3) 使用 LRU 淘汰策略，4) 必须支持线程安全。”

步骤 5：要求附带测试用例

高质量代码离不开测试。要求 AI 同时生成测试代码：

Prompt 片段：

“除了实现上述函数外，请额外输出使用 pytest 编写的测试用例，覆盖：正常情况、空输入、边界值（最小值/最大值）、异常输入（错误类型）。”

步骤 6：指定输出格式 —— 避免废话

默认情况下 AI 会附带解释文字。如果只需要代码，明确说明：

请只输出代码块，使用 ```python ... ``` 格式。不要输出任何解释文字，不要输出“以下是代码”之类的话。

如果允许少量说明，可以规定结构：

输出格式：
1. 简要说明（1-2 句话）
2. 代码块
3. 使用示例（可选）

步骤 7：使用“少样本提示”（Few-shot Prompting）

提供一个具体的输入输出示例，能大幅提升生成准确率：

示例：
输入：get_average([10, 20, None, 30])
输出：20.0 （忽略 None，取非空值的平均）

请实现这个函数，遵循上述示例的行为。

步骤 8：要求自我解释或合理性检查

让 AI 在生成代码前先思考，能减少错误：

在输出代码之前，请先简要列出你的实现思路（不超过 3 点），然后根据这个思路生成代码。

或者：

请先分析这个函数可能遇到的 3 个边界情况，并在代码中处理它们。

三、详细总结

核心原则

高质量 Prompt 通用模板

## 角色
你是一名 [领域] 的资深工程师，代码风格 [简洁/规范/企业级]。

## 任务
用 [语言/框架] 实现 [功能描述]。

## 输入
- 参数名: 类型，取值范围，是否可为空

## 输出
- 成功时: 类型和结构
- 失败时: 错误处理方式（抛异常 / 返回 None / 返回错误码）

## 约束与要求
- 时间复杂度: O(?)
- 空间复杂度: O(?)
- 必须处理的边缘情况: [列出 3~5 项]
- 禁止使用: [列出不允许的函数或模式]
- 依赖: [允许/禁止的第三方库]

## 代码质量要求
- [ ] 完整的类型注解
- [ ] docstring（描述功能、参数、返回值、异常）
- [ ] 关键逻辑注释
- [ ] 错误处理（针对 I/O、网络、类型错误等）

## 输出格式
只输出代码块，语言标识符为 [python/java/js/...]。
如果需要测试代码，请放在单独的代码块中并标注 `test_xxx`。

## 示例（可选）
输入: [具体值] → 输出: [具体值]

常见错误及改进对照表

最后

1. 把 AI 当成初级工程师来指导——你交代得越清楚，它返工越少。
2. 保留好用的 Prompt 模板——同一类任务（如写 API、写算法、写脚本）可以复用。
3. 多轮对话优于单轮长 Prompt：先确认需求 → 再生成代码 → 最后要求优化/加测试。
4. 对生成的代码始终保持审查——AI 可以生成 80 分的代码，但 100 分需要人来把关。

通过系统化地编写高质量 Prompt，可以在日常开发中将 AI 代码生成的成功率大大提高，真正把 AI 变成得力的编程伙伴。

谢谢你看我的文章，既然看到这里了，如果觉得不错，随手点个赞、转发、在看三连吧，感谢感谢。那我们，下次再见。

您的一键三连，是我更新的最大动力，谢谢

山水有相逢，来日皆可期，谢谢阅读，我们再会

我手中的金箍棒，上能通天，下能探海