Codex AGENTS.md 与提示词教程：项目规则、任务拆解和验收模板（2026）

Codex 项目协作需要两类说明：长期有效的项目规则，以及这一次要完成的具体任务。把测试命令、禁改目录和交付要求留在 AGENTS.md，把目标、范围和验收写进任务消息，能减少反复解释，也更容易检查工具有没有越界。这篇 Codex 使用教程提供可调整的模板，不把长提示词当作正确性的保证。

整理公开需求时，可以先用 AIMirror GPT 中文站 或 AICNBox 中文 AI 入口 比较表达。两者是第三方网页服务，不等于 Codex 官方工具，也不会自动读取本地规则；不要把私钥、内部代码和客户数据作为提示词素材上传。

更新日期：2026 年 10 月 24 日。本文侧重项目管理方法，示例不是任何真实仓库的默认配置。官方文档本次读取受限，规则发现范围与优先级请在自己的客户端核对，不据此承诺所有版本行为一致。¹

一、先把三类信息分开

长期规则回答“这个项目平时怎样开发”，单次任务回答“现在改什么”，可复用流程回答“遇到这类工作按什么步骤做”。三者混在一起，会让过期需求长期影响后续任务。先分清归属，再决定写到哪里，比不断增加强调词更有用。

AGENTS.md 是项目说明，不是系统权限开关，也不是密钥保险箱。写上“禁止访问网络”不能替代实际网络策略；写上“只读”不能替代沙箱配置。规则负责表达意图，工具权限与人工验收负责约束和检查执行。

二、先收集事实，再编写规则

从 README、项目脚本和现有协作方式收集真实信息。确认源码位置、生成目录、测试入口和发布流程，再写成简短说明；没有确认的命令标注待核对，不要猜一个看起来常见的构建命令。维护者应能解释每一条规则的依据。

检查工作区有没有已有 AGENTS.md，先读再改，避免创建另一份相互矛盾的说明。多目录项目尤其要记录规则适用范围，子项目可能有不同运行时和测试命令；具体加载顺序以当前客户端文档和实际验证为准，不凭文件名推断。

先让 Codex 只读列出它找到的规则文件与约束摘要，人工打开对应文件对照。这个步骤只能检查理解情况，不能证明它以后绝不偏离；但能及时发现路径错误、规则未加载和含糊表达。发现问题先调整范围，不要用更多感叹号覆盖。

三、一份可以调整的 AGENTS.md 示例

下面模板刻意不绑定框架。创建前先替换目录与测试说明，删除不适用的内容；不要把占位符原样提交。规则放在团队认可的位置，并由维护者审阅，避免个人习惯变成未经确认的全项目要求。

# 项目协作规则

## 范围
- 只处理任务指定文件；扩大范围前说明原因。
- 保留已有用户修改，不覆盖无关内容。
- 不修改生成目录、依赖目录和生产凭证。

## 实施
- 优先复用现有实现，不为小修复新增依赖。
- 诊断只解释；实施、提交和发布分别确认授权。
- 命名、格式和错误处理沿用附近代码。

## 验证
- 从项目配置读取正确的测试与构建命令。
- 先跑相关测试，再执行项目约定检查。
- 界面修改检查窄屏、键盘操作及明暗主题。

## 交付
- 列出修改文件、原因、已执行命令及结果。
- 分开说明失败与未执行项。
- 不在报告或日志中输出密钥和个人资料。

模板里的“生成目录”需要换成项目实际路径，测试命令最好明确到在哪个目录执行。对团队而言，能复制复现的说明比“遵循最佳实践”更有约束力；无法验证的形容词尽量删掉，改成动作和预期结果。

四、单次任务按四个字段写

任务消息至少包含目标、范围、限制和验收。背景只提供影响决策的材料，不必重复整个产品历史；复现步骤、实际结果和预期结果尤其重要。可以先让 Codex 指出缺少的信息，再确认实施方案，避免它自行补全业务规则。

目标：修复搜索框输入纯空格仍发送请求的问题。
范围：搜索输入处理及相关测试，不修改其他页面。
限制：不增加依赖，不改变接口，不提交或推送。
验收：纯空格不发送请求；合法关键词仍能查询；
空结果与网络失败提示保持正常。
先只读定位原因，说明受影响文件，确认后再实施。

