ChatGPT 与 Codex 协同：AGENTS、.agents 与 Handoff 工程配置

love530love2026-07-09 9:42

让 ChatGPT 与 Codex 协同：AGENTS、.agents 与 Handoff 工程配置

主题：AI 开发工程治理实践

版本：CSDN 发布稿 v1.0

适合人群：想让多个 AI 工具长期维护同一工程仓库的开发者

阅读方式：本文可独立阅读，不依赖其他文章背景。
从零打通 那啥GPT 网页版 + 桌面版 访问本地代码：CodexPro + MCP 实战教程
CodexPro + MCP + Cloudflare 配置详解：HTTP2、QUIC 与连接排障
GPT + Codex CLI + CodexPro 三位一体：AI 编程协作工作流

一句话结论

.agents 目录可以把 ChatGPT 的架构评审、Codex 的本地执行和 completion report 串成闭环；AGENTS.md 则是 Codex 官方支持的仓库级自定义指令文件，可记录项目规则、验证方式和完成标准。
#mermaid-svg-poZemkhUaCgKCBI1{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-poZemkhUaCgKCBI1 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-poZemkhUaCgKCBI1 .error-icon{fill:#552222;}#mermaid-svg-poZemkhUaCgKCBI1 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-poZemkhUaCgKCBI1 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-poZemkhUaCgKCBI1 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-poZemkhUaCgKCBI1 .marker.cross{stroke:#333333;}#mermaid-svg-poZemkhUaCgKCBI1 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-poZemkhUaCgKCBI1 p{margin:0;}#mermaid-svg-poZemkhUaCgKCBI1 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-poZemkhUaCgKCBI1 .cluster-label text{fill:#333;}#mermaid-svg-poZemkhUaCgKCBI1 .cluster-label span{color:#333;}#mermaid-svg-poZemkhUaCgKCBI1 .cluster-label span p{background-color:transparent;}#mermaid-svg-poZemkhUaCgKCBI1 .label text,#mermaid-svg-poZemkhUaCgKCBI1 span{fill:#333;color:#333;}#mermaid-svg-poZemkhUaCgKCBI1 .node rect,#mermaid-svg-poZemkhUaCgKCBI1 .node circle,#mermaid-svg-poZemkhUaCgKCBI1 .node ellipse,#mermaid-svg-poZemkhUaCgKCBI1 .node polygon,#mermaid-svg-poZemkhUaCgKCBI1 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-poZemkhUaCgKCBI1 .rough-node .label text,#mermaid-svg-poZemkhUaCgKCBI1 .node .label text,#mermaid-svg-poZemkhUaCgKCBI1 .image-shape .label,#mermaid-svg-poZemkhUaCgKCBI1 .icon-shape .label{text-anchor:middle;}#mermaid-svg-poZemkhUaCgKCBI1 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-poZemkhUaCgKCBI1 .rough-node .label,#mermaid-svg-poZemkhUaCgKCBI1 .node .label,#mermaid-svg-poZemkhUaCgKCBI1 .image-shape .label,#mermaid-svg-poZemkhUaCgKCBI1 .icon-shape .label{text-align:center;}#mermaid-svg-poZemkhUaCgKCBI1 .node.clickable{cursor:pointer;}#mermaid-svg-poZemkhUaCgKCBI1 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-poZemkhUaCgKCBI1 .arrowheadPath{fill:#333333;}#mermaid-svg-poZemkhUaCgKCBI1 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-poZemkhUaCgKCBI1 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-poZemkhUaCgKCBI1 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-poZemkhUaCgKCBI1 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-poZemkhUaCgKCBI1 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-poZemkhUaCgKCBI1 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-poZemkhUaCgKCBI1 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-poZemkhUaCgKCBI1 .cluster text{fill:#333;}#mermaid-svg-poZemkhUaCgKCBI1 .cluster span{color:#333;}#mermaid-svg-poZemkhUaCgKCBI1 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-poZemkhUaCgKCBI1 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-poZemkhUaCgKCBI1 rect.text{fill:none;stroke-width:0;}#mermaid-svg-poZemkhUaCgKCBI1 .icon-shape,#mermaid-svg-poZemkhUaCgKCBI1 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-poZemkhUaCgKCBI1 .icon-shape p,#mermaid-svg-poZemkhUaCgKCBI1 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-poZemkhUaCgKCBI1 .icon-shape .label rect,#mermaid-svg-poZemkhUaCgKCBI1 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-poZemkhUaCgKCBI1 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-poZemkhUaCgKCBI1 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-poZemkhUaCgKCBI1 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} ChatGPT
architecture-reviews
codex/inbox handoff
Codex 执行
codex/reports
codex/done

