Codex的AGENTS.md记忆文件实测，项目交接能省多少事

接手陌生老项目时最头疼的往往不是代码本身而是那些散落在各处的隐性知识为什么这里要这样设计那段看似冗余的逻辑到底能不能删Codex 的 AGENTS.md 记忆文件本质上就是要把这些隐性知识显性化让 AI 在介入项目的第一时间就能建立上下文。最近我专门做了组对照实验看看这东西到底能省多少事。实验设计有记忆 vs 无记忆我找了个三年前的 Spring Boot 老项目业务复杂、文档缺失、原团队已离职——典型的考古现场。第一轮直接让 Codex 分析项目结构并生成一个新增接口第二轮先写好 AGENTS.md 再执行同样任务。无记忆文件的首轮对话Codex 花了将近 15 分钟才理清模块关系。它反复追问这个OrderService和OrderDomainService是什么关系BaseResponse和ApiResult为什么同时存在这些问题不是它笨而是项目里确实有两套并存的命名规范没有任何文档说明。最终生成的代码虽然能跑但混用了两种风格明显不符合项目惯例。第二轮有了 AGENTS.mdCodex 在 3 分钟内就开始输出符合项目规范的代码接口命名、异常处理、日志格式都与现有代码保持一致。这种差异不是速度上的而是质感上的——有记忆的输出像是老手写出来的没记忆的则像实习生第一天上班。AGENTS.md 的核心内容框架我的记忆文件没有搞得太复杂主要分四块项目概览与架构约束。包括技术栈版本、模块划分、分层规则。比如明确写死Controller 层只做参数校验和转换业务逻辑下沉到 ApplicationService这能避免 Codex 把大量逻辑堆在接口层。编码规范与风格约定。不是泛泛而谈遵循阿里巴巴规范而是具体到枚举类用Code后缀错误码常量放在ErrorCodes接口工具类优先使用 Hutool 而非 Apache Commons。这些细节越具体AI 的生成结果越可控。常见陷阱与特殊处理。老项目里总有些不能碰的地方。我记了一条订单金额计算使用BigDecimal禁止使用double或float且必须指定MathContext。Codex 之前在无记忆状态下就踩过这个坑生成了double类型的临时变量。依赖与集成要点。比如缓存统一使用 RedisTemplate键前缀格式为app:module:action:idTTL 默认 300 秒。这避免了每个开发者各自为战也让 AI 生成的代码在集成测试时能直接跑通。协作流程中的更新时机记忆文件不是写一次就完事的。我摸索出的节奏是项目初始化时写骨架每次迭代后补细节。具体操作上Codex 完成一个任务后我会检查它的输出是否有新发现——比如它用了某个我没注意到的工具类或者规避了一个我没写明的坑。这些就补充进 AGENTS.md。反过来如果它犯了错也要把规避方式写进去。这样记忆文件会越用越厚也越来越准。有个细节值得注意不要让 Codex 自己直接改写 AGENTS.md。它容易把记忆文件搞成流水账或者过度概括失去指导意义。我的做法是让 Codex 生成修改建议人工审核后再合并。多开发者共用的冲突处理当团队里多个人同时用 Codex 时记忆文件的同步就成了问题。我们目前的做法是把它纳入版本控制但设置了简单的协作规则任何人修改前先在团队群里说一声避免同时编辑修改内容限制在新增和细化不轻易删除已有条目每周五下午固定 review 一次合并重复或矛盾的描述实际运行下来冲突并不多见。因为 AGENTS.md 的内容相对稳定不像代码那样频繁变动。真正需要协调的是谁来写第一条——通常是最熟悉项目的人先搭框架其他人后续补充。Token 消耗的直观感受关于上下文节省我没有做精确的 Token 统计但有个明显的体感变化无记忆文件时每次对话 Codex 都要重新认识一遍项目长对话到后面经常提示上下文不足有了 AGENTS.md它能把更多 Token 用在具体任务上而不是花在理解项目结构上。一个具体的数字对比在生成一个中等复杂度的接口时无记忆状态下 Codex 平均需要 8-10 轮交互才能定稿有记忆文件后通常 3-4 轮就能达到同等质量。这不仅仅是 Token 量的节省更是开发者注意力的节省——少了很多不对我们项目不是这么做的这样的纠正回合。写在最后AGENTS.md 不是银弹。它解决的是项目知识传递这个老问题只是借助 AI 让这个过程更高效。对于新启动的项目越早建立记忆文件后期省的事越多对于已经成型的老项目花半天时间梳理一份往往能在接下来的第一个需求中就回本。真正让我愿意持续维护它的原因是某天同事说这个项目你交接得挺清楚啊——实际上我根本没写传统意义上的交接文档只是把和 Codex 协作过程中沉淀的记忆文件共享了出去。