提示词实战案例库:从分析到交付的完整配方

如何使用这个案例库

场景推荐框架单轮/多轮复杂度配方编号
接手陌生代码库CRISPE多轮#1
带复现步骤的 Bug 修复六要素(精简版)单轮#2
新功能(含测试 + 文档)六要素(完整版)多轮#3
安全的依赖升级六要素 + 约束单轮#4
基于截图的 UI 原型六要素 + 图片多轮#5
多文件重构六要素 + 委派多轮#6
说明

建议先通读索引,遇到对应场景时再回来复制模板。每个配方都是完整的——可以直接复制到 Codex 中,替换 [] 中的占位符即可使用。

案例 1:接手陌生代码库的只读分析

场景:你刚加入一个项目,需要在 1 小时内理解核心模块的结构和数据流。

第 1 轮:全局扫描

只读分析,不要改任何代码。

分析 src/features/checkout/ 的完整结构,输出:
1. 目录结构和各文件职责(表格形式)
2. 入口路由和页面组件
3. 核心数据流(从用户操作到 API 调用)
4. 依赖的外部服务和内部模块
5. 你注意到的潜在问题或代码异味

优先看 index.ts / page.tsx / route.ts 类型的入口文件,再追踪依赖链。

上下文配置:@src/features/checkout/ 整个目录。

第 2 轮:深入关键模块

基于刚才的分析,深入分析 [关键模块名] 的实现细节:
1. 核心函数/类的职责和调用关系
2. 状态管理方式
3. 错误处理策略
4. 和其他模块的耦合点

输出一份技术分析报告,供后续重构参考。

验证方法:Codex 输出的文件清单和数据流图,和你自己读代码后的理解一致。

警告

只读分析一定要在提示词中明确说"不要改代码"。 否则 Codex 可能"好心"帮你重命名变量或调整格式。

案例 2:带复现步骤的 Bug 修复

场景:线上报了一个 Bug,有明确的复现步骤。

目标:修复 [Bug 简述],使 [期望行为]。

复现步骤:
1. 打开 [页面/路由]
2. 执行 [操作]
3. 观察到 [实际行为]
4. 期望行为:[期望行为]

范围:
- 涉及:[文件路径]
- 不涉及:[排除范围]

验证:
- 按上述复现步骤操作,不再触发问题
- `pnpm test -- --filter=[相关模块]` 全部通过
- 边界条件 [具体描述] 表现正确
- 不引入新的 lint 警告

请先分析根因,确认后再修复。

上下文配置:@涉及的文件路径,如果有错误日志也一并提供。

交叉引用:关于 Bug 修复的完整工作流,参见 工作流

案例 3:新功能开发(含测试和文档)

场景:开发一个新功能,需要代码 + 测试 + 文档一起交付。这个案例用 3 轮协作完成。

第 1 轮:设计 + 实现

目标:在用户设置页新增"通知偏好"表单。

背景:当前用户只能全局开关通知,产品要求支持按类型独立配置(email / push / inApp)。

范围:
- 新建:apps/src/features/settings/components/NotificationPreferences.tsx
- 新建:apps/src/features/settings/api/notification.ts
- 不改:全局通知组件

约束:使用 @packages/ui 的 Switch 组件,移动端优先。

先输出实现方案,确认后写代码。

第 2 轮:补测试(同一线程)

代码确认。现在补测试:
1. 单元测试覆盖开关切换逻辑
2. 边界条件:并发切换、网络失败回滚
3. `pnpm test -- --filter=settings` 全部通过

第 3 轮:补文档(同一线程)

测试通过。最后补文档:
1. 在 apps/src/features/settings/README.md 中补充通知偏好组件的使用说明
2. 如果项目有 API 文档,补充新增的 API 接口说明
3. 列出所有改动文件的摘要

案例 4:安全的依赖升级

场景:升级一个核心依赖,需要确保安全。

目标:将 [依赖名] 从 [当前版本] 升级到 [目标版本]。

约束(按优先级排序):
1. 不引入 breaking change 导致的编译错误
2. 现有测试全部通过
3. 如果有 deprecated API,替换为新 API
4. 升级前先 git stash 保存当前状态

范围:
- 改:package.json 中的版本号
- 改:因版本变化需要适配的代码
- 不改:其他依赖

