摘要: Claude Code 与 Codex 可以形成稳定的跨平台任务接力,但正确做法不是复制聊天记录,也不是试图迁移模型内部上下文,而是把“当前任务状态”外置到 Git 仓库。最推荐的结构是:用 AGENTS.md 保存两端共享的项目规则,用 CLAUDE.md 导入 AGENTS.md 并保留 Claude 专属规则,用 TASK_HANDOFF.md 或 .agent-handoff/state.yaml 保存当前任务目标、已完成工作、决策、修改文件、测试结果和下一步,再用 Git Commit、Branch 和 Worktree 形成可验证的交接点。MCP 和 Skills 可以进一步让两个 Agent 连接同一套工具与可复用流程。本文给出一套 Claude Code 分析规划 → Codex 实现 → Claude Code 复核 → Codex 收尾与 PR 的完整接力方案。
核心结论
Claude Code+Codex 的跨平台任务接力现在可行,但它本质上是“外部状态接力”,不是“Session 接力”。如果把关键决策只留在聊天历史里,换 Agent 后就容易丢上下文;如果把任务状态放进仓库、Git、测试和结构化 Handoff 文件,两种 Coding Agent 就可以在不同终端、IDE、操作系统甚至不同开发者机器之间继续同一个工程任务。
- 最稳妥的共享层是 Git。 代码、Diff、Commit、Branch 与测试结果是模型无关的事实,比聊天摘要可靠。
- 项目长期规则以
AGENTS.md为中心。 Codex 可读取它;Claude Code 官方建议通过CLAUDE.md中的@AGENTS.md导入相同内容。 - 动态任务状态不要塞进
AGENTS.md。 当前目标、已完成工作、Blocking 与下一步更适合放入TASK_HANDOFF.md或.agent-handoff/state.yaml。 - MCP 可以共享 Server,但不要强行共享配置文件。 Claude Code 常用
.mcp.json;Codex 通过自己的配置层加载 MCP。建议两端指向同一个 MCP Endpoint 或同一 stdio Server。 - Skills 可以共享内容,但目录需要适配。 Claude Code 使用
.claude/skills/;Codex 使用自己的 Skill 发现路径。建议维护一份共享 Skill 源目录,再同步到两端。 - 高风险操作必须设置交接门。 部署、数据库迁移、删除资源、修改权限与生产发布不应由两个 Agent 在无人审批情况下自动接力。
背景与主要变化
过去同时使用 Claude Code 与 Codex 时,最常见的方法往往是:
Claude Code 做到一半
↓
复制聊天摘要
↓
打开 Codex
↓
粘贴摘要
↓
重新解释项目
这个方法在小任务上可以使用,但在真实软件工程项目中很脆弱。
原因首先是:聊天摘要不是事实源。
它可能遗漏:
- 修改了哪些文件。
- 为什么放弃某个实现方案。
- 哪个测试已经失败。
- 哪个 Migration 已生成但尚未执行。
- 哪个 API Contract 不允许修改。
- 当前 Branch 与 Base Commit 是什么。
- 哪些风险已经被确认。
- 哪些改动只是临时实验。
其次,两种 Coding Agent 的持久化机制并不相同。
Claude Code 使用 CLAUDE.md、Skills、MCP、自己的 Memory 与 Session 恢复机制;Codex 使用 AGENTS.md、Skills、MCP 和自己的项目配置。它们都能在各自产品内延续上下文,但没有官方机制保证:
Claude Session ID
→
Codex Session ID
可以被直接转换。
第三,双方的工具配置存在差异。
同一个 GitHub、Sentry、Linear 或内部数据库 MCP Server 可以同时被 Claude Code 与 Codex 调用,但两端的配置入口并不完全一致。
第四,两个 Agent 如果同时写同一个 Working Tree,会产生真实的文件冲突。
所以真正需要建立的是一个:
Agent-neutral Task State
也就是:任何 Agent 打开仓库,都能通过外部状态重建任务,而不是依赖前一个 Agent 的聊天历史。
核心功能拆解
1. AGENTS.md:两端共享的长期项目规则
AGENTS.md 很适合作为跨 Agent 的共享规则入口。
例如:
## Repository rules
- Node.js 版本固定为 22。
- 使用 pnpm,不使用 npm 或 yarn。
- 修改 API Handler 后必须运行 `pnpm test:api`。
- 不得直接修改生产数据库。
- 所有数据库 Schema 变化必须生成 Migration。
- 对 `src/billing/` 的修改需要额外运行 `pnpm test:billing`。
## Git workflow
- Agent 不得直接向 main push。
- 使用 `agent/<task-id>-<slug>` 分支。
- 接力前必须创建可恢复 Commit。
- 不允许把 Secret 写入仓库。
## Handoff protocol
- 接力前更新 `TASK_HANDOFF.md`。
- 必须记录当前 Commit、测试结果、Blocking 和下一步。
- 下一 Agent 开始工作前先读取 `TASK_HANDOFF.md`。
这里应该只放长期稳定内容:
- 编码规范。
- Build/Test 命令。
- 安全边界。
- 架构约定。
- Git 流程。
- Handoff 协议。
不要把“今天做到哪一步”长期写进 AGENTS.md。
2. CLAUDE.md:让 Claude Code 共用同一套 AGENTS.md
Anthropic 官方文档明确给出了这种兼容方式:
@AGENTS.md
## Claude Code
- 涉及 `src/billing/` 的修改先进行规划。
- 在把任务交给其他 Coding Agent 前执行 task-handoff Skill。
结构变成:
AGENTS.md
↑
│ @import
CLAUDE.md
Codex:
读取 AGENTS.md
Claude Code:
读取 CLAUDE.md
→ 导入 AGENTS.md
这样长期规则只维护一份。
如果项目完全不需要 Claude 专属规则,在 macOS/Linux 上也可以考虑符号链接:
ln -s AGENTS.md CLAUDE.md
不过为了 Windows 兼容与后续扩展,项目中保留一个很短的 CLAUDE.md 通常更稳妥。
3. TASK_HANDOFF.md:任务接力的核心文件
长期规则解决的是“项目应该怎么工作”,但不能回答:
当前这个任务已经做到哪里?
所以需要第二层:
TASK_HANDOFF.md
推荐模板:
---
handoff_version: 1
task_id: AUTH-247
status: ready_for_codex
from_agent: claude-code
to_agent: codex
branch: agent/AUTH-247-refresh-token
base_commit: 2cd94f1
handoff_commit: 69ad18c
updated_at: 2026-08-21T01:30:00-07:00
---
## Goal
修复 Refresh Token Rotation 中并发请求导致旧 Token 被重复接受的问题。
## Acceptance criteria
- 同一 Refresh Token 只能成功消费一次。
- 第二次使用必须返回 401。
- 不改变现有 Access Token TTL。
- 所有 auth 测试通过。
## Completed
- 已定位问题在 `src/auth/refresh-store.ts`。
- 已补充竞争条件测试。
- 已确认 Redis Lua Script 可作为原子操作方案。
- 尚未修改生产逻辑。
## Decisions
- 使用 Redis Lua Script 保证 consume 操作原子性。
- 不使用分布式锁,避免额外锁生命周期管理。
- 保持现有 API Response Schema。
## Changed files
- `tests/auth/refresh-race.test.ts`
- `TASK_HANDOFF.md`
## Verification
```text
pnpm test:auth
1 failed, 84 passed
当前新增 Race Test 按预期失败。
Next actions
- 在
src/auth/refresh-store.ts实现原子 consume。 - 运行
pnpm test:auth。 - 运行
pnpm lint。 - 如果通过,更新 Handoff 状态为
ready_for_review。
Do not
- 不运行生产 Migration。
- 不更改 Access Token TTL。
- 不修改 API Response Schema。
这个文件的作用相当于:
```text
跨 Agent 的任务存档点
任何 Agent 都可以打开它恢复工作,而不依赖上一个聊天窗口。