1. 为什么需要 .agents

当项目只有一个人、一个聊天窗口时，随便说一句"帮我改一下"可能够用。

但长期项目不一样。长期项目需要回答：

  • 谁提出的任务？
  • 要改哪些文件？
  • 验收标准是什么？
  • Codex 实际做了什么？
  • ChatGPT 怎么知道执行结果？
  • 下一轮从哪里继续？

.agents 的作用就是把这些问题文件化。

2. 推荐目录结构

text 复制代码 
.agents/
├── README.md
├── chatgpt/
│   ├── README.md
│   ├── instructions/
│   │   └── README.md
│   └── architecture-reviews/
│       └── README.md
└── codex/
    ├── README.md
    ├── inbox/
    │   └── README.md
    ├── done/
    │   └── README.md
    └── reports/
        └── README.md

3. 每个目录放什么

目录 内容
.agents/chatgpt/instructions/ ChatGPT 生成的任务说明
.agents/chatgpt/architecture-reviews/ 架构评审、ADR 草案
.agents/codex/inbox/ 待 Codex 执行的 handoff
.agents/codex/done/ 已完成 handoff
.agents/codex/reports/ Codex 执行报告

4. Handoff 生命周期

text 复制代码 
ChatGPT 生成任务
    |
    v
写入 inbox
    |
    v
用户明确要求 Codex 执行
    |
    v
Codex 修改文件并验证
    |
    v
Codex 写 completion report
    |
    v
ChatGPT 读取报告复审

关键点：进入 inbox 不等于自动执行。

5. Handoff 模板

建议模板：

markdown 复制代码 
# HANDOFF-0001: Repository Structure v0.2

## Handoff ID

HANDOFF-0001

## From

ChatGPT

## To

Codex

## Date

2026-07-07

## Status

Pending

## Objective

说明这次任务要达成什么。

## Scope

说明包含什么、不包含什么。

## Instructions

列出具体执行步骤。

## Files to Modify

列出预计修改文件。

## Acceptance Criteria

列出验收标准。

## Completion Report

未执行时写 Not executed。

模板文件可以放在：

text 复制代码 
templates/agent-handoff-template.md

6. Completion Report 怎么写

建议报告格式：

markdown 复制代码 
# HANDOFF-0001 Completion Report

## Summary

## Files Changed

## Verification

## Git Status

## Not Done

## Next Steps

报告必须让 ChatGPT 不看终端也能知道：

  • 做了什么。
  • 改了哪里。
  • 怎么验证。
  • 还有什么风险。

7. AGENTS.md 的作用

.agents 是任务流目录，AGENTS.md 是 Codex 会在任务开始前读取的自定义指令文件。

AGENTS.md 可以写：

  • 仓库结构和重要目录。
  • 如何运行、测试和验证项目。
  • 修改前后的 Git 检查习惯。
  • 什么叫完成，以及如何写执行报告。
  • 哪些内容不应引入当前任务。

示例：

markdown 复制代码 
# AGENTS.md

## Repository Rules

- Use the existing `.venv`.
- Do not recreate the virtual environment.
- Do not push to remote without explicit approval.
- Write completion reports for handoff execution.
- Do not introduce unverified business rules or architecture assumptions.

