[aru_43]

让 Claude Code 和 Codex 共用一套"大脑"

一个分裂的体验

用 AI 写代码,体验是分裂的。

一方面,Claude Code、Codex 这类 agent 确实强:能读项目、自己拆任务、连续动手,"vibe coding"的爽感是真的。另一方面它也很容易失控——长会话写到后面开始"失忆",架构越改越乱;你想换个工具试试别的思路,结果发现得把项目背景从头再讲一遍,之前攒的上下文一点都带不走。

折腾一阵后我想明白一件事:问题不在工具,而在于我们把"项目的记忆"绑死在了某一个工具里。 解法因此也很简单——把记忆和工具解耦。这篇分享我现在在用的方案:一套工具无关的"记忆库",让 Claude Code 和 Codex 共用同一个大脑,想用谁就用谁、随时切换。

两条主线:知识层与能力层

先建立一个心智模型。一个 AI 编程项目里其实有两层东西,别混在一起:

• 知识层——AI 该"知道"什么:项目是什么、架构、数据结构、接口约定、规则、要做什么、做到哪了。
• 能力层——AI 能"做"什么:连数据库 / GitHub 的 MCP、把重复流程固化的命令和技能。

知识层是必备的,也是跨工具的关键;能力层是可选的、按需才加。这篇主要讲知识层——因为它才是决定"能不能随意换工具"的那一层。

为什么真能跨工具:AGENTS.md

方案能成立,靠的是一个正在普及的开放标准:AGENTS.md。它由 OpenAI 提出、后交给 Linux 基金会,到 2026 年已被数万个仓库采用,Codex、Cursor、Copilot、Gemini CLI 等都原生自动读它。

唯一的例外是 Claude Code——它只认 CLAUDE.md、不读 AGENTS.md。但官方给了桥接办法:在 CLAUDE.md 第一行写一句 @AGENTS.md 把它导入进来。Claude Code 每次会话会自动读 CLAUDE.md,顺着这条 import 就把 AGENTS.md 也一并自动加载了。

于是,把"开工须知"写进 AGENTS.md,Claude Code 和 Codex 就共用了同一个入口。这个入口就是整套方案的"大脑前额叶"。

目录结构

我把知识层做成一个 AGENTS.md 入口 + 一个 memory-bank/ 文件夹,全部纯 markdown、提交进 Git:

your-repo/
├── AGENTS.md              # 共用入口:项目简介 + 技术栈/约定 + 军规 + 架构概览 + 开工须知
├── CLAUDE.md              # 仅一行 @AGENTS.md(让 Claude Code 复用同一份)
├── memory-bank/           # 知识层(记忆)
│   ├── data-model.md      # 数据库结构:表/字段/关系/索引及意图
│   ├── api-contract.md    # 接口契约:返回结构、错误码、各接口入参出参
│   └── todo.md            # 复选框任务 = 计划 + 进度;底部记已知问题/下一步
└── db/                    # 建表 schema 等代码(要写时再建)

几个刻意为之的取舍:

军规直接写进 AGENTS.md 正文,不单独建 rules.md。因为 AGENTS.md 是两个工具都能完整自动读的唯一一份,把规则放正文里等于"每次都强制带上"最稳;@import 是 Claude Code 的语法,Codex 不一定会展开,所以别指望 import 一个 rules 文件来跨工具生效。等规则多到几十条,再拆出去不迟。

项目简介、技术栈也并进 AGENTS.md。它们稳定又短、每次都该看,正好适合放进这个"每次都加载"的入口。判断标准就一句:稳定 + 短 + 每次都该看 → 进 AGENTS.md;会高频变动或会越写越长 → 单独成文件。

计划和进度合成一个 todo.md。复选框 - [ ] 是计划、- [x] 是进度,天然合二为一,底部再留个"已知问题 / 下一步"小节就够。

memory-bank 按"有内容才建",不是固定模板。后端有数据和接口,所以有 data-model + api-contract + todo;而纯前端项目没有数据库、也不定义接口(只调用),它的 memory-bank 基本就只剩一个 todo.md(复杂的话再加一个讲组件/模板约定的 design.md)。

日常工作流

有了这套结构,每个功能都走同样的节奏:

先对齐。 让 AI"读完入口和相关记忆,有哪些需要我澄清的,让你对这个任务 100% 清楚?"它通常会问一串问题,我答完后让它据此完善 todo.md 里的计划。这一步看似慢,其实性价比最高——计划越清楚,后面越省心。

再实施,一步一验证。 "执行计划的第 1 步;我来跑测试,测试通过前不要做第 2 步;通过后更新 todo.md。" 绝不让它一口气写完一大坨。

永远先 Plan 再 Execute。 动手前一律先用 Ask 模式或 Plan Mode(Claude Code 里按 shift+tab)给方案,确认满意再放它执行。

而切换工具几乎无感:今天用 Claude Code 写复杂逻辑,明天用 Codex 换思路或省额度,它们读的是同一套 AGENTS.md + memory-bank/,进度都落在同一个 todo.md,无缝衔接,甚至能并排各跑一版对比着挑。

