【Codex】Part 12 — Codex Best Practices

bryant_meng2026-08-13 8:29

文章目录

  • [第十二章 Codex 最佳实践](#第十二章 Codex 最佳实践)
  • [12.1 推荐项目结构](#12.1 推荐项目结构)
  • [12.2 `AGENTS.md` 编写原则](#12.2 AGENTS.md 编写原则)
    • [12.2.1 少即是多](#12.2.1 少即是多)
    • [12.2.2 命令必须可复制执行](#12.2.2 命令必须可复制执行)
    • [12.2.3 给非直观规则写原因](#12.2.3 给非直观规则写原因)
    • [12.2.4 分层规则靠近代码](#12.2.4 分层规则靠近代码)
  • [12.3 Skills 的最佳实践](#12.3 Skills 的最佳实践)
    • [12.3.1 什么时候应该写 Skill](#12.3.1 什么时候应该写 Skill)
    • [12.3.2 Skill 要小而专](#12.3.2 Skill 要小而专)
    • [12.3.3 Skill 触发词要明确](#12.3.3 Skill 触发词要明确)
  • [12.4 MCP 的最佳实践](#12.4 MCP 的最佳实践)
  • [12.5 沙箱与审批策略](#12.5 沙箱与审批策略)
  • [12.6 审查、修改、验证闭环](#12.6 审查、修改、验证闭环)
  • [12.7 团队协作模式](#12.7 团队协作模式)
  • [12.8 上下文与执行效率](#12.8 上下文与执行效率)
  • [12.9 常见反模式](#12.9 常见反模式)
  • [12.10 章节速查](#12.10 章节速查)

第十二章 Codex 最佳实践

本章讨论如何把 Codex 代理（agent）用成稳定、可复用、可治理的工程能力，而不是一次性的聊天工具。

本章面向已经开始在真实项目中使用 Codex 的个人开发者和团队。核心目标只有一个：让 Codex 获得正确上下文（context）、遵守明确边界、满足完成条件（acceptance criteria），并把成功经验沉淀为 AGENTS.md、Skills、MCP 配置和团队规范。

12.1 推荐项目结构

Codex 的表现很大程度取决于它能否快速理解项目。好的目录结构不是为了让人看起来整齐，而是为了让 Agent 能自动发现规则、命令、边界和可复用工作流。
#mermaid-svg-RcZ12STgF8lDK11D{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-RcZ12STgF8lDK11D .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-RcZ12STgF8lDK11D .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-RcZ12STgF8lDK11D .error-icon{fill:#552222;}#mermaid-svg-RcZ12STgF8lDK11D .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-RcZ12STgF8lDK11D .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-RcZ12STgF8lDK11D .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-RcZ12STgF8lDK11D .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-RcZ12STgF8lDK11D .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-RcZ12STgF8lDK11D .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-RcZ12STgF8lDK11D .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-RcZ12STgF8lDK11D .marker{fill:#333333;stroke:#333333;}#mermaid-svg-RcZ12STgF8lDK11D .marker.cross{stroke:#333333;}#mermaid-svg-RcZ12STgF8lDK11D svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-RcZ12STgF8lDK11D p{margin:0;}#mermaid-svg-RcZ12STgF8lDK11D .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-RcZ12STgF8lDK11D .cluster-label text{fill:#333;}#mermaid-svg-RcZ12STgF8lDK11D .cluster-label span{color:#333;}#mermaid-svg-RcZ12STgF8lDK11D .cluster-label span p{background-color:transparent;}#mermaid-svg-RcZ12STgF8lDK11D .label text,#mermaid-svg-RcZ12STgF8lDK11D span{fill:#333;color:#333;}#mermaid-svg-RcZ12STgF8lDK11D .node rect,#mermaid-svg-RcZ12STgF8lDK11D .node circle,#mermaid-svg-RcZ12STgF8lDK11D .node ellipse,#mermaid-svg-RcZ12STgF8lDK11D .node polygon,#mermaid-svg-RcZ12STgF8lDK11D .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-RcZ12STgF8lDK11D .rough-node .label text,#mermaid-svg-RcZ12STgF8lDK11D .node .label text,#mermaid-svg-RcZ12STgF8lDK11D .image-shape .label,#mermaid-svg-RcZ12STgF8lDK11D .icon-shape .label{text-anchor:middle;}#mermaid-svg-RcZ12STgF8lDK11D .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-RcZ12STgF8lDK11D .rough-node .label,#mermaid-svg-RcZ12STgF8lDK11D .node .label,#mermaid-svg-RcZ12STgF8lDK11D .image-shape .label,#mermaid-svg-RcZ12STgF8lDK11D .icon-shape .label{text-align:center;}#mermaid-svg-RcZ12STgF8lDK11D .node.clickable{cursor:pointer;}#mermaid-svg-RcZ12STgF8lDK11D .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-RcZ12STgF8lDK11D .arrowheadPath{fill:#333333;}#mermaid-svg-RcZ12STgF8lDK11D .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-RcZ12STgF8lDK11D .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-RcZ12STgF8lDK11D .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RcZ12STgF8lDK11D .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-RcZ12STgF8lDK11D .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RcZ12STgF8lDK11D .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-RcZ12STgF8lDK11D .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-RcZ12STgF8lDK11D .cluster text{fill:#333;}#mermaid-svg-RcZ12STgF8lDK11D .cluster span{color:#333;}#mermaid-svg-RcZ12STgF8lDK11D div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-RcZ12STgF8lDK11D .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-RcZ12STgF8lDK11D rect.text{fill:none;stroke-width:0;}#mermaid-svg-RcZ12STgF8lDK11D .icon-shape,#mermaid-svg-RcZ12STgF8lDK11D .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-RcZ12STgF8lDK11D .icon-shape p,#mermaid-svg-RcZ12STgF8lDK11D .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-RcZ12STgF8lDK11D .icon-shape .label rect,#mermaid-svg-RcZ12STgF8lDK11D .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-RcZ12STgF8lDK11D .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-RcZ12STgF8lDK11D .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-RcZ12STgF8lDK11D :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-RcZ12STgF8lDK11D .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-RcZ12STgF8lDK11D .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-RcZ12STgF8lDK11D .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-RcZ12STgF8lDK11D .art>*{fill:#f1f5f9!important;stroke:#64748b!important;stroke-width:1px!important;color:#0f172a!important;}#mermaid-svg-RcZ12STgF8lDK11D .art span{fill:#f1f5f9!important;stroke:#64748b!important;stroke-width:1px!important;color:#0f172a!important;}#mermaid-svg-RcZ12STgF8lDK11D .art tspan{fill:#0f172a!important;}#mermaid-svg-RcZ12STgF8lDK11D .ai>*{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-RcZ12STgF8lDK11D .ai span{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-RcZ12STgF8lDK11D .ai tspan{fill:#78350f!important;} project/
AGENTS.md

仓库级约定、命令、边界、完成标准
.codex/

项目级 Codex 配置
config.toml

模型、审批、沙箱、MCP 等配置
.agents/skills/

项目或团队 Skills
review/SKILL.md

代码审查流程
release/SKILL.md

发布检查流程
docs/

架构、API、运行手册
scripts/

可复制执行的脚本
src/
tests/
packages/

Monorepo 子包
packages/*/AGENTS.md

子目录局部规则

推荐的职责划分：

文件或目录 建议用途
AGENTS.md 仓库级规则、构建/测试命令、代码边界、完成标准
packages/*/AGENTS.md Monorepo 中更靠近任务目录的局部规则
.codex/config.toml 项目级 Codex 配置，仅在可信项目中加载
.agents/skills/<name>/SKILL.md 可复用任务流程，如审查、发布、迁移、数据清理
docs/ 长文档、架构说明、API 参考；在 AGENTS.md 中只放索引
scripts/ Codex 和人类都能直接运行的验证、生成、部署脚本

常见错误：

  • 把所有规范堆进根 AGENTS.md，导致上下文被低价值规则占满。
  • 把 README、完整 API 文档或长篇背景资料复制进 AGENTS.md。
  • 在团队项目中只维护个人本地配置，导致不同成员的 Codex 行为不一致。
  • 把密钥、Token、私有凭据写进 AGENTS.md、Skills 或 MCP 配置文件。

在视觉算法仓库中，可以进一步明确 datasets/、configs/、weights/、runs/ 和评估脚本的职责，但不要假设所有项目都采用同一目录布局。写进文档的应是当前仓库已经验证的真实结构。

tips：config.toml 是"设置"，AGENTS.md 是"规矩"，Skill 是"做事方法"。

12.2 AGENTS.md 编写原则

AGENTS.md 是 Codex 自动加载的开放格式说明文件。Codex 启动时会组合全局规则与从项目根目录到当前工作目录之间的项目规则；更靠近当前目录的规则出现在后面，可以覆盖更宽泛的约定。每个目录优先检查 AGENTS.override.md，再检查 AGENTS.md。这条指令链通常在每次运行或 TUI 会话启动时构建，修改后应在新会话中核对是否生效。

它最适合放"每次任务都应遵守"的短规则，而不是百科式项目文档。

12.2.1 少即是多

一份好的 AGENTS.md 应从最少但足够的规则开始，后续只在出现重复错误时增加内容。不要用固定行数判断质量；规则越多，越容易互相冲突，也越容易稀释真正重要的约束。

建议包含：

  • 仓库结构和关键目录。
  • 安装、构建、测试、lint、格式化命令。
  • 代码风格中真正有本项目差异的部分。
  • 高风险路径和禁止修改区域。
  • PR 或交付前的验证标准。
  • 需要调用的 Skills 或外部文档索引。

不建议包含：

  • 通用语言风格常识，如"变量名要清晰"。
  • 完整 API 参考、完整数据库 schema、完整 README。
  • 与项目无关的个人偏好。
  • 没有执行意义的口号，如"写高质量代码"。

12.2.2 命令必须可复制执行

模糊命令会迫使 Agent 猜测。把命令写成可直接复制执行的形式，可以减少无效尝试。

错误示例：

markdown 复制代码 
# Testing
Run tests before committing.

更好的写法：

markdown 复制代码 
# Testing
- Unit tests: `pytest tests/unit -x --tb=short`
- Integration tests: `docker compose -f tests/docker-compose.yml up -d && pytest tests/integration -x --tb=long`
- Frontend checks: `pnpm lint && pnpm test -- --run`

视觉算法项目还应把实验完成条件写成可验证要求：

markdown 复制代码 
# Vision experiment rules
- Before training, record the exact data configuration, checkpoint, and command.
- Change one declared experimental variable at a time when comparing with a baseline.
- A YOLO run is complete only after the target validation split has formal metrics and a loadable checkpoint.
- Do not infer architecture from a run name or checkpoint size; inspect the saved configuration or checkpoint metadata.

视觉实验规则

  • 在训练前，记录确切的数据配置、检查点（checkpoint）和命令行。
  • 与基线进行对比时，每次只更改一个声明的实验变量。
  • 只有当目标验证集拥有正式的指标和可加载的检查点时，YOLO 运行才算完成。
  • 切勿仅凭运行名称或检查点大小来推断架构；应检查保存的配置或检查点元数据。

12.2.3 给非直观规则写原因

当规则不是行业通用约定时，给一行 Reason:。这样 Codex 能理解约束目的，避免在相邻场景中机械套用。

markdown 复制代码 
# Logging
- Production logs must start with an ISO-8601 timestamp.
  Reason: downstream log aggregation parses the timestamp field directly.

# Boundaries
- Do not modify files under `src/generated/`.
  Reason: generated files are overwritten by `pnpm generate`.

12.2.4 分层规则靠近代码

在单仓多包（monorepo） 中，根 AGENTS.md 只放全局规则；包级规则放到对应包目录。
#mermaid-svg-hES1uFS5hZPlB4cA{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-hES1uFS5hZPlB4cA .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-hES1uFS5hZPlB4cA .error-icon{fill:#552222;}#mermaid-svg-hES1uFS5hZPlB4cA .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-hES1uFS5hZPlB4cA .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-hES1uFS5hZPlB4cA .marker{fill:#333333;stroke:#333333;}#mermaid-svg-hES1uFS5hZPlB4cA .marker.cross{stroke:#333333;}#mermaid-svg-hES1uFS5hZPlB4cA svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-hES1uFS5hZPlB4cA p{margin:0;}#mermaid-svg-hES1uFS5hZPlB4cA .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-hES1uFS5hZPlB4cA .cluster-label text{fill:#333;}#mermaid-svg-hES1uFS5hZPlB4cA .cluster-label span{color:#333;}#mermaid-svg-hES1uFS5hZPlB4cA .cluster-label span p{background-color:transparent;}#mermaid-svg-hES1uFS5hZPlB4cA .label text,#mermaid-svg-hES1uFS5hZPlB4cA span{fill:#333;color:#333;}#mermaid-svg-hES1uFS5hZPlB4cA .node rect,#mermaid-svg-hES1uFS5hZPlB4cA .node circle,#mermaid-svg-hES1uFS5hZPlB4cA .node ellipse,#mermaid-svg-hES1uFS5hZPlB4cA .node polygon,#mermaid-svg-hES1uFS5hZPlB4cA .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-hES1uFS5hZPlB4cA .rough-node .label text,#mermaid-svg-hES1uFS5hZPlB4cA .node .label text,#mermaid-svg-hES1uFS5hZPlB4cA .image-shape .label,#mermaid-svg-hES1uFS5hZPlB4cA .icon-shape .label{text-anchor:middle;}#mermaid-svg-hES1uFS5hZPlB4cA .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-hES1uFS5hZPlB4cA .rough-node .label,#mermaid-svg-hES1uFS5hZPlB4cA .node .label,#mermaid-svg-hES1uFS5hZPlB4cA .image-shape .label,#mermaid-svg-hES1uFS5hZPlB4cA .icon-shape .label{text-align:center;}#mermaid-svg-hES1uFS5hZPlB4cA .node.clickable{cursor:pointer;}#mermaid-svg-hES1uFS5hZPlB4cA .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-hES1uFS5hZPlB4cA .arrowheadPath{fill:#333333;}#mermaid-svg-hES1uFS5hZPlB4cA .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-hES1uFS5hZPlB4cA .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-hES1uFS5hZPlB4cA .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hES1uFS5hZPlB4cA .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-hES1uFS5hZPlB4cA .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hES1uFS5hZPlB4cA .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-hES1uFS5hZPlB4cA .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-hES1uFS5hZPlB4cA .cluster text{fill:#333;}#mermaid-svg-hES1uFS5hZPlB4cA .cluster span{color:#333;}#mermaid-svg-hES1uFS5hZPlB4cA div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-hES1uFS5hZPlB4cA .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-hES1uFS5hZPlB4cA rect.text{fill:none;stroke-width:0;}#mermaid-svg-hES1uFS5hZPlB4cA .icon-shape,#mermaid-svg-hES1uFS5hZPlB4cA .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-hES1uFS5hZPlB4cA .icon-shape p,#mermaid-svg-hES1uFS5hZPlB4cA .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-hES1uFS5hZPlB4cA .icon-shape .label rect,#mermaid-svg-hES1uFS5hZPlB4cA .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-hES1uFS5hZPlB4cA .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-hES1uFS5hZPlB4cA .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-hES1uFS5hZPlB4cA :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-hES1uFS5hZPlB4cA .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-hES1uFS5hZPlB4cA .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-hES1uFS5hZPlB4cA .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-hES1uFS5hZPlB4cA .art>*{fill:#f1f5f9!important;stroke:#64748b!important;stroke-width:1px!important;color:#0f172a!important;}#mermaid-svg-hES1uFS5hZPlB4cA .art span{fill:#f1f5f9!important;stroke:#64748b!important;stroke-width:1px!important;color:#0f172a!important;}#mermaid-svg-hES1uFS5hZPlB4cA .art tspan{fill:#0f172a!important;} AGENTS.md

全局规则: 包管理器、提交规范、CI 命令
packages/web/AGENTS.md

React、测试、样式边界
packages/api/AGENTS.md

API、数据库、认证边界
packages/shared/AGENTS.md

公共类型、兼容性、发布约束

Codex 从项目根目录沿当前工作目录向下读取规则。因此，从 packages/api 启动时会组合根规则和 API 规则，而不会读取平级 packages/web 的文件。需要完全替换同目录普通规则时，可使用 AGENTS.override.md。

tips：Monorepo = 一个仓库装多个项目；Multirepo = 一个项目一个仓库
ai-project.git

├── detection

├── depth

├── segmentation

└── common

12.3 Skills 的最佳实践

Skill 适合沉淀"可重复执行的方法"，而不是存放项目背景。一个 Skill 通常是一个目录，包含 SKILL.md 以及可选的脚本、模板、示例或参考材料。

12.3.1 什么时候应该写 Skill

符合以下条件时，适合抽成 Skill：

  • 任务会重复出现，例如周报、发布检查、代码审查、数据清理。
  • 成功依赖固定步骤，而不是单次创意发挥。
  • 需要配套脚本、模板、检查清单或示例。
  • 触发条件可以用一句清晰描述表达。

不适合写 Skill 的情况：

  • 只是一次性任务。
  • 只是几句项目约定，放进 AGENTS.md 更合适。
  • 流程还没有跑通，尚未形成稳定经验。

12.3.2 Skill 要小而专

一个 Skill 只做一类事。例如：

需求 推荐 Skill 不推荐
检查 COCO 图像与标签 coco-dataset-audit 把标注、训练和部署全部混在一起
核验目标检测实验 detection-run-audit 泛化成没有边界的 vision-helper
检查分类类别映射 classification-label-audit 与训练调参流程耦合
验证分割模型导出 segmentation-export-verify 混入设备侧性能测试

12.3.3 Skill 触发词要明确

SKILL.md 的 description 会进入 Codex 的初始技能列表。描述应前置关键词和边界，让 Codex 能在上下文有限时仍然匹配正确。

markdown 复制代码 
---
name: release-checklist
description: Run the release readiness checklist for this repository: changelog, version bump, CI, migration notes, and rollback plan.
---

12.4 MCP 的最佳实践

模型上下文协议（Model Context Protocol，MCP）适合把 Codex 接到外部系统：GitHub、Issue 系统、实验平台、数据集目录、内部文档和日志平台等。它不是越多越好；工具定义和权限面越大，选择、配置和治理就越复杂。
#mermaid-svg-0yEeB5mAPnuapLQT{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-0yEeB5mAPnuapLQT .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-0yEeB5mAPnuapLQT .error-icon{fill:#552222;}#mermaid-svg-0yEeB5mAPnuapLQT .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-0yEeB5mAPnuapLQT .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-0yEeB5mAPnuapLQT .marker{fill:#333333;stroke:#333333;}#mermaid-svg-0yEeB5mAPnuapLQT .marker.cross{stroke:#333333;}#mermaid-svg-0yEeB5mAPnuapLQT svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-0yEeB5mAPnuapLQT p{margin:0;}#mermaid-svg-0yEeB5mAPnuapLQT .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-0yEeB5mAPnuapLQT .cluster-label text{fill:#333;}#mermaid-svg-0yEeB5mAPnuapLQT .cluster-label span{color:#333;}#mermaid-svg-0yEeB5mAPnuapLQT .cluster-label span p{background-color:transparent;}#mermaid-svg-0yEeB5mAPnuapLQT .label text,#mermaid-svg-0yEeB5mAPnuapLQT span{fill:#333;color:#333;}#mermaid-svg-0yEeB5mAPnuapLQT .node rect,#mermaid-svg-0yEeB5mAPnuapLQT .node circle,#mermaid-svg-0yEeB5mAPnuapLQT .node ellipse,#mermaid-svg-0yEeB5mAPnuapLQT .node polygon,#mermaid-svg-0yEeB5mAPnuapLQT .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-0yEeB5mAPnuapLQT .rough-node .label text,#mermaid-svg-0yEeB5mAPnuapLQT .node .label text,#mermaid-svg-0yEeB5mAPnuapLQT .image-shape .label,#mermaid-svg-0yEeB5mAPnuapLQT .icon-shape .label{text-anchor:middle;}#mermaid-svg-0yEeB5mAPnuapLQT .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-0yEeB5mAPnuapLQT .rough-node .label,#mermaid-svg-0yEeB5mAPnuapLQT .node .label,#mermaid-svg-0yEeB5mAPnuapLQT .image-shape .label,#mermaid-svg-0yEeB5mAPnuapLQT .icon-shape .label{text-align:center;}#mermaid-svg-0yEeB5mAPnuapLQT .node.clickable{cursor:pointer;}#mermaid-svg-0yEeB5mAPnuapLQT .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-0yEeB5mAPnuapLQT .arrowheadPath{fill:#333333;}#mermaid-svg-0yEeB5mAPnuapLQT .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-0yEeB5mAPnuapLQT .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-0yEeB5mAPnuapLQT .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0yEeB5mAPnuapLQT .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-0yEeB5mAPnuapLQT .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0yEeB5mAPnuapLQT .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-0yEeB5mAPnuapLQT .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-0yEeB5mAPnuapLQT .cluster text{fill:#333;}#mermaid-svg-0yEeB5mAPnuapLQT .cluster span{color:#333;}#mermaid-svg-0yEeB5mAPnuapLQT div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-0yEeB5mAPnuapLQT .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-0yEeB5mAPnuapLQT rect.text{fill:none;stroke-width:0;}#mermaid-svg-0yEeB5mAPnuapLQT .icon-shape,#mermaid-svg-0yEeB5mAPnuapLQT .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-0yEeB5mAPnuapLQT .icon-shape p,#mermaid-svg-0yEeB5mAPnuapLQT .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-0yEeB5mAPnuapLQT .icon-shape .label rect,#mermaid-svg-0yEeB5mAPnuapLQT .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-0yEeB5mAPnuapLQT .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-0yEeB5mAPnuapLQT .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-0yEeB5mAPnuapLQT :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-0yEeB5mAPnuapLQT .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-0yEeB5mAPnuapLQT .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-0yEeB5mAPnuapLQT .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-0yEeB5mAPnuapLQT .test>*{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-0yEeB5mAPnuapLQT .test span{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-0yEeB5mAPnuapLQT .test tspan{fill:#14532b!important;}#mermaid-svg-0yEeB5mAPnuapLQT .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-0yEeB5mAPnuapLQT .pain span{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-0yEeB5mAPnuapLQT .pain tspan{fill:#7f1d1d!important;} 否
是
是
否
当前任务
需要外部系统吗?
使用内置文件、搜索、Shell、patch 工具
是否有稳定 MCP?
启用最小 MCP 集合
用受控脚本或 API 客户端封装
记录权限、凭据来源、使用范围

MCP 配置建议：

  • 只启用当前项目确实需要的服务器。
  • 为读写工具区分权限，不把数据库写权限暴露给普通开发任务。
  • 凭据走环境变量、Secret Manager 或连接器授权，不写入仓库。
  • 对会产生副作用的工具保留审批或审计。
  • 团队共享 MCP 前，先写清楚用途、权限、联系人和故障处理方式。

例如，目标检测任务只需要读取实验记录时，不应同时授予"删除训练运行"或"覆盖模型注册表"的权限。读取 COCO 数据版本、查询分类实验指标和发布分割模型也应分别采用最小权限（least privilege）。

12.5 沙箱与审批策略

Codex 的沙箱（sandbox）和审批策略（approval policy）是两组独立控制：沙箱决定命令能访问什么，审批策略决定何时向用户请求授权。一般原则是：越接近生产、凭据、批量删除或跨仓库修改，越应该收紧权限并增加验证。
#mermaid-svg-LBDGP2qS3bUjVfQZ{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-LBDGP2qS3bUjVfQZ .error-icon{fill:#552222;}#mermaid-svg-LBDGP2qS3bUjVfQZ .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-LBDGP2qS3bUjVfQZ .marker{fill:#333333;stroke:#333333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .marker.cross{stroke:#333333;}#mermaid-svg-LBDGP2qS3bUjVfQZ svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-LBDGP2qS3bUjVfQZ p{margin:0;}#mermaid-svg-LBDGP2qS3bUjVfQZ .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster-label text{fill:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster-label span{color:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster-label span p{background-color:transparent;}#mermaid-svg-LBDGP2qS3bUjVfQZ .label text,#mermaid-svg-LBDGP2qS3bUjVfQZ span{fill:#333;color:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .node rect,#mermaid-svg-LBDGP2qS3bUjVfQZ .node circle,#mermaid-svg-LBDGP2qS3bUjVfQZ .node ellipse,#mermaid-svg-LBDGP2qS3bUjVfQZ .node polygon,#mermaid-svg-LBDGP2qS3bUjVfQZ .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .rough-node .label text,#mermaid-svg-LBDGP2qS3bUjVfQZ .node .label text,#mermaid-svg-LBDGP2qS3bUjVfQZ .image-shape .label,#mermaid-svg-LBDGP2qS3bUjVfQZ .icon-shape .label{text-anchor:middle;}#mermaid-svg-LBDGP2qS3bUjVfQZ .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .rough-node .label,#mermaid-svg-LBDGP2qS3bUjVfQZ .node .label,#mermaid-svg-LBDGP2qS3bUjVfQZ .image-shape .label,#mermaid-svg-LBDGP2qS3bUjVfQZ .icon-shape .label{text-align:center;}#mermaid-svg-LBDGP2qS3bUjVfQZ .node.clickable{cursor:pointer;}#mermaid-svg-LBDGP2qS3bUjVfQZ .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .arrowheadPath{fill:#333333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-LBDGP2qS3bUjVfQZ .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-LBDGP2qS3bUjVfQZ .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-LBDGP2qS3bUjVfQZ .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster text{fill:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ .cluster span{color:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-LBDGP2qS3bUjVfQZ .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-LBDGP2qS3bUjVfQZ rect.text{fill:none;stroke-width:0;}#mermaid-svg-LBDGP2qS3bUjVfQZ .icon-shape,#mermaid-svg-LBDGP2qS3bUjVfQZ .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-LBDGP2qS3bUjVfQZ .icon-shape p,#mermaid-svg-LBDGP2qS3bUjVfQZ .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-LBDGP2qS3bUjVfQZ .icon-shape .label rect,#mermaid-svg-LBDGP2qS3bUjVfQZ .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-LBDGP2qS3bUjVfQZ .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-LBDGP2qS3bUjVfQZ .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-LBDGP2qS3bUjVfQZ :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-LBDGP2qS3bUjVfQZ .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-LBDGP2qS3bUjVfQZ .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-LBDGP2qS3bUjVfQZ .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-LBDGP2qS3bUjVfQZ .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-LBDGP2qS3bUjVfQZ .pain span{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-LBDGP2qS3bUjVfQZ .pain tspan{fill:#7f1d1d!important;} 选择 approval_policy
untrusted

已知安全的只读命令可直接运行
on-request

需要时请求授权
never

不发起审批请求
选择 sandbox_mode
read-only

只读探索与审查
workspace-write

允许工作区写入
danger-full-access

不使用 Codex 沙箱
任务风险与所需能力
共同形成执行边界

建议配置：

toml 复制代码 
# 可信仓库中确实需要写入时的交互式配置
sandbox_mode = "workspace-write"
approval_policy = "on-request"
toml 复制代码 
# 仅用于隔离环境或用户明确授权的高风险组合
sandbox_mode = "danger-full-access"
approval_policy = "never"

approval_policy = "never" 表示 Codex 不会弹出审批请求，并不等于自动获得沙箱外权限。danger-full-access 则不使用 Codex 沙箱；操作系统、容器和外部服务自身的权限仍可能继续限制命令。

使用 Full Access 时要明确前提：它适合已经隔离的容器、虚拟机（Virtual Machine，VM）、临时工作区、专门测试环境，或用户明确授权的维护任务。它不应成为处理秘密、生产数据或不可回滚操作时的默认选择。

12.6 审查、修改、验证闭环

把 Codex 当成工程同事，而不是文本生成器。重要任务应形成审查闭环（review loop）：
#mermaid-svg-4ljnRMm49IpUKCfM{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-4ljnRMm49IpUKCfM .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-4ljnRMm49IpUKCfM .error-icon{fill:#552222;}#mermaid-svg-4ljnRMm49IpUKCfM .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-4ljnRMm49IpUKCfM .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-4ljnRMm49IpUKCfM .marker{fill:#333333;stroke:#333333;}#mermaid-svg-4ljnRMm49IpUKCfM .marker.cross{stroke:#333333;}#mermaid-svg-4ljnRMm49IpUKCfM svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-4ljnRMm49IpUKCfM p{margin:0;}#mermaid-svg-4ljnRMm49IpUKCfM .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-4ljnRMm49IpUKCfM .cluster-label text{fill:#333;}#mermaid-svg-4ljnRMm49IpUKCfM .cluster-label span{color:#333;}#mermaid-svg-4ljnRMm49IpUKCfM .cluster-label span p{background-color:transparent;}#mermaid-svg-4ljnRMm49IpUKCfM .label text,#mermaid-svg-4ljnRMm49IpUKCfM span{fill:#333;color:#333;}#mermaid-svg-4ljnRMm49IpUKCfM .node rect,#mermaid-svg-4ljnRMm49IpUKCfM .node circle,#mermaid-svg-4ljnRMm49IpUKCfM .node ellipse,#mermaid-svg-4ljnRMm49IpUKCfM .node polygon,#mermaid-svg-4ljnRMm49IpUKCfM .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-4ljnRMm49IpUKCfM .rough-node .label text,#mermaid-svg-4ljnRMm49IpUKCfM .node .label text,#mermaid-svg-4ljnRMm49IpUKCfM .image-shape .label,#mermaid-svg-4ljnRMm49IpUKCfM .icon-shape .label{text-anchor:middle;}#mermaid-svg-4ljnRMm49IpUKCfM .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-4ljnRMm49IpUKCfM .rough-node .label,#mermaid-svg-4ljnRMm49IpUKCfM .node .label,#mermaid-svg-4ljnRMm49IpUKCfM .image-shape .label,#mermaid-svg-4ljnRMm49IpUKCfM .icon-shape .label{text-align:center;}#mermaid-svg-4ljnRMm49IpUKCfM .node.clickable{cursor:pointer;}#mermaid-svg-4ljnRMm49IpUKCfM .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-4ljnRMm49IpUKCfM .arrowheadPath{fill:#333333;}#mermaid-svg-4ljnRMm49IpUKCfM .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-4ljnRMm49IpUKCfM .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-4ljnRMm49IpUKCfM .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-4ljnRMm49IpUKCfM .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-4ljnRMm49IpUKCfM .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-4ljnRMm49IpUKCfM .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-4ljnRMm49IpUKCfM .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-4ljnRMm49IpUKCfM .cluster text{fill:#333;}#mermaid-svg-4ljnRMm49IpUKCfM .cluster span{color:#333;}#mermaid-svg-4ljnRMm49IpUKCfM div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-4ljnRMm49IpUKCfM .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-4ljnRMm49IpUKCfM rect.text{fill:none;stroke-width:0;}#mermaid-svg-4ljnRMm49IpUKCfM .icon-shape,#mermaid-svg-4ljnRMm49IpUKCfM .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-4ljnRMm49IpUKCfM .icon-shape p,#mermaid-svg-4ljnRMm49IpUKCfM .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-4ljnRMm49IpUKCfM .icon-shape .label rect,#mermaid-svg-4ljnRMm49IpUKCfM .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-4ljnRMm49IpUKCfM .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-4ljnRMm49IpUKCfM .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-4ljnRMm49IpUKCfM :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-4ljnRMm49IpUKCfM .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-4ljnRMm49IpUKCfM .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-4ljnRMm49IpUKCfM .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-4ljnRMm49IpUKCfM .test>*{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-4ljnRMm49IpUKCfM .test span{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-4ljnRMm49IpUKCfM .test tspan{fill:#14532b!important;}#mermaid-svg-4ljnRMm49IpUKCfM .ai>*{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-4ljnRMm49IpUKCfM .ai span{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-4ljnRMm49IpUKCfM .ai tspan{fill:#78350f!important;} 否
是
需求
计划
修改
审查
修复
验证
必需验证和证据是否通过？
交付

验证命令要按风险分层：

任务类型 最低验证
文档修改 Markdown 围栏成对、链接/图表语法检查、人工抽读关键段落
单文件代码修改 相关单元测试、lint 或类型检查
跨模块修改 受影响模块测试、集成测试、回归用例
安全或生产相关修改 审查记录、回滚方案、最小权限验证、人工确认点

视觉算法任务还要区分"过程正在运行"和"结果已经成立"：

  • 目标检测：确认权重可加载，并在指定 COCO 验证集上生成正式指标。
  • 图像分类：核对类别顺序、数据划分和每类结果，不能只看整体准确率。
  • 语义分割：核对掩码取值、忽略索引和评估口径，不能直接比较不同定义的交并比（Intersection over Union，IoU）。
  • 长时间训练：记录进程、日志推进、检查点和最新指标；仅显示 RUNNING 不代表训练正常推进。

12.7 团队协作模式

个人使用 Codex 时，靠提示词就能解决很多问题；团队使用时，应把反复验证有效的经验沉淀到可版本化资产中，并通过持续集成与持续交付（Continuous Integration and Continuous Delivery，CI/CD）独立验证交付物。
#mermaid-svg-zc7mOuqJqTF3hZ0A{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-zc7mOuqJqTF3hZ0A .error-icon{fill:#552222;}#mermaid-svg-zc7mOuqJqTF3hZ0A .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-zc7mOuqJqTF3hZ0A .marker{fill:#333333;stroke:#333333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .marker.cross{stroke:#333333;}#mermaid-svg-zc7mOuqJqTF3hZ0A svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-zc7mOuqJqTF3hZ0A p{margin:0;}#mermaid-svg-zc7mOuqJqTF3hZ0A .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster-label text{fill:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster-label span{color:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster-label span p{background-color:transparent;}#mermaid-svg-zc7mOuqJqTF3hZ0A .label text,#mermaid-svg-zc7mOuqJqTF3hZ0A span{fill:#333;color:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .node rect,#mermaid-svg-zc7mOuqJqTF3hZ0A .node circle,#mermaid-svg-zc7mOuqJqTF3hZ0A .node ellipse,#mermaid-svg-zc7mOuqJqTF3hZ0A .node polygon,#mermaid-svg-zc7mOuqJqTF3hZ0A .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .rough-node .label text,#mermaid-svg-zc7mOuqJqTF3hZ0A .node .label text,#mermaid-svg-zc7mOuqJqTF3hZ0A .image-shape .label,#mermaid-svg-zc7mOuqJqTF3hZ0A .icon-shape .label{text-anchor:middle;}#mermaid-svg-zc7mOuqJqTF3hZ0A .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .rough-node .label,#mermaid-svg-zc7mOuqJqTF3hZ0A .node .label,#mermaid-svg-zc7mOuqJqTF3hZ0A .image-shape .label,#mermaid-svg-zc7mOuqJqTF3hZ0A .icon-shape .label{text-align:center;}#mermaid-svg-zc7mOuqJqTF3hZ0A .node.clickable{cursor:pointer;}#mermaid-svg-zc7mOuqJqTF3hZ0A .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .arrowheadPath{fill:#333333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zc7mOuqJqTF3hZ0A .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-zc7mOuqJqTF3hZ0A .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zc7mOuqJqTF3hZ0A .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster text{fill:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A .cluster span{color:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-zc7mOuqJqTF3hZ0A .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-zc7mOuqJqTF3hZ0A rect.text{fill:none;stroke-width:0;}#mermaid-svg-zc7mOuqJqTF3hZ0A .icon-shape,#mermaid-svg-zc7mOuqJqTF3hZ0A .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-zc7mOuqJqTF3hZ0A .icon-shape p,#mermaid-svg-zc7mOuqJqTF3hZ0A .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-zc7mOuqJqTF3hZ0A .icon-shape .label rect,#mermaid-svg-zc7mOuqJqTF3hZ0A .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-zc7mOuqJqTF3hZ0A .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-zc7mOuqJqTF3hZ0A .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-zc7mOuqJqTF3hZ0A :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-zc7mOuqJqTF3hZ0A .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .ai>*{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .ai span{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .ai tspan{fill:#78350f!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .test>*{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .test span{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-zc7mOuqJqTF3hZ0A .test tspan{fill:#14532b!important;} 个人经验

有效提示词、排障步骤、检查清单
AGENTS.md

团队共享规则
Skills

可复用工作流
MCP 配置

外部系统能力与权限
治理

评审、版本、负责人、淘汰机制
团队使用 Codex 完成任务
CI/CD

独立验证交付物
结果与问题反馈

团队落地建议：

  • 用 PR 管理 AGENTS.md 和团队 Skills，避免口头约定失效。
  • 每个 Skill 明确 owner、适用范围、测试方式和废弃条件。
  • 对高风险 MCP 服务器建立审批和审计。
  • 定期清理过时规则，尤其是路径、命令、依赖版本和部署流程。
  • 将"Codex 应该怎么验证完成"写进 AGENTS.md，而不是每次临时补充。

12.8 上下文与执行效率

常见的可控因素包括上下文是否聚焦、工具是否与任务相关、搜索范围是否合理，以及验证是否有针对性。不要为了追求"短"而删掉完成任务所需的约束和证据。

优化原则：

  • 把稳定规则放前面，把任务特定上下文放后面。
  • 不让根 AGENTS.md 承担长文档职责。
  • 少启用与当前任务无关的 MCP 服务器。
  • 用 rg、测试过滤器、构建缓存等工程工具缩小搜索和验证范围。
  • 对复杂任务先做计划和影响面分析，再进入修改。
  • 对重复任务抽成 Skill，减少每次重新解释流程的成本。
  • 处理 COCO 等大数据集时先检查目录和样本，再决定是否需要全量扫描。
  • 比较模型时固定数据、预处理和评估口径，只改变已经声明的实验变量。

#mermaid-svg-Os8aR9FhCm7qjSjU{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-Os8aR9FhCm7qjSjU .error-icon{fill:#552222;}#mermaid-svg-Os8aR9FhCm7qjSjU .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-Os8aR9FhCm7qjSjU .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-Os8aR9FhCm7qjSjU .marker{fill:#333333;stroke:#333333;}#mermaid-svg-Os8aR9FhCm7qjSjU .marker.cross{stroke:#333333;}#mermaid-svg-Os8aR9FhCm7qjSjU svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-Os8aR9FhCm7qjSjU p{margin:0;}#mermaid-svg-Os8aR9FhCm7qjSjU .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster-label text{fill:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster-label span{color:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster-label span p{background-color:transparent;}#mermaid-svg-Os8aR9FhCm7qjSjU .label text,#mermaid-svg-Os8aR9FhCm7qjSjU span{fill:#333;color:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU .node rect,#mermaid-svg-Os8aR9FhCm7qjSjU .node circle,#mermaid-svg-Os8aR9FhCm7qjSjU .node ellipse,#mermaid-svg-Os8aR9FhCm7qjSjU .node polygon,#mermaid-svg-Os8aR9FhCm7qjSjU .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-Os8aR9FhCm7qjSjU .rough-node .label text,#mermaid-svg-Os8aR9FhCm7qjSjU .node .label text,#mermaid-svg-Os8aR9FhCm7qjSjU .image-shape .label,#mermaid-svg-Os8aR9FhCm7qjSjU .icon-shape .label{text-anchor:middle;}#mermaid-svg-Os8aR9FhCm7qjSjU .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-Os8aR9FhCm7qjSjU .rough-node .label,#mermaid-svg-Os8aR9FhCm7qjSjU .node .label,#mermaid-svg-Os8aR9FhCm7qjSjU .image-shape .label,#mermaid-svg-Os8aR9FhCm7qjSjU .icon-shape .label{text-align:center;}#mermaid-svg-Os8aR9FhCm7qjSjU .node.clickable{cursor:pointer;}#mermaid-svg-Os8aR9FhCm7qjSjU .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-Os8aR9FhCm7qjSjU .arrowheadPath{fill:#333333;}#mermaid-svg-Os8aR9FhCm7qjSjU .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-Os8aR9FhCm7qjSjU .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-Os8aR9FhCm7qjSjU .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Os8aR9FhCm7qjSjU .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-Os8aR9FhCm7qjSjU .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Os8aR9FhCm7qjSjU .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster text{fill:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU .cluster span{color:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-Os8aR9FhCm7qjSjU .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-Os8aR9FhCm7qjSjU rect.text{fill:none;stroke-width:0;}#mermaid-svg-Os8aR9FhCm7qjSjU .icon-shape,#mermaid-svg-Os8aR9FhCm7qjSjU .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-Os8aR9FhCm7qjSjU .icon-shape p,#mermaid-svg-Os8aR9FhCm7qjSjU .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-Os8aR9FhCm7qjSjU .icon-shape .label rect,#mermaid-svg-Os8aR9FhCm7qjSjU .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-Os8aR9FhCm7qjSjU .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-Os8aR9FhCm7qjSjU .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-Os8aR9FhCm7qjSjU :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-Os8aR9FhCm7qjSjU .pain>*{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .pain span{fill:#fee2e2!important;stroke:#dc2626!important;stroke-width:1px!important;color:#7f1d1d!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .pain tspan{fill:#7f1d1d!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .ai>*{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .ai span{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-Os8aR9FhCm7qjSjU .ai tspan{fill:#78350f!important;} 修剪
下次复用
低效上下文

长 AGENTS.md、无关工具、宽泛搜索
高效上下文

短规则、相关文件、最小 MCP
定向验证

只跑受影响测试
沉淀 Skill

复用稳定流程

12.9 常见反模式

反模式 问题 改法
"让 Codex 自己看着办" 缺少验收标准，容易跑偏 写清目标、范围、验证命令
根 AGENTS.md 过长 占用上下文，规则冲突 拆到子目录或文档索引
MCP 全量启用 工具定义膨胀，权限面扩大 每个项目只启用必要服务器
Skill 大而全 触发不准，维护困难 一类任务一个 Skill
不跑验证就交付 难以发现回归 按风险选择最小验证集
把生产权限给默认环境 风险不可控 使用最小权限、审批和审计
把秘密写进文本配置 容易泄露 使用环境变量、Secret Manager 或连接器授权
根据运行名猜模型结构 结论缺少证据 检查实际配置、日志或检查点元数据
把训练启动当成完成 可能没有正式结果 核对日志推进、权重和目标验证集指标

12.10 章节速查

#mermaid-svg-no2AXz8qBQW063AX{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-no2AXz8qBQW063AX .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-no2AXz8qBQW063AX .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-no2AXz8qBQW063AX .error-icon{fill:#552222;}#mermaid-svg-no2AXz8qBQW063AX .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-no2AXz8qBQW063AX .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-no2AXz8qBQW063AX .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-no2AXz8qBQW063AX .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-no2AXz8qBQW063AX .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-no2AXz8qBQW063AX .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-no2AXz8qBQW063AX .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-no2AXz8qBQW063AX .marker{fill:#333333;stroke:#333333;}#mermaid-svg-no2AXz8qBQW063AX .marker.cross{stroke:#333333;}#mermaid-svg-no2AXz8qBQW063AX svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-no2AXz8qBQW063AX p{margin:0;}#mermaid-svg-no2AXz8qBQW063AX .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-no2AXz8qBQW063AX .cluster-label text{fill:#333;}#mermaid-svg-no2AXz8qBQW063AX .cluster-label span{color:#333;}#mermaid-svg-no2AXz8qBQW063AX .cluster-label span p{background-color:transparent;}#mermaid-svg-no2AXz8qBQW063AX .label text,#mermaid-svg-no2AXz8qBQW063AX span{fill:#333;color:#333;}#mermaid-svg-no2AXz8qBQW063AX .node rect,#mermaid-svg-no2AXz8qBQW063AX .node circle,#mermaid-svg-no2AXz8qBQW063AX .node ellipse,#mermaid-svg-no2AXz8qBQW063AX .node polygon,#mermaid-svg-no2AXz8qBQW063AX .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-no2AXz8qBQW063AX .rough-node .label text,#mermaid-svg-no2AXz8qBQW063AX .node .label text,#mermaid-svg-no2AXz8qBQW063AX .image-shape .label,#mermaid-svg-no2AXz8qBQW063AX .icon-shape .label{text-anchor:middle;}#mermaid-svg-no2AXz8qBQW063AX .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-no2AXz8qBQW063AX .rough-node .label,#mermaid-svg-no2AXz8qBQW063AX .node .label,#mermaid-svg-no2AXz8qBQW063AX .image-shape .label,#mermaid-svg-no2AXz8qBQW063AX .icon-shape .label{text-align:center;}#mermaid-svg-no2AXz8qBQW063AX .node.clickable{cursor:pointer;}#mermaid-svg-no2AXz8qBQW063AX .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-no2AXz8qBQW063AX .arrowheadPath{fill:#333333;}#mermaid-svg-no2AXz8qBQW063AX .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-no2AXz8qBQW063AX .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-no2AXz8qBQW063AX .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-no2AXz8qBQW063AX .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-no2AXz8qBQW063AX .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-no2AXz8qBQW063AX .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-no2AXz8qBQW063AX .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-no2AXz8qBQW063AX .cluster text{fill:#333;}#mermaid-svg-no2AXz8qBQW063AX .cluster span{color:#333;}#mermaid-svg-no2AXz8qBQW063AX div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-no2AXz8qBQW063AX .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-no2AXz8qBQW063AX rect.text{fill:none;stroke-width:0;}#mermaid-svg-no2AXz8qBQW063AX .icon-shape,#mermaid-svg-no2AXz8qBQW063AX .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-no2AXz8qBQW063AX .icon-shape p,#mermaid-svg-no2AXz8qBQW063AX .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-no2AXz8qBQW063AX .icon-shape .label rect,#mermaid-svg-no2AXz8qBQW063AX .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-no2AXz8qBQW063AX .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-no2AXz8qBQW063AX .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-no2AXz8qBQW063AX :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;}#mermaid-svg-no2AXz8qBQW063AX .stage>*{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-no2AXz8qBQW063AX .stage span{fill:#dbeafe!important;stroke:#2563eb!important;stroke-width:1px!important;color:#1e3a8a!important;}#mermaid-svg-no2AXz8qBQW063AX .stage tspan{fill:#1e3a8a!important;}#mermaid-svg-no2AXz8qBQW063AX .ai>*{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-no2AXz8qBQW063AX .ai span{fill:#fef3c7!important;stroke:#d97706!important;stroke-width:1px!important;color:#78350f!important;}#mermaid-svg-no2AXz8qBQW063AX .ai tspan{fill:#78350f!important;}#mermaid-svg-no2AXz8qBQW063AX .test>*{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-no2AXz8qBQW063AX .test span{fill:#dcfce7!important;stroke:#16a34a!important;stroke-width:1px!important;color:#14532b!important;}#mermaid-svg-no2AXz8qBQW063AX .test tspan{fill:#14532b!important;} 任务

目标、上下文、约束、完成条件
AGENTS.md

持久项目规则
Skills

可复用流程
MCP

所需外部能力
Sandbox 与审批

执行边界
Codex 执行任务
Review Loop

审查、修复、验证
Team Governance

PR、owner、审计、淘汰
Outcome

稳定、可复用、可治理

本章要点：Codex 最佳实践不是"写更神奇的提示词"，而是把工程上下文、权限边界、验证流程和团队经验变成可维护的资产。AGENTS.md 负责稳定规则，Skills 负责可复用流程，MCP 负责外部系统连接，沙箱和审批负责风险控制。四者配合，Codex 才能从个人效率工具变成团队工程能力。

参考资料：

本章基于 Codex CLI 0.146.0 与 2026-08-03 的官方文档整理。Codex 仍在演进，使用时应以当前文档和本机行为为准。

相关推荐
JaydenAI1 个月前
[TypeScript学习笔记-11]创建一个极简的monorepo项目
typescript·monorepo
SQDN2 个月前
Codex CLI 报 wire_api=“chat“ 不再支持？改为 Responses 并验证 /v1/responses
openai·开发工具·codex·responses api·config.toml
爱好曙光3 个月前
前端Monorepo依赖管理优化：pnpm硬链接与按需安装实战
性能优化·pnpm·monorepo·前端工程化
知兀5 个月前
工程管理monorepo，后端多模块
monorepo
USER_A0015 个月前
创建Monorepo多项目管理
monorepo
We་ct6 个月前
前端包管理工具与Monorepo全面解析
前端·javascript·npm·pnpm·yarn·monorepo·包管理
木斯佳6 个月前
前端八股文面经大全：腾讯前端一面（2026-04-04）·深度解析
前端·ai·鉴权·monorepo
蜡台7 个月前
Monorepo 架构管理多个子项目实现
前端·javascript·vue.js·pnpm·monorepo
SuperEugene7 个月前
Monorepo + pnpm workspace 落地实操：Vue 中后台多项目 / 组件库 / 公共包管理｜Vue 工程化篇
前端·javascript·vue.js·pnpm·vite·monorepo
热门推荐
01国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）02历年考研数学一、数学二、数学三真题试卷及答案PDF03「全语录+省流版」邵艾伦 × 孙宇晨：聊风口、聊个人IP、聊年轻人如何抓住 AI 时代的机会04GitHub 镜像站点05Windows 10/11 如何退出微软账户并改用本地账户登录（含找不到选项的解决方法）06Telegram APK 下载安装完整指南 — 2026年最新07蜘蛛磁力 搜索引擎大全，如何使用蜘蛛磁力查找磁力链接08轻量化AI渗透武器库｜ARTEX自主攻防系统、资产梳理、漏洞挖掘、链路分析全流程智能化落地09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新10如何新建文件夹？ 电脑新建文件夹的4种方法