提示词实战案例库:从分析到交付的完整配方
如何使用这个案例库
| 场景 | 推荐框架 | 单轮/多轮 | 复杂度 | 配方编号 |
|---|---|---|---|---|
| 接手陌生代码库 | 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。
选读建议:案例库看完了,如果想把模板沉淀为团队资产——→ 模板库 章节。如果想回到方法论层面复习——→ 高质量任务描述模板 和 验收标准。