几条不能省的护栏

vibe coding 爽,但认真的项目里有几条线不能越:

碰钱碰数据的代码,先写测试。 涉及支付、资金、权限、数据隔离的逻辑,先写测试 → 确认失败 → 再实现到绿,而且不让 AI 改测试。这是和 agent 配合最稳的模式。

AI 改"军规"和"契约",你必须审 diff。 这些文件是项目的宪法,都在 Git 里、有历史,AI 改完花十秒在 diff 里扫一眼再提交,别让它悄悄重写了规则。

密钥永远不进记忆库。 任何 token、密钥只走环境变量。

别在长会话里放飞。 一个会话聚焦一个功能,做完即提交、开新会话,避免上下文堆积导致失忆和乱改。

能力层:按需才加

回到开头那两层——memory-bank 之外,你迟早会想要"能力层",但它是可选的:

• .mcp.json:想让 AI 在仓库里直接操作外部服务时才配(连数据库、操作 GitHub)。它能被 Claude Code 和 Codex 共用。
• .claude/commands、.claude/skills:某个流程老是重复,就固化成命令(比如 /spec、/done)。纯提效,没有也能开发,且是工具专属的。

前期只靠知识层就能完整开发——AI 读文件、写代码、你跑测试。等有了具体需求再往上加能力层即可。

全局的归全局,项目的归项目

最后澄清一个常见困惑:不是所有东西都塞进代码目录。你跨所有项目都用的(个人的 GitHub 连接器、通用技能)留在全局;只有这个项目专属、且想随代码版本化、给团队或别的工具共享的,才放进仓库——也就是 AGENTS.md、memory-bank/、.mcp.json 这些。而且放进去的是"配置 / 声明",不是把软件复制一份。

实操:怎么把这套框架"告诉"agent

讲完结构,最常被问的一个问题是:那我具体怎么让 Claude Code 或 Codex 用上这套东西?

答案可能和直觉相反:你不需要每次口头解释。你只要把框架写进 AGENTS.md 一次,之后每次会话它都会自动加载、自动遵守。 这套框架是"自描述"的——规矩就住在那个被自动读取的入口文件里。落地只有三步。

第一步:让 agent 帮你搭骨架(一次性)

在仓库里打开 Claude Code 或 Codex,把下面这段丢给它:

请在本仓库建立这套结构并填好初稿:
- AGENTS.md(含:项目简介、技术栈/约定、军规、架构概览,以及一段"给 AI 的开工须知")
- CLAUDE.md(只写一行 @AGENTS.md)
- memory-bank/(data-model.md、api-contract.md、todo.md)
开始前先问我必要信息:项目是什么、技术栈、有哪些核心数据实体和接口、有哪些必须遵守的规则。
我回答后再生成,生成完等我确认。

(Claude Code 还有个 /init,会扫描仓库自动生成一份 CLAUDE.md 当起点,你再按这套结构调整也行。)

第二步:把规矩写进 AGENTS.md 的"开工须知"

这才是你真正"告诉 agent 框架"的地方——写一次,永久生效。 在 AGENTS.md 末尾放这么一段,它会随入口被每次自动加载:

# 开工须知(给 AI)
- 动手前先读 memory-bank/todo.md 了解进度;做哪块再读 data-model.md / api-contract.md 对应部分。
- 严格遵守上面的"军规"。
- 永远先用 Plan/Ask 模式给方案,我确认后再实现。
- 一步一验证:做完一步等我测试通过,再做下一步;不要一次写一大坨。
- 碰钱碰数据的逻辑先写测试,且不要修改测试。
- 每完成一步:更新 todo.md;改了军规/契约/数据模型,提醒我在 diff 里审核。

写好这段,你就不用每次再复述流程了——agent 一加载 AGENTS.md 就知道该怎么干,Claude Code 和 Codex 都一样。

第三步:每次开工一句开场白

读完 AGENTS.md 和 memory-bank/todo.md,复述你接下来要做什么;
按 todo 的第 1 步走,先给我方案,我确认后再实现,测试我来跑。

平时维护也很轻:做完一步让它"更新 todo.md,勾掉已完成、补上新发现的任务";定了什么长期约定,用 Claude Code 的 # 快捷记忆随手追加进 AGENTS.md。

一句话收束这一节:框架不靠口述,靠写进 AGENTS.md;日常你只需要一句开场白 + 指一个任务。 第一次用上面那段 bootstrap 提示词把骨架搭起来,这套就跑起来了。

写在最后

这套方案的内核就一句话:把项目的记忆做成工具无关的纯文本,跟着代码走;工具只是读这份记忆的不同"读者"。

想通这一点,"用 Claude Code 还是 Codex"就从一个让你纠结的选择,变成了一个可以随手切换的自由。工具会一直更新换代,但你那套 memory-bank/ 会一直陪着项目长大——这大概就是从"凭感觉写代码"走向"靠工程做事"的那一步。

本文涉及的工具标准(AGENTS.md、Claude Code 的 @AGENTS.md 导入、记忆自动加载等)更新较快,具体以各家官方文档为准。