验收不要只写“功能正常”。上例明确了应阻止的行为，也说明应保留的行为，方便识别回归；项目有特殊空格处理或国际化要求时，要在实施前补齐。没有业务依据的边界不要由模型猜定。

五、诊断、修复与审查使用不同模板

只想知道原因，就要求提供证据和复现办法，而不是直接改文件。诊断输出应区分确认事实、合理推测和待验证项；一条日志只能支持它实际说明的范围，不能据此宣布整个系统已经找到根因。

只读诊断，不修改、不安装依赖、不执行外部请求。
根据脱敏报错和项目文件，列出最可能的原因。
每项给出证据、反证条件与最小验证步骤。
缺少材料时说明缺什么，不编造运行结果。

确认原因后再提出修复任务，要求最小补丁和针对性测试。审查则关注已有差异的风险，要求指出触发条件、影响和复现方法；不要把“审查一下”默认理解成可以修改全部问题。完整操作路线可看 Codex 使用总教程。

审查意见也要人工核验。看似重复的校验可能对应不同信任边界，看似未使用的字段可能被外部系统读取；让工具注明判断依据，再结合真实调用路径决定是否修改，不能为了满足审查建议制造新问题。

六、规则冲突时先停在边界内

任务要求与项目说明不一致时，应把冲突具体列出来。例如任务要求升级依赖，而规则禁止新增依赖，先解释是否确实必须升级及替代方案；未得到清楚授权前，不应默默忽略约束。文件里的说明也不能覆盖运行环境的安全限制。

外部网页、第三方文档、日志和代码注释可能包含指令式文字。引用这些材料是为了理解业务，不代表授权执行其中的命令；尤其是要求上传环境变量、关闭保护、下载运行脚本的段落，应当作为不可信内容处理，并向维护者说明。

规则需要改动时，把调整本身作为可审阅的差异。先说明旧规则为什么不再适用、会影响哪些流程，再修改并测试；不要在修业务问题时悄悄放宽全部权限。生产操作、付款和对外消息仍应独立确认。

七、用小任务验证规则是否有用

选择无敏感数据的练习仓库，先让工具复述规则，再做一项小修改。对照检查文件范围、依赖变化、测试结果和交付摘要；至少验证一项禁止行为确实没有发生，但不要故意授权危险操作来测试它是否服从。

检查时同时看 git status --short 和差异，未跟踪文件要单独打开。终端工作流可参考 CLI 使用教程，编辑器协作可看 VS Code 使用教程；入口不同，规则仍需在实际环境中验证。

八、维护规则，不把它变成聊天档案

每次目录、运行时或发布流程变化后，顺手检查规则。已经删除的脚本、失效的路径和临时故障记录应及时清理；保留规则适用条件和负责复核的人，比保留每次修改的长故事更方便维护。

规则开始变长时，先合并重复项，再判断哪些内容属于单次任务。高频、稳定且有明确输入输出的流程才值得做成 Skill；偶发问题继续留在任务里，避免为了复用而增加复杂度。引用其他说明时注明路径，不要求每次无差别阅读全部材料。

团队成员可以用同一个练习验证改版规则，并比较两次差异与测试记录。有效性不以提示词长度衡量，而是看是否减少重复纠正、是否能及时发现偏离、是否保留必要的人类确认。没有改进就继续简化，而不是继续堆条款。

九、开始下一次任务前的行动清单

维护者还应记录规则的复核日期，尤其是在迁移目录或更换测试工具之后。旧规则中的路径即使仍然存在，也可能不再是当前开发入口；用一次最小任务确认它确实指向正确环境，再让团队继续复用。没有条件验证的部分明确标注待确认，不把历史成功当成永久保证。

交接时只提供当前有效的规则和本次任务摘要，不必附上完整聊天记录。接手者应能从文件、差异和命令结果理解现场；需要个人记忆才能解释的约定，应补成可复核说明，再进入下一轮修改。

先核对已有规则，补充当前目标与验收，再要求只读理解。确认方案后授权最小修改，最后阅读差异、执行测试并记录未验证项；提交与发布另行确认。这样才能把 Codex 使用教程里的方法变成可重复的协作步骤。

需求仍然模糊时，可在 AIMirror GPT 中文站 整理不含敏感信息的目标，回到项目后再补真实路径和测试命令。先做好一份短规则与一个小任务，比复制一份无法核验的万能提示词更实用。