Codex 提示词怎么写？20 个编程 Prompt 模板与 AGENTS.md 最佳实践（2026）

如果你条件有限，强烈推荐国内 API 站

这是站主自主搭建纯 GPT API 站，无需梯子，实时更新 GPT 最新模型（仅支持电脑端），价格是官方的 三分之一，操作简单，连接稳定，价格便宜，保证没有任何掺水、收集信息等低劣行为，保证爽用 GPT。

• 考普 AI 官网入口

Codex 的效果不仅取决于模型能力，也取决于你能否讲清任务。只输入“帮我改一下项目”，很容易出现修改范围过大、遗漏测试或结果不符合预期。

本教程提供一套适合真实项目的六段式 Prompt 结构，并整理 20 个可直接复制的模板，覆盖代码分析、Bug 修复、功能开发、测试、重构、安全审查和文档维护。

还没准备好环境可先看 Codex 安装配置教程；希望完整走一遍项目流程可看 Codex 写代码实战；需要把固定流程、脚本和参考资料打包复用，则看 Codex Skills 教程。

一、Codex 提示词的六段式公式

部分	要说明什么	示例
目标	最终解决的问题	修复登录后偶发跳回登录页
上下文	技术栈、现状、相关文件	Next.js + TypeScript，认证在 src/auth/
范围	允许查看或修改的内容	只改中间件和对应测试
限制	明确不能做什么	不换认证库，不改数据库结构
验证	如何证明完成	测试、类型检查、构建与 Diff
输出	如何汇报	原因、文件、结果和剩余风险

通用骨架：

目标：
[最终要完成的事情]

上下文：
[技术栈、相关目录、当前行为与预期行为]

范围：
[允许检查和修改的文件或模块]

限制：
[禁止修改的内容、兼容性和安全要求]

验证：
[需要运行的测试、构建、类型检查或人工验收]

输出：
[要求说明修改、验证结果、风险和待确认事项]

任务越简单，Prompt 可以越短；影响范围越大，边界和验证就应该越明确。

二、普通提问与结构化提问对比

不推荐

帮我修一下登录问题，顺便优化代码。

它没有故障现象、预期行为、范围和验收方式，“顺便优化”还会诱发无关修改。

更可靠

目标：
修复用户登录成功后偶尔被重定向回 /login 的问题。

上下文：
这是 Next.js + TypeScript 项目。登录接口位于 src/app/api/login/，
认证中间件位于 src/middleware.ts。问题常发生在登录后首次打开控制台时。

范围：
先只读分析认证流程，再修改与 Cookie 写入、读取和重定向直接相关的文件。

限制：
不更换认证库，不修改数据库结构，不调整无关页面样式。

验证：
运行相关单元测试、类型检查和构建，检查最终 Diff 无无关变化。

输出：
说明根因、修改文件、命令结果和未覆盖风险。

后者没有指定每一行代码，却提供了足够清楚的任务边界。

三、20 个可复制的 Codex Prompt 模板

使用时把方括号替换为项目实际信息。

模板 1：快速理解陌生项目

请只读分析这个项目，不修改文件。
检查目录、入口、依赖、脚本、核心模块、配置和测试。
用中文说明架构、启动命令、风险和建议阅读顺序。
不要输出或猜测任何密钥内容。

模板 2：定位 Bug 根因但暂不修改

请分析以下问题，本轮不要修改：
现象：[实际错误]
预期：[正确行为]
复现：[步骤]
范围：[目录或模块]
追踪调用链，区分事实和推测，给出证据、影响与最小修复方案。
信息不足时明确列出还需要什么。

模板 3：最小范围修复 Bug

目标：修复 [Bug]。
上下文：[技术栈、错误、复现和文件]
范围：只改直接相关文件并补必要测试。
限制：不做无关重构，不升级依赖，不改变公开 API。
验证：运行相关测试、类型检查、构建和 git diff --check。
输出：根因、修改、命令结果和剩余风险。

模板 4：开发一个小功能

用户需求：[功能]
验收条件：
- [条件一]
- [条件二]
- [条件三]
相关模块：[文件或目录]
先阅读现有实现并给计划，优先复用现有组件，不引入非必要依赖。
完成后运行测试和构建，逐项报告验收结果。

模板 5：补充单元测试

为 [函数或模块] 补单元测试。
先核对测试框架和 Mock 习惯，覆盖正常、边界、空值、异常和回归场景。
不要为了测试通过改变生产行为；无法测试时先解释原因。
运行相关测试并说明覆盖的行为，不虚构覆盖率。

