Codex ECC 导航地图¶

本指南帮助 Codex 代理导航 ECC，而无需从头扫描每个表面。在规划工作、准备 PR 级差异，或向审查者交接上下文时，请在根目录 AGENTS.md 和 .codex/AGENTS.md 之后使用它。

从这里开始¶

按此顺序阅读：

AGENTS.md - 通用项目规则、代理路由、测试预期和提交工作流。
.codex/AGENTS.md - Codex 专属配置、MCP、技能发现和 hook 一致性限制。
docs/COMMAND-AGENT-MAP.md - 命令到代理和技能的映射。
本指南 - Codex 会话的仓库导航、差异包结构和 PR 审查通道。

如果这些文件不一致，请针对当前任务优先采用更具体的文件：Codex 专属行为应放在 .codex/AGENTS.md；通用贡献策略应放在 AGENTS.md 和 CONTRIBUTING.md。

表面地图¶

表面	负责内容	Codex 用途
`AGENTS.md`	跨框架操作规则	在任何仓库工作前阅读
`.codex/AGENTS.md`	Codex 专属指导	在根目录说明之后阅读
`.codex/config.toml`	Codex 沙箱、MCP、配置档案和代理角色	当配置或 MCP 行为重要时检查
`.codex/agents/`	Codex 多代理角色层	用于探索者、审查者和文档研究者角色
`.agents/skills/`	面向 Codex 的技能副本	当 Codex 需要原生技能加载时使用
`skills/`	规范技能源	新增工作流知识时先更新
`agents/`	Claude 风格子代理提示	用作审查通道和委派意图的源材料
`commands/`	旧版斜杠命令垫片	仅在需要命令兼容性时更新
`docs/COMMAND-AGENT-MAP.md`	命令到代理和技能的关系	在重命名或新增工作流表面前检查
`rules/`	共享编码、安全和工作流规则	实现前阅读语言或领域规则
`hooks/`	Claude Code hook 工作流	不要假设 Codex hook 一致性
`scripts/`	安装、验证、同步和 CLI 工具	遵循现有 Node 脚本模式
`manifests/`	安装组件和模块注册	添加可安装表面时更新
`.github/PULL_REQUEST_TEMPLATE.md`	必需的 PR 正文检查清单	创建 PR 时保留各部分

任务路由¶

编辑前使用此快速路由：

任务	首选文件	可能验证
添加或更新技能	`skills/<name>/`、`.agents/skills/<name>/`、`manifests/`、`agent.yaml`	`node scripts/ci/validate-skills.js`、`node tests/ci/codex-skill-surface.test.js`
添加或更新命令	`commands/`、`docs/COMMAND-AGENT-MAP.md`、`COMMANDS-QUICK-REF.md`	`node scripts/ci/validate-commands.js`、`npm run command-registry:check`
添加 Codex 配置变更	`.codex/`、`scripts/codex/`、`scripts/lib/install-targets/codex-home.js`	`node tests/scripts/codex-hooks.test.js`、`node tests/codex-config.test.js`
添加可安装内容	`manifests/`、`scripts/lib/install-*`、`package.json`	`node scripts/ci/validate-install-manifests.js`、针对性安装测试
添加仅文档指导	`docs/`、`README.md`、框架补充文件	针对性文档测试，如可用再加 `markdownlint`
审查 PR	`commands/review-pr.md`、`agents/*reviewer.md`、`agents/pr-test-analyzer.md`	差异审查及相关测试

保持工作流贡献以技能为先。仅为旧版斜杠入口兼容性或跨框架一致性添加或更新 commands/。

Codex 代理角色¶

ECC 在 .codex/agents/ 中提供项目本地 Codex 角色层：

角色	文件	用途
探索者	`.codex/agents/explorer.toml`	编辑前进行只读证据收集
审查者	`.codex/agents/reviewer.toml`	正确性、安全和缺失测试审查
文档研究者	`.codex/agents/docs-researcher.toml`	API、发布说明和文档声明验证

使用角色处理有界的旁路工作。在本地完成当前阻塞任务，并在独立证据或审查任务可以并行运行时委派它们。

PR 差异包¶

在 /pr 之前，准备一个本地差异包。这为审查者提供了许多 PR 工具否则需要重建的上下文。

运行：

git fetch origin
git diff origin/main...HEAD --stat
git diff origin/main...HEAD --name-only
git log origin/main..HEAD --oneline --reverse

然后捕获：

## PR Diff Packet

### Intent
<One sentence describing the user-visible or maintainer-visible outcome.>

### Diff Map
- Added: <new files and why they exist>
- Modified: <existing files and why they changed>
- Unchanged but relevant: <surfaces checked and intentionally left alone>

### Risk and review lanes
- Behavior:
- Security:
- Tests:
- Docs:
- Release/install surface:

### Testing Done
- <commands run, or "Not run" with reason>

### Follow-ups
- <optional, only if not required for this PR>

使用 .github/PULL_REQUEST_TEMPLATE.md 作为最终 PR 正文结构。差异包为该模板提供输入；它不替代该模板。

PR 命令¶

需求	命令表面	说明
创建 PR	`/pr`	发现 PR 模板，分析提交和文件，推送并创建 PR
从 PRP 工作流创建 PR	`/prp-pr`	相同核心流程，并包含 PRP 工件引用
审查 PR	`/review-pr`	运行多视角审查通道并汇总发现
在 PR 前审查当前变更	`/code-review`	当尚无 GitHub PR 时，在提交前使用

Codex 可能无法在所有环境中原生执行斜杠命令。当斜杠命令不可用时，阅读命令文件并手动执行相同步骤。

审查通道¶

对于 PR 级差异，在请求审查前检查这些通道：

通道	证据
范围	`git diff origin/main...HEAD --name-only` 与声明的意图匹配
测试	新行为具有针对性测试或明确的无测试理由

审查车道	证据
安全	无密钥、不安全的外部写入、宽泛权限或输入信任缺口
安装面	新的技能、命令、代理、钩子、脚本或文件已在需要处注册
跨框架	Codex、OpenCode、Cursor、Claude Code 和文档面仅在适用时更新
文档	README 和聚焦文档链接到新的权威来源

对于代码更改，在实现后调用相关的审查车道。对于仅文档更改，运行针对性文档测试并审查链接漂移。

不要将 commands/ 视为新工作流知识的权威位置。优先使用 skills/。
不要将 Claude 钩子声明复制到 Codex 文档中。Codex 的强制执行基于指令、沙箱设置和可选的 MCP 配置。
在未检查权威 skills/ 源和 Codex agents/openai.yaml 元数据预期之前，不要更新 .agents/skills/。
除非用户明确要求发布捆绑包，否则不要打开混合了不相关的技能、命令、安装和发布更改的宽泛 PR。
不要让 Codex 文档更改仅能通过 README 正文被发现。当它影响 Codex 行为时，从 .codex/AGENTS.md 链接它。

快速命令¶

有用的本地检查：

node tests/docs/codex-navigation-map.test.js
node tests/ci/codex-skill-surface.test.js
npm run command-registry:check
npm run catalog:check
node tests/run-all.js

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 ev/ECC