目标
你最终想得到什么结果，而不只是“帮我看看”。
CODEX FIELD GUIDE · 2026
先理解 Agent，
再把任务交给 Agent。
Codex 不是“会写代码的聊天框”。它会读取规则、检查环境、调用工具、观察结果，再决定继续还是结束。你要做的，是给它清晰的目标和可靠的边界。
AGENT
目标仍未完成？
不是一次回答而是可观察、可纠正的执行循环
00 / 心智模型
一次可靠执行，需要四样东西
上下文
仓库、文件、现状、错误和已有约定。
边界
什么不能改、哪些操作需确认、范围到哪里。
验收
测试、截图、命令输出，或明确的完成条件。
好任务=目标+上下文+边界+验收
01 / 指令层
全局与仓库 AGENTS.md
把它理解为“每次开工前，Agent 必须先读的工程约定”。离当前目录越近的规则，优先级通常越高。
GLOBAL
基础层
~/.codex/AGENTS.md
个人跨仓库习惯：语言、提交格式、安全边界、默认验证方式。
REPO
项目层
project/AGENTS.md
团队共享约定：技术栈、目录职责、构建命令、测试与发布规则。
LOCAL
最高层
project/api/AGENTS.override.md
局部例外：只适用于当前子目录，覆盖上层冲突规则。
02 / 执行层
Agent Loop 原理
模型不会“一次性生成整个工程”。每次工具结果都会成为下一步判断的新输入，这就是 Agent 与普通文本生成的关键区别。
理解
读取请求、指令层与完成条件。
检查
查看代码、环境、工具和当前状态。
决定
选择下一项最小且有效的动作。
执行
编辑文件、运行命令或调用外部工具。
观察
读取输出，识别成功、错误与新事实。
验证
测试结果；未完成就回到下一轮。
你不需要提供 Agent 的“思维过程”。你需要提供的是可检查的事实、明确约束和验证方法。
读取 → 决定 → 工具调用 → 结果 → 再决定
03 / 长任务
Goal 模式：让任务跨轮次持续推进
Goal 是部分 Codex 客户端提供的长任务机制。它保存一个明确目标及其状态，让 Agent 在自动续跑时继续围绕同一结果工作。
一轮对话内完成
- 修一个明确的 bug
- 解释一个模块
- 改一处页面样式
范围窄、上下文稳定、一次验证即可收尾。
围绕结果持续迭代
- 迁移整个项目
- 完成多阶段部署
- 长期排查复杂故障
适合需要多轮执行、阶段验证和中断后恢复的任务。
active 持续推进
→
complete 验收完成
或
blocked 确认无法继续
Goal 不是“放宽要求”，也不是简单待办清单。完成标准、验证和安全边界仍然有效；具体可用性与界面以当前 Codex 客户端为准。
04 / 能力层
Skills：可复用的专业工作流
Skill 是一个包含 SKILL.md 的目录，可附带脚本、参考资料和模板。它告诉 Codex 某类任务应该按什么流程完成。
常驻上下文
名称 + 描述 + 路径
用很少的上下文告诉 Codex“有哪些能力可用”。
按需加载
完整 SKILL.md
只有匹配任务时才读取完整流程，称为渐进式披露。
深层资源
scripts/ + references/
再按步骤调用脚本或读取具体参考文件。
deploy-service/
├── SKILL.md # 必需：触发条件与流程
├── scripts/ # 可执行工具
├── references/ # 按需读取的知识
└── assets/ # 模板与静态资源什么时候该写 Skill？
同一类任务反复出现，而且需要稳定步骤、专用工具或领域知识时。
一句判断：规则讲“始终怎么做”，Skill 讲“遇到这类任务时怎么做”。
05 / 机制选择
这条信息应该放哪里？
选择你正在解决的问题，查看最小且合适的 Codex 机制。
DURABLE INSTRUCTIONS
使用 AGENTS.md
适合语言规范、代码约定、验证命令、禁止事项与仓库边界。保持短小、稳定，并放在需要生效的目录层级。
project/AGENTS.md
06 / 起步模板
从两个短文件开始
示例故意保持精简。把真正稳定的约定写进去，而不是复制一份庞大的通用规则。
# Personal defaults
- Reply in Chinese.
- Read files before editing.
- Keep changes scoped to the request.
- Run focused verification after changes.
- Ask before irreversible operations.# Project guide
- Install: `pnpm install`
- Dev: `pnpm dev`
- Test: `pnpm test`
- Reuse components from `src/ui`.
- Do not edit generated files in `dist/`.
- Verify desktop and mobile layouts.第一条高质量任务可以这样写：
“修复登录页在 390px 宽度下按钮溢出的问题。复用现有组件，不改其他页面。完成后运行前端测试，并用桌面和移动端截图验证。”
READY / CHECK
交给 Agent 前，检查这五件事
- 01目标是否能用一句话说清？
- 02Agent 是否能找到相关文件与现状？
- 03不能做什么，是否明确写出？
- 04完成后要运行什么验证？
- 05重复规则是否应该沉淀到 AGENTS.md 或 Skill？