AI 编程提示词指南：让 Codex 和 Claude 少改错、少返工

好指令的三个要素

把 AI 当成一个刚加入项目、能力不错但不了解背景的同事。它需要知道目标、边界和验收标准，而不是一句“帮我优化一下”。

• 目标：要解决的具体问题，例如“修复登录页在移动端点击无响应”。
• 边界：允许改哪些文件、不能改哪些约定、是否允许加依赖。
• 验证：改完必须跑什么命令、达到什么结果才算完成。

先把项目上下文喂给它

在仓库根目录放一份 AGENTS.md（或团队约定的同类文件），写清技术栈、目录结构、常用命令和禁止事项。多数编程工具会在开始时读取它，比每次对话重复解释更可靠。

# 项目约定

- 技术栈：Next.js App Router + TypeScript + Cloudflare Workers
- 包管理器：npm；不要引入新的 UI 依赖
- 提交前必须通过：npm run typecheck && npm run lint && npm test
- 不要修改 migrations/ 下已应用的历史迁移
- 组件默认使用服务端组件；需要交互时再加 "use client"
- 所有面向用户的文案使用中文，不要出现未翻译的占位符

除了 AGENTS.md，把相关文件路径直接写进指令也很有用。让 AI 自己全仓库搜索，容易把无关模块一起改掉，尤其是命名相似的项目。

五个常用提示词模板

下面模板可以直接改写使用。注意模板里的“不要”比“要”更重要：明确禁止事项，能显著减少顺手重构和无关格式化。

在 src/lib/pricing.ts 和 tests/pricing.test.ts 范围内修复：优惠码叠加时总价被重复打折。
要求：
1. 先复现问题并写出失败测试；
2. 只改这两个文件，不改数据库结构和 API 形状；
3. 修复后运行 npm test -- pricing，并贴出结果；
4. 说明根因和为什么这样改。

为订单查询页增加“按邮箱搜索”功能。
范围：app/orders/page.tsx、src/lib/orders.ts、tests/order-history-ui.test.ts。
约束：复用现有查询参数风格，不新增依赖，不改 URL 结构。
验收：输入邮箱能过滤列表；无结果时有空状态；已有测试全部通过。
先给计划，等我确认后再改代码。

把 ProductCard 里的价格格式化逻辑抽成 src/lib/pricing.ts 的纯函数。
要求：行为不变、导出名清晰、补单元测试；不调整组件样式和 DOM 结构；改完运行 typecheck 和 test。

阅读 src/lib/refunds.ts，为退款状态机补测试。
覆盖：正常退款、重复退款、金额为 0、Stripe 返回失败、并发重复请求。
只新增测试文件，不改实现；如果发现实现 bug，先报告不要直接修。

用 10 行以内说明 src/lib/upgrade.ts 的职责、入口函数和失败路径；
再列出三个最容易被误用的地方，并给出文件:行号。
不要改任何文件。

让改动可审查：小步、diff、测试

• 一次只做一件事。修 bug 的对话里不要顺手重命名变量或升级依赖。
• 要求 AI 在改完后总结 diff：改了哪些文件、每个文件为什么改。
• 要求它运行测试并贴出真实输出，不要只说“测试通过”。
• 对 UI 改动要求截图或本地验证步骤；只看代码容易漏掉布局问题。
• 大改动拆成多个小提交，每个提交都能独立回滚。

模型和工具怎么选

Codex CLI 更贴近终端工作流，适合在仓库里读文件、改代码、跑命令；Claude 系列在长上下文和代码解释上常被用于 IDE 插件或对话式开发。两者没有绝对优劣，取决于你的工具链和任务类型。

• 需要它直接操作仓库、执行测试：选支持工具调用的 CLI/IDE 代理。
• 需要讨论方案、读大段代码：选长上下文表现稳定的模型。
• 涉及公司代码：先确认数据使用政策，必要时走本地或私有部署。
• 不要把生产密钥、客户数据粘贴到未获批准的第三方工具里。

常见误区

• “帮我优化代码”——没有目标，AI 只能按通用审美乱改。
• 一次贴上整个仓库——上下文越杂，越容易改错模块。
• 不设边界——AI 会顺手重构、升级依赖，diff 变得无法审查。
• 不看 diff 直接合并——测试通过不代表行为符合预期。
• 把报错全文粘贴但不说复现步骤——AI 只能猜。