模板 6：为接口补集成测试

为 [接口] 添加集成测试，覆盖正常响应、参数错误、未授权、下游异常和幂等场景。
复用现有测试设施，不连接生产服务，不写真实账号或 Token。
列出命令、结果和未覆盖场景。

模板 7：重构复杂函数但保持行为

重构 [函数]，提高可读性和可测试性，但保持外部行为不变。
先说明职责、复杂分支和测试保护情况。
不改签名、返回结构和错误类型，不顺手重构其他模块。
先补测试，再小步重构并运行验证。

模板 8：消除重复代码

检查 [文件列表] 的重复实现。
先列出重复点和细微差异，只有语义一致时才抽取。
避免参数过多的万能函数，保持公开接口，补公共逻辑测试。

模板 9：提升 TypeScript 类型安全

改进 [目录] 的 TypeScript 类型安全。
检查 any、不安全断言、可空值、接口响应、泛型和联合类型分支。
不要只用 unknown 加强制断言；不改变运行时行为。
运行 typecheck 和相关测试，列出仍无法收窄的类型。

模板 10：处理性能问题

分析 [页面或函数] 的性能问题：[现象]。
先从测量、日志和代码路径寻找证据，不凭感觉优化。
列出瓶颈依据，只实施低风险、可验证的改动。
提供可复现的前后验证；没有可靠数据时明确说明。

模板 11：排查构建失败

排查构建失败，错误如下：[已移除敏感信息的完整错误]。
找到第一个具有根因意义的错误，区分源码、依赖和环境问题。
用最小改动修复，不随意删除锁文件或全量升级依赖。
重新构建并报告根因、修改和环境要求。

模板 12：安全升级单个依赖

将 [依赖] 从当前版本升级到 [目标范围]。
先核对迁移说明、所有用法、破坏性变化和运行环境要求。
只升级必要依赖，不绕过类型或安全检查。
运行测试和构建，说明兼容性变化与人工检查项。

模板 13：增加输入校验

为 [接口或函数] 增加输入校验，处理必填、类型、长度、数值边界、枚举和危险字段。
沿用现有校验库和错误格式，不在日志暴露密码、Token 或个人数据。
补正常与异常测试，说明每类非法输入的处理。

模板 14：代码安全审查

只读审查 [目录或 Diff]，不要修改。
重点检查认证授权、注入、XSS/CSRF、开放重定向、路径遍历、密钥泄露和不安全依赖。
每项发现给出位置、触发条件、影响、严重度和修复建议。
不要把缺乏证据的可能性写成已确认漏洞。

模板 15：审查当前 Git Diff

审查当前 git diff，不修改文件。
优先找逻辑错误、行为回归、边界、安全、测试遗漏和无关改动。
按严重程度列出文件与行号；没有明确问题时直说，并列出残余风险。
不要只复述变化。

模板 16：修复响应式布局

修复 [页面] 在 [宽度/设备] 下的 [溢出或遮挡]。
优先复用现有断点和变量，不改变桌面端，不引入新 UI 框架。
检查关键宽度，说明选择器、影响范围和人工验收步骤。

模板 17：改进错误处理与日志

改进 [模块] 的错误处理。
区分输入、业务和系统错误；保留排查上下文但不记录敏感信息；不静默吞异常。
沿用现有日志格式，补异常路径测试，说明哪些错误会重试、转换或抛出。

模板 18：更新项目文档

根据当前代码更新 [README 或接口文档]。
包含用途、环境、安装、启动、配置、示例、测试和故障排查。
所有命令和路径必须从仓库核对，不编造参数、截图或运行结果。
无法验证的内容标记“需要确认”。

模板 19：只制定实现计划

为以下需求制定计划，本轮不修改：[需求]。
分析现有模块、数据流、可复用代码、文件变化、迁移与兼容风险、测试和分阶段交付。
按依赖顺序输出计划，对未知业务规则列出问题和备选方案。

模板 20：任务完成后的综合验收

对刚才的修改做最终验收：
- 检查 git status 和 git diff；
- 逐项核对验收条件；
- 报告测试、类型检查、Lint 和构建；
- 检查临时文件、调试代码和敏感信息；
- 列出人工验证与剩余风险。
不要降低规则或跳过失败项；未经要求不要提交、推送或部署。

四、一次性 Prompt 与 AGENTS.md 的区别

