结构化提示词工程模式
产生一致、可审查代码的可复用提示词模式：角色、上下文、约束、输出格式。
提示词工程进阶
为什么
GitHub 2024 调查发现 92% 的美国受访者用 AI 编程工具生成测试用例，73% 的开源受访者用 AI 工具编程或写文档。临时提示词产生不一致的输出。
结构化模式（角色 + 上下文 + 约束 + 格式 + 示例）使输出足够确定以供审查和迭代。这是'偶尔好'与'可靠好'的 AI 代码之间的差别，并让你能将提示词与代码一起版本化。
何时使用
在以下情况使用结构化提示词：重复同类 AI 任务（写单元测试、加 REST 路由）；多个队友使用 AI 且希望一致输出；或 AI 输出必须匹配严格格式（JSON schema、特定文件模板）。一次性探索性问题可跳过。
如何做
1. 选择模式。五块模式适用于大多数代码任务：
[角色] [上下文] [约束] [输出格式] [示例]
2. 角色：AI 扮演谁。要具体。
"你是一名资深 TypeScript 工程师，编写严格、null 安全的代码。"
3. 上下文：仅提供所需内容，带文件引用。
"项目：Astro 7 + zod。相关文件：@src/api/router.ts @src/data/books.ts"
4. 约束：输出必须遵守的硬规则。
- 仅使用命名导出。
- 用 zod 验证所有输入。
- 不添加新依赖。
- 匹配 router.ts 中现有错误处理模式。
5. 输出格式：你想要的确切形状。
"仅返回新文件内容，无 markdown 围栏，无解释。"
6. 示例：一两对输入/输出（few-shot）。这是杠杆最高的块。
粘贴一个已知良好的路由处理器并说"遵循此形状"。
7. 将提示词存为可复用文件（prompts/add-route.md）并纳入 git 版本。
输出漂移时迭代；像对待代码一样审查提示词。
示例
可复用提示词文件：prompts/add-route.md
## 角色
你是一名 Astro 7 + zod 项目的资深 TypeScript 工程师。
## 上下文
- 路由：@src/api/router.ts（Hono 风格处理器）
- 数据层：@src/data/books.ts（Books 表 CRUD）
- 需对照的现有路由：@src/api/routes/health.ts
## 约束
- 用 zod schema 验证请求体；推断类型。
- 创建返回 201，验证错误返回 400，DB 错误返回 500。
- 仅命名导出；不添加新依赖。
## 输出格式
单个 TS 文件，无 markdown 围栏，无散文。
## 示例
（此处粘贴 health.ts 内容作为需遵循的形状）
在 Cursor 中使用：@prompts/add-route.md "添加 POST /api/books"
常见问题
- ⚠错误：模型返回 "I cannot help with that" → 改写去除受限措辞；收窄范围并提供明确的允许示例。
- ⚠模型输出 JSON 解析错误 → 用 ```json 围栏包裹并在系统提示加 "仅返回合法 JSON"。
- ⚠错误：超出 token 限制（400 Bad Request） → 拆分提示、摘要前文或切换更大上下文模型。
- ⚠错误：模型返回 "I cannot help with that" → 改写去除受限措辞；收窄范围并提供明确的允许示例。
最佳实践
- ✓提示词保持在约 2000 token 以内。过长会稀释对实际任务的注意力。
- ✓将约束写为否定要点（'不添加依赖'）— 显式时模型更易遵循否定。
- ✓在 git 中版本化提示词，并在 PR 中像代码一样审查提示词 diff。
- ✓对同一任务 A/B 测试提示词变体；保留审查修正更少的那版。
- ✓全团队对每类任务复用一个规范提示词，保证一致输出。
常见问题解答
什么是五块提示词模式？
角色 + 上下文 + 约束 + 输出格式 + 示例。角色设专长、上下文限定文件、约束设硬规则、格式定形状、示例（few-shot）锚定。合起来使输出足够确定以供审查。
为什么提示词需要 few-shot 示例？
零样本提示词跨模型版本漂移，产生不一致形状。一个输入/输出示例锚定你想要的确切格式，是杠杆最高的块。没有它，同一提示词不同天可能产生不同结构。
结构化提示词该多长？
保持在约 2000 token 以内。上下文过载（粘贴 10 文件）会稀释对实际任务的注意力。仅含输出依赖的文件加一个示例。过长提示词成本更高且表现更差。
应该在 git 中版本化提示词吗？
应该。将可复用提示词存为文件（如 prompts/add-route.md）并提交。在 PR 中像代码一样审查提示词 diff，对同一任务 A/B 测试变体。聊天历史中的未版本化提示词会丢失，团队无法迭代。
如何阻止 AI 用 markdown 围栏包裹代码？
加显式输出格式块：'仅返回新文件内容，无 markdown 围栏，无解释。'没有它，模型默认用围栏包裹代码并加需手动剥离的散文。