验证:
- `pnpm install` 无错误
- `pnpm typecheck` 无错误
- `pnpm test` 全部通过
- `pnpm lint` 无新增 warning

如果升级过程中遇到 breaking change,先列出来让我确认,不要自行绕过。
警告

永远先 git stash / commit 再让 Codex 改依赖。 依赖升级有不确定性,确保你能回滚。

案例 5:基于截图的 UI 原型

场景:你有一张设计稿截图,需要 Codex 实现对应的 UI。

第 1 轮:分析设计稿

[附上截图]

分析这张设计稿,输出:
1. 页面布局结构(用组件树描述)
2. 需要的交互元素(按钮、输入框、下拉菜单等)
3. 响应式断点考虑
4. 可能用到的现有组件(参考 @packages/ui/)

不要写代码,先确认分析结果。

第 2 轮:实现 UI(同一线程)

分析正确。实现这个 UI:
1. 使用 @packages/ui 中的现有组件
2. 移动端优先,在 375px / 768px / 1440px 三个断点验证
3. 先用 placeholder 数据

验证:启动 dev server,截图对比设计稿。

交叉引用:基于截图做原型的完整工作流,参见 工作流

案例 6:多文件重构(本地规划 → 云端执行)

场景:需要重构一个涉及 10+ 文件的大模块,方向明确,耗时较长。

第 1 步:本地规划

/plan 将 src/services/payment/ 从 callback 模式重构为 async/await 模式。

要求:
1. 列出所有涉及的文件和改动点
2. 标注风险点(可能有副作用的地方)
3. 确保公共 API 不变
4. 估计改动量

先输出计划,确认后再执行。

第 2 步:确认计划后,委派到云端

计划确认后,在 Codex App 中点击"发送到云端",或在 CLI 中使用委派命令。云端线程会基于你的计划独立执行。

第 3 步:本地审查收尾

云端完成后,切回本地审查:

云端重构已完成。请帮我审查:
1. 列出所有改动文件和 diff 摘要
2. 运行 `pnpm test` 确认测试通过
3. 运行 `pnpm typecheck` 确认类型正确
4. 标注你不确定是否正确的改动点

交叉引用:关于委派式协作的详细说明,参见 多轮协作技巧

从案例中提炼你自己的配方

步骤操作
1. 识别高频场景哪些任务你经常交给 Codex?(Bug 修复?功能开发?代码审查?)
2. 抽取共性字段这些任务的提示词中,哪些字段是每次都写的?(目标?范围?验证?)
3. 模板化把共性字段抽象成模板,用 [] 标记变量部分
4. 团队评审让团队成员试用模板,收集反馈
5. 版本化管理把模板放到 templates/ 目录或项目文档中,跟踪变更
说明

提示词是一等工件。 值得像代码一样版本化管控——记录谁改了什么、为什么改、改后效果如何。当你的配方库积累到 10+ 个模板时,团队效率会有明显提升。

交叉引用:关于提示词模板化管理的更多思路,参见 模板库 章节。

验证清单

  • 你的高频场景都有对应的提示词模板
  • 模板中的变量部分用 [] 明确标记
  • 每个模板都有验证字段
  • 模板存放在团队可访问的位置
  • 定期根据实际使用效果迭代模板

FAQ

Q:这些配方适用于所有 AI 编码工具吗?

核心思路通用,但具体语法(@mention、/plan、/goal)是 Codex 特有的。如果你用其他工具,把语法替换成对应工具的方式即可——结构化的任务描述和验收标准是通用的。

Q:团队怎么共享和迭代配方?

建议把模板放到项目仓库中(如 docs/templates/prompts/),和代码一起版本化管理。每次迭代模板时,写清楚改了什么、为什么改。

Q:配方需要经常更新吗?

当以下情况发生时,需要更新配方:Codex 的能力升级了(比如支持了新工具)、项目架构变化了(比如新增了一个核心模块)、或者你发现某个字段的效果不好。建议每季度审查一次高频配方。

说明

平台能力、套餐限制以 OpenAI Codex 官方文档为准;本文写于 2026-06-24。

选读建议:案例库看完了,如果想把模板沉淀为团队资产——→ 模板库 章节。如果想回到方法论层面复习——→ 高质量任务描述模板验收标准