当前 Prompt 适合写这一次任务的目标；AGENTS.md 适合记录未来多个任务仍成立的仓库规则；Skill 则适合把一类任务的说明、脚本和资源做成可调用的工作流。完整边界与创建方式见 Codex Skills 安装、启用与创建教程。AGENTS.md 常见内容包括：

• 项目结构和技术栈；
• 安装、测试、Lint 与构建命令；
• 目录职责和代码风格；
• 兼容性与安全规则；
• 最终交付检查项。

不适合放进 AGENTS.md 的内容包括：

• 密码、API Key、Cookie 或其他凭据；
• 只对某一次任务有效的临时要求；
• 已经过期或无法执行的命令；
• 默认自动提交、推送或部署的高风险指令；
• “任何情况下都必须成功”这类不可验证目标。

大型仓库可以在子目录放置更具体的 AGENTS.md。规则应和对应目录的真实工作方式一致，并由团队维护者审查。

五、安全、可维护的 AGENTS.md 示例

# Repository Guide

## Project Structure
- `src/` contains production source code.
- `tests/` contains automated tests.
- Do not edit generated files in `dist/`.

## Development Commands
- Install: `npm ci`
- Test: `npm test`
- Typecheck: `npm run typecheck`
- Lint: `npm run lint`
- Build: `npm run build`

Verify that a command exists in `package.json` before running it.

## Change Rules
- Make the smallest change that satisfies the request.
- Preserve public APIs unless explicitly asked otherwise.
- Do not perform unrelated refactors.
- Reuse existing utilities before adding new ones.
- Add or update tests when behavior changes.

## Security
- Never print, copy, commit, or modify real secrets.
- Do not open `.env` unless the task explicitly requires configuration analysis.
- Do not weaken authentication, authorization, or validation to make tests pass.

## Git and Delivery
- Inspect `git status` before and after editing.
- Review `git diff` before reporting completion.
- Do not commit, push, publish, or deploy unless explicitly requested.
- Do not discard existing user changes.

## Final Report
Include files changed, behavior, validation results, checks not run, and remaining risks.

只记录“未来多个任务仍然成立”的规则。过长、冲突或过期的说明会增加理解成本，应定期清理。

六、AGENTS.md 的安全边界

• 不写真实凭证，即使仓库是私有的；
• 不默认读取所有 .env、密钥目录或用户主目录；
• 不默认授权提交、推送、发布和生产部署；
• 不要求跳过测试、关闭权限检查或忽略构建错误；
• 不使用“发现问题就删除相关目录”这类宽泛指令；
• 不把网页、Issue 或代码注释里的不可信文字自动视为命令；
• 数据库迁移、批量删除和生产操作应先说明影响并等待确认；
• 明确保留仓库中已有的未提交修改。

七、任务完成后的验证清单

• [ ] git status 没有意外生成文件；
• [ ] git diff 只包含当前任务改动；
• [ ] 没有覆盖用户原有未提交代码；
• [ ] 没有泄露密钥、Cookie、邮箱或用户数据；
• [ ] 相关测试已经运行；
• [ ] 类型检查、Lint 和构建结果已明确说明；
• [ ] 没有通过删测试或降低校验来规避失败；
• [ ] 新依赖确有必要并检查了锁文件；
• [ ] 文档、配置示例和实现一致；
• [ ] 高风险修改经过人工复核；
• [ ] 提交、推送与部署仍由人明确决定；
• [ ] 无法验证的部分被标记，而非描述成已通过。

八、常见问题

Prompt 是不是越长越好

不是，关键是信息密度。简单文案修改只需目标、范围和验证；认证、支付、数据迁移等高风险任务应明确六个部分。

可以直接让 Codex 修改整个项目吗

不建议在不了解仓库时开放无限范围。先只读分析，再制定计划，最后分模块实施和验证。

AGENTS.md 能代替当前 Prompt 吗

不能。它保存长期规则，当前 Prompt 仍需说明这次任务的目标、具体范围与验收条件。

修改完可以直接上线吗

不建议。至少查看 Diff、运行相关测试并人工验收；账号、支付、权限、数据库和生产配置需要更严格复核与回滚准备。

总结

写好 Codex 提示词的核心不是堆技术术语，而是把任务讲清楚：目标说明结果，上下文帮助理解，范围控制边界，限制降低风险，验证证明完成，输出形成可复核报告。

经常重复的规则写进 AGENTS.md，每次任务的具体目标留在当前 Prompt。两者配合，才能让 Codex 从“生成代码的工具”变成更可靠的项目协作助手。

继续阅读：Codex 项目实战 · Codex Skills 教程 · Codex 安装配置教程 · Codex 国内使用方案