4. .agent-handoff/state.yaml:机器可读状态
如果只是人工切换 Claude Code 与 Codex,TASK_HANDOFF.md 已经可以工作。
如果未来还要连接:
- GitHub Actions。
- n8n。
- 自研 Orchestrator。
- CI Gate。
- Slack Bot。
- Agent Router。
建议再建立:
version: 1
task:
id: AUTH-247
title: Fix refresh token race condition
state:
phase: implementation
status: ready
owner: codex
previous_owner: claude-code
git:
branch: agent/AUTH-247-refresh-token
base_commit: 2cd94f1
handoff_commit: 69ad18c
verification:
required:
- pnpm test:auth
- pnpm lint
last_result: failing_expected
risk:
level: medium
production_write: false
human_approval_required: false
Markdown 给人类与 Agent 阅读。
YAML 给自动化程序读取。
5. Git Commit:不可替代的事实锚点
Handoff 文件说明“发生了什么”,Git Commit 则证明“真实代码是什么”。
推荐接力前固定执行:
git status
git diff
pnpm test:auth
git add .
git commit -m "handoff(AUTH-247): reproduce refresh token race"
git rev-parse --short HEAD
然后把 Hash 写入:
handoff_commit
下一 Agent 开始时:
git status
git log -5 --oneline
git show 69ad18c
这比让模型相信一句“测试已经写好了”可靠得多。
6. Git Worktree:并行 Agent 的隔离层
如果严格顺序执行:
Claude Code
→ Codex
→ Claude Code
一个 Branch 就够了。
如果希望:
Claude Code 调查
同时
Codex 实现
应该给不同 Agent 使用不同 Worktree。
Claude Code 支持 Worktree 工作流;Codex 也适合基于 Git Worktree 做并行隔离。
推荐:
repo/
├── main working tree
└── .worktrees/
├── claude-AUTH-247/
└── codex-AUTH-247/
不要让两个 Agent 同时作为 Writer 修改同一个 Working Tree。
Skills:把“如何接力”标准化
Claude Code 的 Skill 位于:
.claude/skills/<skill-name>/SKILL.md
Anthropic 当前文档明确说明 Claude Code Skills 遵循 Agent Skills 开放标准,并支持自动匹配与 /skill-name 调用。
为了减少双端漂移,可以维护:
shared-skills/
└── task-handoff/
├── SKILL.md
└── scripts/
└── collect-state.sh
再通过构建脚本同步到双方需要的位置。
SKILL.md:
---
name: task-handoff
description: Prepare a coding task for handoff to another agent.
---
## Procedure
1. Read `AGENTS.md`.
2. Inspect `git status`, `git diff`, and the last 5 commits.
3. Run the task-specific verification commands.
4. Update `TASK_HANDOFF.md`.
5. Update `.agent-handoff/state.yaml`.
6. Ensure no secrets were added.
7. Create a handoff commit if there are task changes.
8. Return:
- current status
- handoff commit
- tests
- blockers
- next actions
Do not deploy, merge to main, or change production resources as part of handoff.
同步脚本:
#!/usr/bin/env bash
set -euo pipefail
SOURCE="shared-skills/task-handoff"
rm -rf .claude/skills/task-handoff
rm -rf .agents/skills/task-handoff
mkdir -p .claude/skills
mkdir -p .agents/skills
cp -R "$SOURCE" .claude/skills/task-handoff
cp -R "$SOURCE" .agents/skills/task-handoff
这能避免两份同名 Skill 几周后产生不同流程。
MCP:共享同一个工具层
Claude Code 和 Codex 都支持 MCP,因此可以让两个 Agent 连接同一套:
GitHub
Linear
Sentry
CI
Docs
PostgreSQL read-only
Deployment Status
Claude Code 项目级配置可以使用 .mcp.json:
{
"mcpServers": {
"engineering-hub": {
"type": "http",
"url": "${ENGINEERING_MCP_URL}",
"headers": {
"Authorization": "Bearer ${ENGINEERING_MCP_TOKEN}"
}
}
}
}
核心原则是:
Claude Code ─┐
├→ 同一 MCP Server → GitHub / CI / Sentry / Docs
Codex ───────┘
而不是要求两个客户端使用完全一样的配置文件。
Secret 处理
不要把真实 Token 写进仓库。
只保留:
ENGINEERING_MCP_URL
ENGINEERING_MCP_TOKEN
变量名称。
真实值交给环境变量或 Secret Manager。
适用人群与使用场景
场景一:Claude Code 分析,Codex 实现
Claude Code:
Explore codebase
→ 找 Root Cause
→ 写失败测试
→ 记录设计决策
→ Handoff
Codex:
读取 Handoff
→ 实现代码
→ 跑测试
→ 更新状态
→ Handoff
适合复杂 Bug。
场景二:Codex 并行实现多个方案,Claude Code Review
使用不同 Worktree:
方案 A
方案 B
方案 C
分别实现。
然后 Claude Code 对:
Git Diff
Tests
Benchmark
做独立 Review。
场景三:Claude Code 大型重构,Codex 回归修复
Claude Code 完成核心重构。
Codex 根据:
CI failures
TASK_HANDOFF.md
git diff
逐个修复回归。
场景四:跨机器接力
开发者 A:
macOS + Claude Code
完成分析,Push Branch。
开发者 B:
Windows / Linux + Codex
Clone 后继续。
只要状态都在 Git 中,就不依赖同一台电脑。
站内可继续结合:
安装、配置与完整接力步骤
第一步:建立共享规则
项目根目录创建:
AGENTS.md
再创建:
CLAUDE.md
写入:
@AGENTS.md
## Claude Code specific
- 对高风险修改先规划。
- 在把任务交给其他 Coding Agent 前执行 task-handoff。
第二步:建立 Handoff 文件
创建:
TASK_HANDOFF.md
.agent-handoff/state.yaml
提交:
git add AGENTS.md CLAUDE.md TASK_HANDOFF.md .agent-handoff/state.yaml
git commit -m "chore: add cross-agent handoff protocol"
第三步:建立共享 Skill
创建:
shared-skills/task-handoff/
再用同步脚本复制到两个客户端需要的目录。
第四步:配置共同 MCP
Claude Code 示例:
claude mcp add --transport http engineering-hub \
--scope project \
https://YOUR_DOMAIN/mcp
不同版本 CLI 参数可能调整,实际执行前应分别运行:
claude mcp --help
codex mcp --help
确认当前版本语法。
第五步:Claude Code 接任务
示例:
调查 AUTH-247:Refresh Token 在高并发下偶尔可以重复使用。
先不要修改生产逻辑。
定位 Root Cause,补充稳定复现问题的测试,然后准备交给 Codex 实现。
Claude Code 先完成:
Plan
→ Explore
→ Test reproduction
第六步:Claude Code 创建接力点
执行:
git status
git diff
pnpm test:auth
更新:
TASK_HANDOFF.md
然后:
git add .
git commit -m "handoff(AUTH-247): reproduce token rotation race"
此时 Claude Code 的聊天 Session 已不再是恢复任务的必要条件。
第七步:Codex 接管
启动 Codex 后第一条 Prompt 可以很短:
Read AGENTS.md and TASK_HANDOFF.md.
Verify the current branch and handoff commit.
Continue AUTH-247 from the documented next actions.
Do not change anything listed under "Do not".
Run the required tests before handing back.
因为真正上下文已经在仓库里。
第八步:Codex 实现与测试
Codex 修改代码后:
pnpm test:auth
pnpm lint
如果全部通过,更新:
state.status = ready_for_review
state.owner = claude-code
并提交:
git add .
git commit -m "handoff(AUTH-247): implement atomic token consume"
第九步:Claude Code 独立 Review
Claude Code 即使新开 Session 也可以:
Read AGENTS.md and TASK_HANDOFF.md.
Review the handoff commit as an independent reviewer.
Check correctness, race conditions, security, and regression risk.
Do not modify files until review findings are listed.
新的 Context 还有一个优势:
Reviewer 不容易被实现过程中的思路锚定。
第十步:最终 Gate
有 Findings:
Claude Code
→ 更新 Handoff
→ Codex Fix
没有 Findings:
status: ready_for_pr
再由人工或受控自动化创建 PR。