8. 和治理文件的关系

不要让 AGENTS.md 变成万能文档。

推荐分工：

文件 职责
README.md 项目入口、安装方式、常用命令
docs/ 设计说明、教程、操作文档
AGENTS.md Codex 自定义指令、项目规则、验证方式
.agents/ 代理任务与报告
decision-log/ 决策、设计、里程碑

9. 安全注意事项

handoff 和报告里不要写：

  • token。
  • API key。
  • Cloudflare 临时完整 URL。
  • 私有客户信息。
  • 不能公开的本地路径。

如果必须引用敏感配置，用占位：

text 复制代码 
https://example.trycloudflare.com/mcp?codexpro_token=<redacted>

10. 推荐落地步骤

  1. 创建 .agents 目录结构。
  2. 给每个目录写 README。
  3. 创建 templates/agent-handoff-template.md。
  4. 创建第一个 handoff，但不要自动执行。
  5. 用户明确要求后，由 Codex 执行。
  6. Codex 写 report。
  7. ChatGPT 读取 report，进入下一轮。

11. FAQ

.agents 要不要提交到 Git？

如果它是项目协作流程的一部分，建议提交。若里面有临时私密内容，应拆分到 ignored 目录。

handoff 进入 inbox 后 Codex 会自动执行吗？

不会。必须由用户明确告诉 Codex 执行。

ChatGPT 怎么知道 Codex 的结果？

Codex 把执行报告写到 .agents/codex/reports/，ChatGPT 通过 CodexPro 或用户复制内容读取报告。

12. 系列总结

如果你正在搭建一套 AI 开发协作流程，可以按下面顺序逐步落地：

  1. 让 ChatGPT 访问本地代码。
  2. 理解 CodexPro、MCP、Cloudflare 链路。
  3. 建立 ChatGPT + Codex CLI + CodexPro 工作流。
  4. 用 .agents 和 AGENTS.md 固化长期协作规范。

这就是 AI 工程治理的起点：不是让 AI 随便改文件，而是让 AI 的计划、执行、验证和复盘都有工程痕迹。

13. 参考资料

相关推荐
武子康1 小时前
调查研究-222 PagedAttention 详解：vLLM 如何像操作系统一样管理 KV Cache
人工智能·llm·agent
龙虾PRO1 小时前
AI 产业三大发展主线同步爆发，香港企业依托智能工具落地合规化应用方案
人工智能
B8017913Y1 小时前
上课记笔记写不完不会整理？2026学习笔记生成使用场景该怎么选
人工智能·笔记·学习
武子康1 小时前
调查研究-221 KV Cache：LLM 推理服务真正的显存黑洞
人工智能·llm·agent
小猴子下山1231 小时前
2026年无锡干细胞领域企业发展观察：聚焦细胞生物技术与大健康管理
人工智能·精选
IT_陈寒1 小时前
React useEffect依赖数组把我坑惨了，这次搞明白了
前端·人工智能·后端
环境栈笔记1 小时前
AI 浏览器任务失败怎么排查：Context、Session、Page State 和 Task Log 检查清单
前端·人工智能·后端·自动化
Be-real2 小时前
机器学习：欠拟合、过拟合、偏差方差超全详解
人工智能·机器学习·过拟合·欠拟合
饼干哥哥2 小时前
Lovart真的帮大忙了，一键直出品牌视觉套件和个人IP封面Skill
人工智能·代码规范·设计
热门推荐
012026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？022026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf03AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路042026 年 AI 大模型 & AI 编程工具实战全总结05AI科技热点日报 | 2026年07月01日06GitHub 镜像站点07【AI】2026 年具身智能模型和世界模型总结082026 AI 编程工具选型横评：Cursor / Claude Code / Trae / Copilot 到底选谁（建议收藏·避坑版）09Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析102026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片