更新时间：2026-07-06
这是一篇给团队外部读者看的 Codex 简明教程。它不假设你使用某个特定项目，也不要求你先背完一整本配置手册。目标很朴素：让你知道怎么把 Codex 用成一个靠谱的代码协作者，而不是一个会写代码但偶尔迷路的热心路人。
先说结论：Codex 很强，但它不是许愿池。你给它清楚的上下文、边界和验收标准，它就像临时加入团队的高级工程师；你只说“帮我优化一下”，它可能真的会开始优化，顺便把你没打算动的抽屉也整理了。
这篇适合谁
- 你已经或准备在代码仓库里使用 Codex。
- 你希望 Codex 不只是回答问题，还能读代码、改文件、跑命令、做自测。
- 你想把团队规则沉淀下来，而不是每次都写一段“祖传 prompt”。
- 你想让 AI 帮忙，但又不想把生产仓库交给一位过度自信的电子实习生。
如果你只是想问“这个函数什么意思”，也能看；但这篇的重点是：如何把 Codex 用进真实开发流程。
先记住一句话
把一次性要求写进当前 prompt，把长期规则写进 AGENTS.md，把复杂细则放进项目文档，把重复流程做成 skill，把机械检查交给 hooks / rules，把外部系统通过 MCP 接进来。
翻译成人话就是：
- 临时要求：今天这次怎么做。
AGENTS.md：这个仓库永远怎么做。- 文档：细节太多，别塞爆 Codex 的脑袋。
- skill：总是重复的流程，让它变成一键可复用。
- hooks / rules：能机械判断的事情，不要靠人类和模型的自觉。
- MCP：需要访问 GitHub、Figma、Notion、内部文档等外部系统时，给 Codex 正规通道。
不要把所有东西都塞进一次 prompt。那不叫上下文工程，那叫把冰箱、洗衣机和客厅沙发一起塞进登机箱。
一个典型的项目骨架示例可以长这样：
AGENTS.mddocs/ 开发原则.md 设计规范.md Codex工作规则/ 交付校准与路由规则.md 功能落地后自测和人工验收规则.md 提交规则.md 对话记录规则.md 本地运维记录规则.md.agents/ skills/ project-acceptance/ SKILL.md project-commit-push/ SKILL.md project-conversation-archive/ SKILL.md.codex/ config.toml rules/ default.rules hooks.json hooks/ post_tool_use_project_check.py stop_project_check.py agents/ architecture-reviewer.toml test-acceptance-reviewer.toml security-reviewer.toml下面所有示例都按这个骨架改写成通用版本。你可以照抄结构，不要照抄项目名、端口、私有路径、远端地址、凭证位置和任何真实业务秘密。公开教程要像样板间，不要像把自己家钥匙也摆上展台。
Codex 到底在工作时做什么
你可以把 Codex 理解成一个会读代码、会改代码、会跑命令、会解释原因的 coding agent。它通常可以完成这些事：
- 阅读项目文件和已有实现。
- 修改代码、配置、文档或测试。
- 运行命令，比如类型检查、测试、格式检查、脚本。
- 根据错误继续排查。
- 总结改动范围、验证结果和剩余风险。
- 在需要时使用工具、浏览器、MCP、插件或 skill。
但它也有边界：
- 它不知道你脑内的真实需求，除非你说出来。
- 它可能不知道某个库、产品或规则的最新变化，除非它查证。
- 它可能过度发散，所以你要给边界。
- 它能改很多文件，但不代表它应该改很多文件。
- 它可以运行命令，但危险命令必须谨慎，尤其是删除、重置、强推、生产环境操作。
好用 Codex 的关键不是“写一段神奇 prompt”，而是把协作环境布置好。
第一层：把长期规则写进 AGENTS.md
AGENTS.md 是给 Codex 的项目说明书。它适合放稳定、每次都应该遵守的规则，比如：
- 项目的构建、测试、启动命令。
- 代码风格和命名约定。
- 哪些目录属于前端、后端、共享逻辑、脚本、文档。
- 重要架构边界，比如“客户端不能直接写数据库”。
- 交付时必须说明哪些内容，比如改动范围、验证结果、风险。
- 什么时候需要读哪些更详细的文档。
一个轻量的 AGENTS.md 可以长这样：
Agent 工作约定
开工前
- 先阅读本文件。
- 优先理解现有实现，不要凭记忆猜项目结构。
- 小改动直接处理；复杂、跨模块、高风险任务先给计划。
架构边界
- 客户端只调用公开 API，不直接访问数据库。
- 服务端负责权限、校验、持久化和审计。
- shared 目录只放跨端纯逻辑，不访问文件系统、网络、DOM 或环境变量。
验证
- 文档改动至少运行
git diff --check。 - 前端代码改动运行
npm run typecheck。 - 服务端代码改动运行
npm run test或对应模块测试。 - 无法运行验证时，最终回复必须说明原因。
交付
- 说明改了什么。
- 说明跑了什么验证。
- 如果有用户可见行为变化，给出人工验收路径和剩余风险。
更贴近实战的写法，可以采用“轻前置 + 重后置”：开工前只读少量硬红线，避免一上来把模型淹进文档浴缸；交付前再按实际改动补读细则。
Agent 工作约定
本文件适用于整个仓库。默认采用“轻前置 + 重后置”： 开工前只看少量硬红线；完成后再按实际改动读取细则、验证并修正。
工作流程
- 开工前：读取本文件，判断任务类型和风险。
- 工作中：优先读代码事实和现有实现，沿用当前模块、命名和数据流。
- 交付前：按
docs/Codex工作规则/交付校准与路由规则.md做后置校准。
前置硬红线
- 客户端不直接读写数据库；持久化写入必须经过服务端 API、迁移或明确导入脚本。
- 服务端拥有事实、权限、校验、数据库写入和审计。
shared只放跨端纯逻辑，不访问数据库、文件系统、HTTP、DOM、cookie、localStorage 或环境变量。- 日志和本地记录必须默认安全；不要输出 token、cookie、口令、私密正文、私有远端或完整敏感 payload。
按需读取入口
| 场景 | 读取文档 |
|---|---|
| 交付前校准、验证、文档更新判断 | docs/Codex工作规则/交付校准与路由规则.md |
| 开发原则、命名、验证、文档边界 | docs/开发原则.md |
| UI、移动端、阅读体验、弹窗、布局、交互 | docs/设计规范.md |
| 提交、commit、push | docs/Codex工作规则/提交规则.md |
| 对话归档、本地记录 | docs/Codex工作规则/对话记录规则.md |
注意，AGENTS.md 不是百科全书。它应该像机场提示牌，清楚、稳定、指路；不要写成机场地下管线施工图。
第二层：把复杂细则放进文档
有些规则很重要，但太长，不适合放在 AGENTS.md。比如：
- 详细设计规范。
- 数据模型和迁移规则。
- 发布、同步、导入、导出流程。
- 安全与信息保护细则。
- 人工验收标准。
- 提交和发布流程。
这类内容应该放进 docs/，再在 AGENTS.md 里写“什么时候读哪份文档”。
推荐结构：
AGENTS.mddocs/ 开发原则.md 架构说明.md 设计规范.md 验收规则.md 提交规则.md如果参考一个真实项目的做法，docs/ 可以拆得更明确一些：
docs/ 开发原则.md 设计规范.md Codex工作规则/ 交付校准与路由规则.md 功能落地后自测和人工验收规则.md 提交规则.md 对话记录规则.md 本地运维记录规则.mddocs/开发原则.md 适合放长期工程价值观，不放一次性任务流水账：
开发原则
- 真实优先，显式失败
不用静默 fallback 掩盖真实问题；无法正确处理的状态应尽早暴露、记录并修正。
- 简洁优先，及时收口
功能完成后及时清理临时逻辑、重复分支和历史痕迹；无关重构不夹带进功能改动。
- 边界清晰，抽象有因
分层、模块和抽象必须服务于稳定边界、复用和隔离复杂度。
- 可读可观测，默认安全
日志必须级别清晰、可定位问题、默认不暴露秘密；禁止输出凭据、token、密码或完整正文。
- 小步变更，可验证可回滚
每次改动先明确影响范围和最小验证路径；高风险能力必须可重复执行、可追踪、可回滚。
docs/设计规范.md 适合约束 UI 和交互，不要每次靠 prompt 临时祈祷“美观一点”：
设计规范
核心原则
- 内容优先：公开端让标题、正文、图片和目录成为主角；后台让表格、表单和关键操作成为主角。
- 分层清楚：页面、区域、组件、状态要可辨，但不依赖厚阴影、大渐变或装饰背景。
- 行为稳定：加载、拖拽、选中、保存、失败等状态必须可预期，不能造成布局跳动或误触。
检查清单
- 是否复用了现有主题变量和组件语义？
- 表格、媒体、工具栏和弹层是否有稳定尺寸或约束？
- 移动端是否无重叠、无不可读压缩、无关键操作丢失？
- 危险操作、等待态、失败态和恢复路径是否明确？
docs/Codex工作规则/交付校准与路由规则.md 则像“交付前总闸”，告诉 Codex 按触及范围补读什么、验证什么：
交付校准与路由规则
校准顺序
- 看实际改动：用
git status、git diff --name-only确认触及范围。 - 按触及范围补读文档：只读与本轮改动相关的原则、设计、架构或数据文档。
- 对照硬红线检查：确认没有违反客户端 / 服务端 / shared / 信息安全边界。
- 判断是否要更新长期文档：只写稳定事实，不写阶段流水账。
- 运行最小必要验证：按风险选择命令，不默认全量构建或全量测试。
最小验证矩阵
- 纯文档：
git diff --check - 架构边界：
npm run architecture:check - 客户端页面、组件、API client、TS schema：
npm run client:type-check - 服务端 HTTP、模块、配置：
npm run server:check
如果项目有用户可见功能，最好再单独写验收规则。别把“用户能不能验到”留给缘分，缘分的测试覆盖率通常不高。
功能落地后自测和人工验收规则
验收设计顺序
- 先确认本次实际改变的功能、页面、接口、数据流或运行态边界。
- 先写人工验收建议：入口、前置条件、主路径、边界 case、可观察结果。
- 从人工验收建议里抽取可重复的自测用例。
- 先运行专项自测，再按触及范围运行最小必要验证。
- 最终交付时说明自测结果、人工验收建议、URL / 验收路径和剩余风险。
提交规则也建议独立成文，尤其是团队里出现过“怎么把本地报告也提交上去了”的精彩瞬间：
提交规则
默认不提交的内容
docs/对话记录/docs/本地运维记录/tests/reports/.debug/、tmp/.env、密钥、cookie、token、口令、连接凭证- 本机绝对路径、私有远端、完整敏感 payload 或包含秘密的日志
Stage 和 commit
- 优先显式
git add本次应提交的路径。 - commit message 使用中文，简洁说明改动目的。
- 提交失败时保留现场，说明失败原因和下一步。
这样 Codex 开工前只需要读少量硬规则，真正需要细节时再按路由读取。你也不用每次把整套制度贴进聊天框，像在需求评审会上朗读公司章程。
第三层：把重复流程做成 skill
如果你经常对 Codex 说同一类话，比如：
- “按我们的格式提交并推送。”
- “修完功能后生成验收步骤。”
- “归档这次对话。”
- “按团队模板更新发布说明。”
- “检查是否有敏感信息泄露。”
这些就适合做成 skill。
skill 可以包含：
SKILL.md：说明什么时候使用、具体步骤是什么。scripts/：辅助脚本，比如生成报告、跑检查。references/：长参考资料。assets/：模板、示例、资源。
你可以把 skill 理解成 Codex 的“标准作业程序”。一次写好，多次复用。比起每次都在 prompt 里念一遍流程，skill 更像把泡面调料包提前配好，需要时直接加水，少一点人生波折。
适合做 skill 的判断标准：
- 这个流程会重复出现。
- 步骤比较固定。
- 需要引用一堆文档或脚本。
- 做错会有成本。
- 团队希望不同人、不同会话里得到一致结果。
公开版 .agents/skills/ 可以这样组织：
.agents/ skills/ project-acceptance/ SKILL.md project-commit-push/ SKILL.md project-conversation-archive/ SKILL.md project-ops-records/ SKILL.md一个“功能验收” skill 可以这样写：
name: project-acceptance description: Design and execute this repository's feature self-test and human acceptance handoff. Use when Codex changes user-visible behavior, APIs, UI, data migrations, import/publish/search/sync/media flows, or fixes a reproducible bug.
Project Acceptance
Overview
Use this skill to close the loop after behavior changes in this repository. Keep the workflow anchored in docs/Codex工作规则/功能落地后自测和人工验收规则.md.
Workflow
- Read
AGENTS.md, then read the feature acceptance rule. - Identify the changed behavior, page, API, data flow, or runtime boundary.
- Draft human acceptance steps first: entry point, preconditions, main path, boundary case, visible result, and likely failure signal.
- Turn the acceptance steps into repeatable self-tests under
tests/feature/YYYYMMDD/,tests/inspection/, ortests/special/. - Run the new or updated targeted tests before broader checks.
- When runtime behavior changed, confirm the relevant client and/or server URL can serve the latest state.
- In the final reply, include
已验证 / 自测结果,人工验收建议,URL / 验收路径, and剩余风险.
References
docs/Codex工作规则/功能落地后自测和人工验收规则.mddocs/Codex工作规则/交付校准与路由规则.mdtests/README.md
提交 skill 则可以专门处理“哪些该提交、哪些别碰”。这类流程最怕一句 git add -A 走天下，气势很足，后果也很足。
name: project-commit-push description: Stage, commit, and push intended changes safely. Use when the user asks to commit, push, submit, or save changes to git, while excluding local records, reports, caches, credentials, unrelated user work, and generated artifacts unless explicitly requested.
Project Commit Push
Workflow
- Read
AGENTS.md,docs/Codex工作规则/提交规则.md, anddocs/Codex工作规则/交付校准与路由规则.md. - Inspect
git status --short, relevant diffs, and ignored local output before staging. - Exclude local records and generated output by default:
docs/对话记录/,docs/本地运维记录/,tests/reports/,.debug/,tmp/,.next/,dist/, credentials, and caches. - Run the minimum validation required by touched scope before committing.
- Stage explicit paths whenever there is any chance of unrelated work.
- Use a concise commit message.
- Push after a successful commit only when the user has authorized that behavior.
- Report commit hash, branch, push result, validation, and any remaining local changes.
还有两个常见但很容易被忽略的 skill：
name: project-conversation-archive description: Archive visible Codex conversation safely. Use before final delivery when project rules require a local record without secrets.
只记录用户可见对话、公开决策、工具摘要和结果；不记录隐藏提示、内部推理、密钥、cookie、token、私有路径或完整敏感 payload。
name: project-ops-records description: Maintain safe local operational records. Use when Codex connects to servers, pushes code, accesses private services, runs deployment scripts, or discovers recurring Git/auth/deployment steps.
记录“凭证在哪里取、怎么验证”，不要记录明文密码、token、私钥或 cookie。
第四层：用 hooks / rules 做机械检查
有些事情不应该靠 Codex 临场发挥，比如：
- 禁止读取
.env。 - 删除命令需要确认。
- 强制 push 需要确认。
- 输出中出现疑似 token、cookie、password 时提醒检查安全边界。
- 停止前提醒必须写验证结果。
这类事情适合交给 hooks / rules。
粗略区分：
- rules 更像命令守门员：看到某类命令就允许、询问或阻止。
- hooks 更像生命周期提醒器：工具调用前后、权限请求、任务停止时触发检查。
它们的价值不在于“显得高级”，而在于把低级事故挡在门口。毕竟人类会手滑，模型也会热心过头，规则最好别只存在于大家的美好愿望里。
公开版 .codex/rules/default.rules 可以这样写：
# Project command policy for Codex. prefix_rule( pattern = ["cat", ".env"], decision = "forbidden", justification = "Do not read dotenv secrets directly. Ask for a safe placeholder value or use the documented credential location.", match = [ "cat .env", ],) prefix_rule( pattern = ["git", "push", "--force"], decision = "prompt", justification = "Force push can rewrite shared history; confirm explicitly.", match = [ "git push --force", ],) prefix_rule( pattern = ["rm", "-rf"], decision = "prompt", justification = "Confirm destructive recursive deletion before continuing.", match = [ "rm -rf tmp/build", ],) prefix_rule( pattern = ["sqlite3"], decision = "prompt", justification = "Direct database access can bypass server-owned validation; prefer server APIs, migrations, or explicit import scripts.", match = [ "sqlite3 data/app.db", ],).codex/hooks.json 适合把“工具调用后检查”和“停止前提醒”接起来：
{ "hooks": { "PostToolUse": [ { "matcher": "Bash|apply_patch|Edit|Write", "hooks": [ { "type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/post_tool_use_project_check.py\"", "timeout": 20, "statusMessage": "Checking project safety hints" } ] } ], "Stop": [ { "hooks": [ { "type": "command", "command": "python3 \"$(git rev-parse --show-toplevel)/.codex/hooks/stop_project_check.py\"", "timeout": 20, "statusMessage": "Checking delivery reminders" } ] } ] }}对应的 hook 脚本不必很重，能提醒就够。比如工具输出里出现敏感标记时提醒检查输出，或者发现本地记录被 stage 时提醒确认：
SENSITIVE_MARKERS = ( "authorization:", "bearer ", "cookie:", "password", "secret", "token", "private_key",) LOCAL_ONLY_PREFIXES = ( "docs/对话记录/", "docs/本地运维记录/", "tests/reports/",) if tool_payload_mentions_sensitive_marker: print("Project hint: keep final summaries free of secrets.", file=sys.stderr) if staged_file_starts_with_local_only_prefix: print("Project hint: local-only paths are staged; confirm before committing.", file=sys.stderr)如果团队经常需要专项审查，还可以在 .codex/agents/ 里放几个窄职责 subagent。它们适合“并行审查”，不适合“随便派出去大改一通”。
name = "security-reviewer"description = "Reviews changes and local records for secret leakage, unsafe logging, private paths, credential handling, and local-record staging risk."developer_instructions = """Review changes for security and logging issues.Prioritize leaked tokens, cookies, passwords, private keys, private remotes, local absolute paths, full sensitive payloads, unsafe logging, and accidental staging of local-only records.Read AGENTS.md, docs/开发原则.md, docs/Codex工作规则/对话记录规则.md, and docs/Codex工作规则/本地运维记录规则.md before reviewing.Return findings with exact paths and safer alternatives. Do not expose secret values in the response."""nickname_candidates = ["Security Review", "Secret Review", "Log Review"]第五层：用 MCP 连接外部系统
Codex 主要在代码仓库里工作。但真实开发经常离不开外部系统：
- GitHub / GitLab：issue、PR、review、CI。
- Figma：设计稿和组件。
- Notion / Confluence：需求文档。
- Linear / Jira：任务状态。
- 内部知识库、日志平台、监控系统。
MCP，全称 Model Context Protocol，可以让 Codex 通过标准方式访问外部工具和上下文。
什么时候需要 MCP？
- Codex 需要读取外部事实，而不是靠你复制粘贴。
- Codex 需要对外部系统执行动作，比如创建 issue、读取 PR 评论。
- 你的团队希望工具访问有明确权限边界。
- 你不想让“请看这个链接”变成“请你把 8 页文档复制给我”。
一句话：本地仓库里的事，先用文件和命令；外部系统里的事，考虑 MCP。
项目级 .codex/config.toml 可以只放团队共享且安全的配置，个人偏好和秘密留在用户自己的全局配置里：
# Project-scoped Codex configuration for trusted local runs.# Keep secrets and personal preferences in ~/.codex/config.toml. project_doc_max_bytes = 65536 [features]hooks = true [agents]max_threads = 6max_depth = 1 [mcp_servers.openaiDeveloperDocs]url = "https://developers.openai.com/mcp"enabled = truestartup_timeout_sec = 20tool_timeout_sec = 60default_tools_approval_mode = "auto"如果你接的是内部知识库、设计工具或任务系统，也按同样原则处理：配置连接方式，别把 token、cookie、私钥或账号密码写进仓库。给 Codex 接水管，不要把水厂钥匙挂在水管上。
第六层：复杂任务先计划
小修小补可以直接让 Codex 做。比如改一句文案、补一个测试、修一个明显拼写错误。
但这些任务建议先让它计划：
- 跨多个模块。
- 涉及数据库、权限、支付、发布、同步、导入导出。
- 需求还不清楚。
- 你只知道“有问题”，但不知道问题在哪里。
- 改错了会影响用户或生产数据。
好用的开场：
先不要改文件。请先阅读相关代码，按以下格式给我计划： 目标：不做范围：可能触及的模块：风险点：需要确认的问题：最小验证路径：计划的意义不是仪式感，而是防止 Codex 带着一把锤子冲进代码仓库，看什么都像钉子。
日常提需求的万能公式
给 Codex 提需求，可以用这个公式：
背景：现在发生了什么，相关页面 / 接口 / 文件是什么。目标：希望达成什么结果。边界：哪些东西不要动，哪些方案不要用。验证：改完需要跑什么检查，或者怎样人工验收。输出：最终希望它说明什么。一个不太好的 prompt：
帮我优化一下登录。这句话的问题是：优化哪里？性能？样式？流程？错误提示？安全？用户体验？如果 Codex 真的开始“全面优化”，你就会得到一场很有创造力的重构。
更好的写法：
背景：登录页在移动端输入验证码后，按钮状态不明显。目标：只调整按钮的禁用、加载和错误状态表现，不改登录 API。边界：不要改认证流程，不新增状态管理库。验证：改完运行前端类型检查，并给出移动端人工验收步骤。输出：说明改动文件、验证结果和剩余风险。这就清楚多了。Codex 不用猜，你也不用事后看着 diff 发出“你是谁，你对我的仓库做了什么”的声音。
常用 prompt 模板
1. 小改动
适合文案、局部样式、小范围文档修正。
帮我调整以下内容：…… 要求：- 只改相关文件。- 沿用现有风格。- 改完运行最小验证。- 最终说明改了什么、验证了什么。2. 功能实现
适合新增页面、接口、组件、脚本或业务能力。
目标：……背景：相关入口 / 页面 / 接口是……约束：- 不引入新的技术栈，除非现有方案无法完成。- 沿用现有模块边界和命名风格。- 不修改无关文件。完成标准：- 实现功能。- 补充必要测试或自测。- 给出人工验收路径和剩余风险。3. bug 修复
适合可复现问题。
现象：……复现步骤：1. ……2. ……期望结果：……实际结果：…… 要求：- 先定位原因，再做最小修复。- 不做无关重构。- 改完补充或运行能覆盖该问题的验证。- 最终说明根因、修复点、验证结果。4. 只读评估
适合架构判断、方案比较、代码审查前置分析。
只评估，不改文件。 请判断这个方案是否合理：……重点看：- 是否违反现有架构边界。- 是否会引入重复数据路径。- 是否有测试或迁移风险。 请引用具体文件和事实。5. 代码审查
适合检查当前 diff。
请 review 当前未提交改动。 重点看：- 真实 bug 或行为回归。- 架构边界是否被破坏。- 是否缺少必要测试。- 是否有敏感信息、调试日志或本地文件误入。 只给发现和建议，不改文件。6. 文档更新
适合让文档匹配当前事实。
帮我更新这份文档：…… 要求：- 以当前代码和已有文档为准。- 不写阶段流水账。- 只记录长期稳定规则。- 改完运行 `git diff --check`。7. 提交前整理
适合你已经认可改动，准备 commit。
请检查当前 git diff，帮我整理提交范围。 要求：- 先展示会提交哪些文件。- 排除本地日志、缓存、临时报告、密钥和无关改动。- commit message 用中文，简洁说明业务意图。- 未经确认不要 push。如果你要让 Codex 自动 push，请明确说。Git 不是许愿池，远端更不是。
一次健康的 Codex 工作流
推荐节奏如下：
- 让 Codex 先读少量关键规则。
- 让它查看相关代码和现状。
- 复杂任务先产出计划，小任务直接改。
- 修改时保持范围小。
- 改完运行最小必要验证。
- 查看 diff，必要时继续修正。
- 最终让它说明改动、验证、人工验收和风险。
也可以用一句话概括：
先看事实，再动手；小步修改，可验证交付。这听起来像工程常识，但工程常识最大的特点就是：大家都同意，然后经常忘。
验证怎么做才不虚
“已验证”这三个字很便宜，真正重要的是验证了什么。
常见最小验证：
| 改动类型 | 常见验证 |
|---|---|
| 纯文档 | git diff --check |
| 前端组件 | 类型检查、相关页面人工检查 |
| 服务端接口 | 单元测试、接口 smoke test |
| 数据结构 | 迁移测试、导入 / 读取验证 |
| UI 行为 | 浏览器实际操作、移动端尺寸检查 |
| 安全相关 | 权限路径、日志安全、失败场景 |
最终回复里最好让 Codex 写清楚：
- 已运行的命令。
- 命令是否通过。
- 没有运行的验证，以及为什么没运行。
- 人工验收路径。
- 剩余风险。
比如：
已验证：- 运行 `npm run typecheck`，通过。- 运行 `git diff --check`，通过。 人工验收：- 打开登录页。- 输入手机号并触发验证码流程。- 检查按钮的禁用、加载、错误状态。 剩余风险：- 未连接真实短信服务，仅验证了前端状态。这比“我测过了”可靠得多。后者通常和“我马上到”一样，需要结合语境理解。
安全边界：别把钥匙挂门上
使用 Codex 时，安全规则要提前写清楚。
建议长期固定这些底线：
- 不读取、不输出、不提交
.env、密钥、token、cookie、私钥。 - 不把完整用户隐私、生产 payload、内部日志原文写进公开文档。
- 不随便运行删除命令。
- 不随便
git reset --hard、git checkout --或强推。 - 不把本地临时文件、缓存、报告、会话记录默认提交。
- 访问生产环境、执行部署、修改数据库前必须确认。
如果你的项目有更具体的红线，比如“客户端不能直接访问数据库”“所有写入必须走服务端 API”“日志不能暴露秘密”，就写进 AGENTS.md。
不要等事故发生后再补规则。那叫用 production 当白板。
什么时候让 Codex 自己查资料
以下情况不要让 Codex 靠记忆：
- 最新版本、最新 API、最新价格、最新政策。
- 第三方库刚更新过的行为。
- 云服务、框架、SDK 的当前推荐写法。
- 法律、财务、医疗、安全等高风险信息。
- 任何你自己都觉得“这可能最近变了”的东西。
你可以直接要求：
这部分可能已经变化。请先查官方文档，再给方案，并在最终回复附上来源链接。对代码仓库内部事实，则优先让 Codex 读代码。外部事实查官方，内部事实看源码。不要反过来，反过来就像拿天气预报判断单元测试是否通过。
常见错误，以及怎么救
错误 1：把 Codex 当搜索框
只问“怎么做 X”，可能得到泛泛答案。更好的是让它结合你的项目：
请先阅读当前项目里 X 的实现，再给出改造建议。错误 2：一次塞太多目标
“顺便重构一下”“顺便优化性能”“顺便统一风格”都是范围膨胀的入口。顺便这个词，在代码里经常不顺。
更好的做法是拆任务：
- 先修 bug。
- 再补测试。
- 再单独做重构。
错误 3：没有验收标准
没有验收标准，Codex 只能猜什么叫完成。你说“更好看”，它可能理解成“更炫”；你想要“更清楚”，它可能端上一盘动效。
写清楚：
- 哪个页面。
- 哪个状态。
- 哪个尺寸。
- 哪个用户路径。
- 哪个命令通过才算完成。
错误 4：规则只写在聊天里
如果同一条规则重复出现 3 次，就该沉淀。
沉淀顺序：
- 只是这次任务：写在当前 prompt。
- 每次都要遵守：写进
AGENTS.md。 - 细节很长：写进
docs/。 - 流程重复：做成 skill。
- 可以机械判断：做成 hooks / rules。
- 需要外部系统：接 MCP。
错误 5：不看 diff 就提交
让 Codex 改完后，至少看一下：
git status --shortgit diff --statgit diff --check如果变更多，再看关键文件 diff。相信工具，但别把方向盘拆了。
一个小团队可以这样落地
如果你刚开始，不需要一天内搭完整套体系。按这个顺序来：
- 在仓库根目录写一个简洁的
AGENTS.md。 - 把常用验证命令写进去。
- 把 3 到 5 条真正重要的架构红线写进去。
- 准备几个常用 prompt 模板。
- 每次 Codex 重复犯错，就把规则沉淀到合适位置。
- 当某个流程重复 3 次以上，再考虑做 skill。
- 当需要外部系统事实，再接 MCP。
- 当危险操作或安全边界问题反复出现，再配 hooks / rules。
不要一上来就追求“全自动 AI 工程平台”。先让它稳定帮你改代码、跑检查、说清楚结果。自动化是一层层长出来的，不是喊一声“智能化”就从天花板掉下来。
给 Codex 的好任务长什么样
一个好任务通常具备这些信息：
- 有明确目标。
- 有相关入口。
- 有不做范围。
- 有约束。
- 有验证方式。
- 有期望输出格式。
示例：
目标：修复文章详情页移动端标题换行后遮挡作者信息的问题。 背景：- 页面入口：/posts/[slug]- 相关组件可能在 `src/components/PostHeader.tsx`- 只影响移动端，桌面端当前表现正常。 约束：- 不改文章数据结构。- 不引入新的 UI 库。- 尽量沿用现有 CSS 变量和断点。 验证：- 运行前端类型检查。- 给出移动端 375px 和 430px 宽度下的人工验收步骤。 交付：- 说明改动文件。- 说明验证结果。- 说明剩余风险。这类 prompt 很少浪费回合，因为它把“该去哪、别去哪、怎么判断做完”都说清楚了。
给 Codex 的坏任务长什么样
这个页面怪怪的，修一下。这不是需求，这是悬疑片开头。
如果你真的只知道“怪怪的”，也可以这样写：
这个页面看起来不对，但我还不确定原因。请先只读检查，不要改文件。 请帮我：- 找出最可能的问题点。- 引用具体文件和代码。- 给出 2 到 3 个修复方案。- 标注每个方案的风险和验证方式。不知道问题没关系，别让 Codex 带着不知道的问题直接动手就行。
公开教程里最值得带走的 checklist
开工前：
- 这次是小改、功能、bug、审查、文档，还是提交？
- 需要 Codex 先计划吗？
- 有没有必须遵守的架构或安全边界？
- 有没有需要查官方文档的外部事实？
工作中：
- 是否先看了当前代码事实？
- 是否只改相关文件？
- 是否避免了无关重构？
- 是否没有输出敏感信息？
交付前：
- diff 是否符合预期？
- 是否运行了最小验证？
- 没跑的验证是否说明原因？
- 用户可见变化是否给了人工验收路径？
- 剩余风险是否说清楚？
长期维护：
- 重复错误是否写进
AGENTS.md？ - 长规则是否放进
docs/？ - 重复流程是否适合 skill？
- 机械检查是否适合 hooks / rules？
- 外部系统是否需要 MCP？
官方资料
下面这些资料适合继续深入：
最后一句
Codex 最擅长的不是“替你思考一切”，而是在你给出清晰目标、边界和反馈后，把大量具体工作推进得又快又稳。
把它当成会干活的协作者，而不是会读心的魔法按钮。你负责方向盘，它负责踩油门、看仪表、提醒路况。这样开起来，才不会一脚油门冲进需求沼泽。
术语解释
下表按术语在正文中的首次出现顺序排列。