实际工作流示例
完整执行链:
Issue / User Goal
↓
Claude Code
Analyze + Reproduce
↓
Git Commit A
↓
TASK_HANDOFF.md
↓
Codex
Implement + Test
↓
Git Commit B
↓
TASK_HANDOFF.md
↓
Claude Code
Independent Review
↓
┌────────────────┐
│ Findings exist?│
└───────┬────────┘
│
Yes │ No
↓
Codex Fix
│
└────────────→ PR Gate
建议把不同事实存放到明确位置:
| 接力事实 | 推荐存放位置 |
|---|---|
| 项目长期规则 | AGENTS.md |
| Claude 专属规则 | CLAUDE.md |
| 当前任务摘要 | TASK_HANDOFF.md |
| 自动化状态 | .agent-handoff/state.yaml |
| 代码状态 | Git Commit |
| 修改内容 | Git Diff |
| 验证结果 | Handoff + CI |
| 工具状态 | MCP |
| 重复流程 | Skills |
核心原则:
不要让任何关键任务事实只存在于某个 Agent 的聊天窗口里。
对比与选型建议
| 方案 | 可恢复性 | 可验证性 | 自动化能力 | 推荐场景 |
|---|---|---|---|---|
| 复制聊天摘要 | 低 | 低 | 低 | 很小的临时任务 |
| 只用 Git Commit | 高 | 高 | 中 | 简单工程接力 |
| Git+Handoff | 很高 | 很高 | 中 | 个人/小团队 |
| Git+Handoff+Skills+MCP | 很高 | 很高 | 高 | 企业、多 Agent、多 Repo |
最推荐的基础方案
对于多数开发者:
AGENTS.md
+
CLAUDE.md → @AGENTS.md
+
TASK_HANDOFF.md
+
Git Branch / Commit
已经足够稳定。
当工作流成熟以后,再加入:
Skills
MCP
Worktree
CI Gate
Agent Router
风险、限制与注意事项
1. 不要把 Claude Session Resume 当成 Codex Handoff
Claude Code 自己的 Session Resume 只恢复 Claude Code 会话。
跨厂商需要外部状态层。
2. 不要双 Agent 同时写一个 Working Tree
风险包括:
- 文件覆盖。
- 未提交改动被另一个 Agent修改。
- 测试结果无法对应具体版本。
- Handoff Commit 不可信。
要么顺序接力,要么使用 Worktree。
3. Handoff 文件可能过期
下一 Agent 开始前必须验证:
git status
git rev-parse --short HEAD
是否与:
handoff_commit
一致。
不一致时先 Reconcile,不要继续盲做。
4. 不要把 Secret 写进 Handoff
禁止:
API Key
Database Password
Cloud Credential
Production Token
只记录:
ENV VAR NAME
Secret reference
Credential source
5. MCP 必须最小权限
建议分离:
read tools
write tools
admin tools
不要把所有高权限能力一次暴露给两个 Agent。
6. 高风险步骤加入 Human Approval
对于:
- Production Deploy。
- Database Migration。
- Delete。
- Billing。
- Account Permission。
- Public Publish。
- Secret Rotation。
建议:
Agent ready
↓
Human approval
↓
Execute
7. Handoff 不要无限增长
历史过程交给:
Git History
Issue
PR
TASK_HANDOFF.md 只保存当前任务继续执行所需信息。
8. Skills 要有唯一 Source of Truth
如果 .claude/skills/ 与另一个 Agent 的 Skill 目录都由复制产生,应让:
shared-skills/
成为唯一源码。
9. Acceptance Criteria 必须可验证
不要写:
继续优化代码。
应该写:
pnpm test:auth passes
pnpm lint passes
Refresh token replay returns 401
No API schema changes
Agent 接力质量很大程度取决于完成条件能否被机器验证。
事实依据与来源
本文关于 Claude Code CLAUDE.md、AGENTS.md 导入、Skills 与 MCP 的信息来自 Anthropic Claude Code 官方文档。Anthropic 明确说明 Claude Code 读取 CLAUDE.md 而不是直接读取 AGENTS.md,并推荐在 CLAUDE.md 中用 @AGENTS.md 让多个 Coding Agent 共用项目指令。Claude Code Skills 使用 .claude/skills/<skill-name>/SKILL.md,并遵循 Agent Skills 开放标准。
本文关于 Claude Code 项目级 MCP 的 .mcp.json、项目共享范围和环境变量展开同样来自 Anthropic 官方 MCP 文档。
本文关于 Codex 的 AGENTS.md、Skills、MCP 与 Agentic Coding 能力来自 OpenAI 官方 Codex / Developer 文档。
官方没有确认的内容:
- 没有官方跨厂商 Claude Session → Codex Session 转换协议。
- 没有官方规定必须使用
TASK_HANDOFF.md。 - 没有官方规定必须使用
.agent-handoff/state.yaml。 - 没有官方规定 Claude Code 必须负责分析、Codex 必须负责实现。
这些属于本文的工程实施建议。
本文也没有声称 Claude Code 或 Codex 在所有任务中一定优于另一方。具体表现受模型版本、代码库、权限、上下文质量与测试覆盖影响。
FAQ
Claude Code 能把正在运行的 Session 直接交给 Codex 吗?
目前没有官方跨厂商 Session Transfer 机制。Claude Code 的恢复功能只恢复 Claude Code 自己的会话。跨到 Codex 时,应通过 Git、AGENTS.md、TASK_HANDOFF.md、测试结果和 MCP 等外部状态恢复任务。
Claude Code 可以读取 Codex 使用的 AGENTS.md 吗?
可以通过 Anthropic 官方推荐的兼容方式实现。Claude Code 原生读取 CLAUDE.md,你可以在 CLAUDE.md 中写 @AGENTS.md。这样 Codex 直接读取 AGENTS.md,Claude Code 通过 Import 读取同一份内容。
是否可以只保留 AGENTS.md,不创建 CLAUDE.md?
Codex 可以直接使用 AGENTS.md,但 Claude Code 原生入口仍是 CLAUDE.md。为了跨平台与后续 Claude 专属规则,建议创建一个很短的 CLAUDE.md 并导入 AGENTS.md。
Claude Code 和 Codex 的 Skill 可以共用吗?
Skill 内容可以高度复用,因为核心都是 SKILL.md。但默认目录、客户端扩展和加载机制可能不同。推荐维护一个共享源码目录,再同步到各客户端需要的位置。
MCP 配置能直接复制吗?
不建议。两端都支持 MCP,但配置入口与格式并不保证完全一致。正确做法是让两端连接同一个 MCP Server,而不是要求共享同一份客户端配置文件。
任务接力一定需要 Git Commit 吗?
不是产品硬性要求,但强烈建议。没有 Handoff Commit 时,下一 Agent 很难确认 Handoff 文档描述的代码状态是否等于磁盘上的真实状态。
两个 Agent 可以同时开发吗?
可以,但不要同时写同一个 Working Tree。使用独立 Git Worktree 和 Branch,再在 Review / Merge Gate 汇合。
TASK_HANDOFF.md 应该提交到 Git 吗?
如果它记录团队共享任务状态,建议提交。必须严格禁止写入 Secret。
Claude Code 的 Memory 能不能作为跨 Agent Memory?
不能依赖。Claude Code 的内部 Memory 不会自动变成 Codex 的上下文。跨 Agent 状态必须放到双方可访问的仓库、MCP 或其他共享存储中。
最推荐的最小方案是什么?
AGENTS.md
CLAUDE.md → @AGENTS.md
TASK_HANDOFF.md
Git Branch + Commit
先跑通这四项,再增加 Skills、MCP、Worktree 与 CI Gate。
参考来源
- Anthropic Claude Code:How Claude remembers your project
- Anthropic Claude Code:Extend Claude with skills
- Anthropic Claude Code:Connect Claude Code to tools via MCP
- Anthropic Claude Code:Features overview
- OpenAI Developers:Codex and developer documentation
- OpenAI Codex 官方产品页面
工具选型与提示词资料
适合阅读工具评测、工具推荐、对比测评类文章后继续转化。