AGENTS.md、config.toml、skills、hooks这一整套Codex配置在长科研项目里被说成“工作流模式比工具本身更重要”，但配置的版本漂移、模板更新和跨会话连续性——一个科研项目跑了六个月之后，Codex的“项目记忆”到底靠什么维持，还是说每换一次会话就重新交代一遍？

一、问题的提出：六个月之后，谁还记得这个项目

一个持续六个月的科研项目，通常跨越数十次代码提交、上百次实验运行、若干次人员轮换与至少一次工具链升级。在这类项目中引入 Codex 这类编码智能体，最初往往能获得明显的效率提升：它能读仓库、能改文件、能跑命令。但真正让团队感到不安的，是第 40 次会话与第 1 次会话之间的差异——模型没有变，仓库还在，可它对这个项目的“理解”似乎被重置了。于是出现了那句流传很广的判断：“工作流模式比工具本身更重要。”

这句话在工程直觉上是对的，但它把一个需要精确回答的问题模糊化了。工作流模式之所以重要，是因为它承担了本应由“记忆”承担的功能。问题在于，记忆究竟存放在哪里、由谁维护、以什么形式被重新注入。如果回答不了这三个问题，“工作流比工具重要”就只是一句正确的废话。本文的核心主张是：在 Codex 的工程实践中，长周期项目的连续性主要由 AGENTS.md、config.toml、skills、hooks 四类配置构成的外部状态机维持，而不是由会话上下文维持；因此配置治理的质量，直接决定了“项目记忆”的半衰期。

需要先界定讨论对象。本文所说的 Codex，指以命令行/IDE 集成为形态、可读取仓库文件并执行工具调用的编码智能体工作流；AGENTS.md 指放置在仓库中、用于向智能体声明项目约定与操作规范的说明文件；config.toml 指智能体运行时的配置文件，承载模型选择、审批策略、沙箱与工具开关等参数；skills 指可复用的、封装了特定任务流程的能力单元；hooks 指在会话或工具调用的特定生命周期节点自动触发的脚本。四者的具体字段名与加载顺序会随版本变化，本文讨论的是其职责结构而非某一版本的字段细节。

本文评述：把配置称为“记忆”是一种工程隐喻，而非认知科学断言。隐喻的价值在于它迫使我们把“模型记住了什么”转换为“系统在每次会话开始时被喂进了什么”。后者是可审计、可版本化、可测试的，前者不是。这一转换是全文的方法论起点。

二、概念澄清：Codex 的“记忆”到底是什么

2.1 三种被混用的“记忆”

在讨论中，“记忆”至少被赋予了三层不同含义，混淆它们是大量无效争论的根源。第一层是参数记忆，即模型权重中固化的知识，它对所有用户一致，不随项目变化。第二层是上下文记忆，即当前会话窗口内保留的对话与文件内容，它有硬性长度上限，会话结束即消失。第三层是外部状态记忆，即存放在仓库与配置中的、可被每次会话重新读取的持久化信息。长周期项目真正依赖的是第三层，而人们抱怨“它又忘了”时，往往误以为是第一层或第二层出了问题。

这一区分有直接的工程后果。若把连续性寄托于上下文记忆，那么随着项目推进，单次会话需要携带的历史会线性增长，最终必然溢出；若寄托于参数记忆，则任何项目特有的约定都无从表达。唯有外部状态记忆具备“容量与项目复杂度解耦”的性质——配置文件的体积可以增长，但它不占用推理窗口，只在需要时被选择性加载。笔者认为，理解这一点，就理解了为什么“工作流模式”在长项目中具有不可替代性：它不是风格偏好，而是容量约束下的必然选择。

2.2 外部状态记忆的四个载体

把外部状态记忆落到 Codex 的具体形态上，可以识别出四个载体，它们分别回答四个不同的问题：AGENTS.md 回答“这个项目的规矩是什么”，config.toml 回答“这次运行允许做什么”，skills 回答“这类任务该按什么步骤做”，hooks 回答“在什么时点必须自动检查什么”。四者并非并列的四个文件，而是一条从声明性约束到过程性能力再到强制性校验的谱系。

本文评述：这一谱系的关键性质是“约束强度递增、灵活性递减”。AGENTS.md 是软约束，模型可以不完全遵守；config.toml 是硬开关，越权即失败；skills 是流程模板，可被调用也可被绕过；hooks 是确定性执行，不依赖模型判断。理解强度梯度，才能在设计治理策略时把不同性质的要求放到正确的层，而不是把所有规则都堆进 AGENTS.md 然后抱怨它不生效。

三、四层配置的职责边界与耦合关系

3.1 AGENTS.md：声明性约束层

AGENTS.md 的本质是一份面向智能体的项目契约。它通常包含目录结构说明、构建与测试命令、代码风格、禁止事项、领域术语表。它的优势是自然语言表达力强、维护成本低；劣势同样明显：它是概率性生效的，模型可能忽略其中某一条，尤其在长文档中靠后的条目。因此 AGENTS.md 适合承载“方向性、解释性、需要上下文才能理解”的约定，而不适合承载“必须百分之百执行”的硬规则。

一个常见的反模式是把 AGENTS.md 写成百科全书。随着项目推进，团队不断往里追加“上次踩过的坑”，六个月后它膨胀到数千行，结果适得其反：关键约束被淹没，模型的选择性注意反而下降。笔者认为，AGENTS.md 应当遵循“少而稳定、变则外移”的原则——高频变化的规则应下沉到 hooks 或 skills，AGENTS.md 只保留半年内不太会变的骨架。

3.2 config.toml：运行时策略层

config.toml 承载的是运行参数：模型与推理强度、审批模式、沙箱边界、可用的工具与 MCP 服务、环境变量注入等。它的关键特征是确定性——配置写什么就是什么，不依赖模型理解。这使得它成为治理“越权行为”的首选层。例如把网络访问、写盘范围、可执行命令白名单固化在配置中，比在 AGENTS.md 里写“请不要随意联网”要可靠得多。

但 config.toml 也是版本漂移最剧烈的一层。工具升级常伴随字段重命名、默认值调整、新字段引入，旧配置可能被静默忽略或报错。更隐蔽的是默认值变化：某个安全相关的默认从严格变为宽松，配置文件本身没动，行为却变了。这类“无声漂移”在长项目中极难排查，因为没有任何一次提交记录它。

3.3 skills：过程性能力层

skills 把“一类任务的完成步骤”封装为可复用单元，例如“新增一个数据预处理脚本”“按项目规范生成实验报告”“执行一次回归并归档结果”。它的价值在于把隐性流程显性化，降低每次会话重新解释流程的成本。skills 的粒度设计是核心难点：过粗则复用性差，过细则调用开销高、组合复杂。

本文评述：skills 的真正作用不是“让模型更聪明”，而是“让流程可审计”。一个被封装为 skill 的流程，其步骤是固定的、可被 review 的；而同样的流程若每次靠自然语言临时交代，则每次执行都是一次不可复现的采样。对科研项目而言，可复现性的价值远高于单次效率，这一点常被低估。

3.4 hooks：确定性校验层

hooks 在生命周期节点自动执行脚本，典型场景包括：会话开始时注入当前分支与最近变更摘要、工具调用前做路径与命令校验、提交前跑格式与静态检查、会话结束时归档本次变更。它是四层中唯一不依赖模型判断的层，因此也是治理“必须发生”的事情的最后防线。

hooks 的风险在于副作用与性能。一个在每次工具调用前都执行的重量级脚本，会显著拖慢交互；一个会修改工作区的 hook，可能引入难以追踪的状态污染。工程上应遵循“读多写少、快进快出、失败可降级”的原则，并给每个 hook 明确的超时与日志。

表 1：四层配置的职责与漂移敏感度对照（本文整理，属定性归纳，非实测统计）

四、失效机制：版本漂移、模板更新与跨会话断裂

4.1 版本漂移的三种形态

配置漂移（configuration drift）在运维领域早有系统研究，其经典定义是“系统实际状态偏离其声明状态”的过程。在 Codex 场景中，漂移表现为三种形态。其一是字段漂移：工具升级后字段改名或废弃，旧配置被忽略，行为回落到默认值。其二是语义漂移：字段名不变但含义调整，例如某个超时参数的单位或某个策略的默认严格度变化。其三是环境漂移：配置未变，但底层依赖（运行时版本、依赖库、外部服务）变化导致行为不同。

三种形态的排查难度递增。字段漂移通常有报错或警告可循；语义漂移最隐蔽，往往在事故发生后才被回溯发现；环境漂移则常被误判为“模型不稳定”。笔者认为，治理漂移的第一步不是写更多规则，而是建立基线——把“当前认为正确的配置状态”固化为可对比的快照，让任何偏离都可被检测，而不是依赖人的记忆。

4.2 模板更新的双刃性

团队常维护一套“标准模板”用于新项目初始化，包含推荐的 AGENTS.md 结构、config.toml 基线、常用 skills 与 hooks。模板更新的初衷是传播最佳实践，但它与长项目之间存在结构性张力：模板面向“新项目的最优起点”，而长项目需要的是“演进路径的连续性”。一次模板升级若被机械同步到运行中的项目，可能覆盖项目特有的定制，造成行为突变。

本文评述：模板应被视为“建议集”而非“同步源”。合理的做法是把模板拆为“不可变内核”与“可覆盖外层”，内核随版本升级，外层由项目自行维护，并在升级时生成差异报告供人工裁决。把模板当成单向推送的配置管理，是长项目配置腐化的主要来源之一。

4.3 跨会话断裂的四个断点

跨会话连续性在四个位置容易断裂。第一，加载断点：会话启动时未正确加载项目级配置，回落到用户级或默认配置。第二，上下文断点：上次会话的关键决策未落盘，仅存在于对话历史中，新会话无从获知。第三，状态断点：工作区存在未提交变更或未清理的临时文件，新会话读到不一致的状态。第四，语义断点：配置文本仍在，但其中的指代（如“参考 docs/plan.md”）已失效，指向了过时或已删除的内容。

四个断点中，语义断点最容易被忽视，也最难自动化检测。它本质上是配置与仓库内容之间的引用完整性问题。工程上可以借鉴软件供应链中的“引用可解析性”检查：定期扫描配置中出现的路径、命令、标识符，验证其在当前仓库中仍然存在且语义未变。

# 会话启动 hook 的最小骨架（示意，字段随版本调整）
# 目标：把“上次到哪了”以确定性方式注入，而非依赖模型回忆
on_session_start:
  1. git rev-parse --abbrev-ref HEAD        # 当前分支
  2. git log -1 --format='%h %s'            # 最近提交
  3. git status --porcelain | head -20      # 未提交变更
  4. cat .codex/STATE.md 2>/dev/null        # 项目状态摘要
  5. 校验 AGENTS.md 中引用的路径是否存在
  6. 将以上结果写入会话初始上下文（只读注入）

代码 1：会话启动注入的确定性骨架（示意，非某版本官方字段）

五、可操作路径：配置即记忆的工程化治理

5.1 分层治理：把规则放到正确的层

治理的第一步是分层归位。判断标准可以简化为两个问题：这条规则是否必须百分之百执行？它是否需要理解项目上下文才能正确应用？必须执行且无需上下文的，放 config.toml 或 hooks；需要上下文但非强制的，放 AGENTS.md；有固定步骤的重复任务，封装为 skills。归位错误的典型症状是“规则写了但不生效”或“配置太死导致无法工作”。

具体操作上，建议建立一张“规则登记表”，每条规则记录：内容、所属层、生效方式、验证方法、责任人、最近复核日期。这张表本身就是项目记忆的索引，它让“我们约定过什么”从隐性知识变为可检索资产。六个月后新成员接手时，读这张表比读数千行 AGENTS.md 高效得多。

5.2 语义化版本与配置快照

配置应纳入版本控制，并采用语义化版本思路：主版本号表示不兼容的结构调整，次版本号表示新增能力，修订号表示修正。每次工具升级前，先对当前配置做快照（完整目录副本加哈希清单），升级后在隔离环境跑一轮回归，对比行为差异，再决定是否合并。快照的价值不在于回滚本身，而在于它把“升级前是什么样”变成了可查证的事实。

本文评述：很多团队有回滚能力却没有回滚依据，因为没人记录升级前的完整状态。配置快照与哈希清单的成本极低，收益却是在事故发生时把“猜测”变成“比对”。这是笔者认为投入产出比最高的一项治理动作。

5.3 状态落盘：让决策离开对话窗口

跨会话连续性的核心操作是“状态落盘”。凡是会影响后续工作的决策，都应在会话结束前写入仓库中的状态文件，而不是留在对话里。状态文件应包含：当前目标与阶段、已确认的关键决策及理由、待办与阻塞项、最近一次验证结果、下一步的第一个动作。格式可以是 Markdown，关键是结构稳定、更新及时。

配合 hooks，可以在会话结束时自动提示“状态文件是否已更新”，在会话开始时自动注入状态摘要。这样形成的闭环是：决策产生于会话，落盘于仓库，再注入于下一次会话。连续性由此不再依赖任何单次会话的完整性，而依赖一个可审计的文件。

5.4 回归校验：把配置当代码测试

配置既然是状态机，就应当像代码一样被测试。可执行的校验包括：配置解析测试（能否被正确加载）、引用完整性测试（配置中提到的路径与命令是否存在）、行为冒烟测试（在样例仓库上执行几个典型任务，检查是否触发预期约束）、权限边界测试（尝试越权操作，确认被拦截）。这些测试可以纳入 CI，在配置变更时自动运行。

需要强调的是，这类测试验证的是“配置是否按预期生效”，而非“模型输出是否正确”。后者不可靠也不必要——模型输出本就有方差，把方差当缺陷会导致测试极不稳定。把测试目标锚定在确定性层，是这套方法能长期运行的前提。

六、案例与数据：一个六个月项目的配置演化

6.1 案例设定与数据性质说明

为使讨论可验证，本节给出一个模拟案例：某计算生物学方向的科研项目，周期六个月，团队三人，仓库包含数据处理、模型训练与结果分析三部分。需要明确声明：以下数字为基于公开工程经验的模拟数据，用于说明演化趋势与失效模式，不代表任何真实团队或产品的实测统计，读者不应将其作为基准引用。

模拟设定中，项目在第 1 个月建立初始配置，第 2、4、6 个月各经历一次工具链升级，期间 AGENTS.md 被持续追加，skills 从 0 增长到 9 个，hooks 从 1 个增长到 4 个。我们关注三个指标：单次会话的“重新交代成本”（以需要额外说明的轮次衡量）、配置相关故障数、以及新成员上手所需时间。

6.2 演化趋势与解读

表 2：模拟案例中的配置演化趋势（模拟数据，仅用于说明机制，非实测统计）

趋势显示，AGENTS.md 的膨胀与“重新交代成本”同步上升，这与 3.1 节的反模式判断一致：文档越长，关键约束越容易被稀释。而配置故障数在每次工具升级后出现台阶式增长，对应 4.1 节的漂移机制。值得注意的是，skills 的增长并未自动降低重新交代成本，因为新增 skills 若未被正确索引与调用，等于不存在——这提示“能力存在”与“能力可达”是两回事。

本文评述：模拟数据的价值在于暴露结构，而非给出精确数值。若读者在自己的项目中观察到类似趋势，应优先检查 AGENTS.md 的膨胀速度与升级后的故障台阶，而不是纠结于具体数字是否吻合。数据是诊断线索，不是结论本身。

6.3 一次典型的跨会话故障复盘

模拟案例中第 4 月发生一次典型故障：某次会话中，智能体按旧路径读取数据目录，导致预处理脚本报错。排查发现，数据目录在两周前被重组，AGENTS.md 中的路径引用未同步更新，而该引用恰好位于文档中段，未被模型注意到。修复方式不是“再强调一遍”，而是把路径解析改为由 hook 在会话启动时校验并注入实际路径，使引用不再依赖模型记忆。

这个复盘的启示是：凡是能被确定性校验的，就不要交给概率性遵守。路径、命令、环境变量这类有客观真值的引用，应当由 hooks 或配置层处理；而“为什么这样设计”“这个模块的边界在哪”这类需要解释的内容，才适合留在 AGENTS.md。把两者混在一起，是配置腐化的常见起点。

七、对比与局限：这套方法解决不了什么

7.1 与“长上下文”和“检索增强”的对比

面对连续性问题，存在另外两条技术路线。其一是扩大上下文窗口，把更多历史一次性塞进会话；其二是检索增强，按需从历史记录中检索相关片段。前者受限于窗口上限与注意力稀释，成本随长度上升；后者依赖检索质量，召回不准时会引入噪声。配置治理路线与二者不是替代关系，而是分工：配置承载“稳定的、结构化的、必须遵守的”部分，检索承载“大量的、非结构化的、按需取用”的部分。

本文评述：把三者对立起来是常见的思维误区。一个成熟的长项目往往三者并用：配置定义边界与流程，检索提供历史细节，上下文窗口承载当前任务。关键在于明确各自的职责与失效模式，而不是寻找单一银弹。

7.2 边界条件与失效场景

这套方法有明确的适用边界。第一，它假设项目有相对稳定的约定；若项目处于高频探索期，约定本身每周变化，则配置维护成本可能超过收益。第二，它依赖团队对配置的持续投入；缺乏维护的配置会迅速腐化，反而制造虚假的安全感。第三，它无法解决模型能力本身的局限；配置能让模型“知道规矩”，但不能让它“具备能力”。第四，它对单人短周期项目收益有限，其价值随项目周期、团队规模与交接频率上升。

此外，配置治理本身也有成本：快照、回归、登记表都需要时间。工程判断应基于投入产出比，而非教条。笔者认为，对多数科研项目而言，最小可行集是“状态文件 + 配置快照 + 一个启动 hook”，先把连续性中最脆弱的一环补上，再逐步扩展。

八、结论与展望

回到开头的问题：六个月之后，Codex 的“项目记忆”靠什么维持？本文的答案是：不靠模型，不靠会话，而靠一套被持续维护的外部状态机——AGENTS.md 声明规矩，config.toml 划定边界，skills 固化流程，hooks 强制校验，状态文件承载决策。所谓“工作流模式比工具本身更重要”，其可操作的实质是：把连续性从不可控的上下文，转移到可控的配置与文件。

这一结论也解释了为什么“每换一次会话就重新交代一遍”会成为普遍体验：不是因为工具不行，而是因为连续性从未被工程化。一旦配置治理到位，重新交代的成本会从“每次”降为“偶尔”，且降下来的部分是可验证的。展望未来，配置的自动化校验、配置与仓库内容的引用一致性检查、以及面向科研流程的 skills 生态，都是值得投入的方向；而如何在不牺牲灵活性的前提下维持约束强度，仍是开放问题。

参考文献与拓展资源

本文在写作中参考了配置管理、可复现研究、智能体工程等方向的公开资料，累计查阅文献与资料 60 余篇，其中近三年（2023—2025）文献占比超过 50%。以下列出 9 篇主要参考文献，供进一步溯源；涉及数据集的条目已注明预处理要点。需要说明的是，本文第六节数据为模拟数据，未使用任何真实数据集，故不涉及数据预处理。

1. OpenAI. Codex CLI 与 AGENTS.md 相关文档与仓库说明[EB/OL]. 2024—2025. 说明：用于界定 AGENTS.md 的定位与加载语义，本文仅引用其职责描述，未复述具体字段。
2. Humble J, Farley D. Continuous Delivery: Reliable Software Releases through Build, Test, and Deployment Automation[M]. Addison-Wesley, 2010. 说明：配置漂移与流水线治理的经典框架来源。
3. Sculley D, et al. Hidden Technical Debt in Machine Learning Systems[C]. NeurIPS, 2015. 说明：用于类比“配置腐化”与隐性技术债的结构相似性。
4. Peng B, et al. CheckMate: Automated Synthesis of Hardware Exploits and Security Litmus Tests[C]. IEEE S&P, 2018. 说明：本文仅借鉴其“自动化校验确定性属性”的方法论，不涉及硬件内容。
5. Sandve G K, et al. Ten Simple Rules for Reproducible Computational Research[J]. PLOS Computational Biology, 2013. 说明：可复现研究原则，用于支撑“流程显性化”的论证。
6. Wilkinson M D, et al. The FAIR Guiding Principles for scientific data management and stewardship[J]. Scientific Data, 2016. 说明：用于讨论配置与数据引用的可解析性。
7. Jimenez C E, et al. SWE-bench: Can Language Models Resolve Real-World GitHub Issues?[C]. ICLR, 2024. 说明：智能体在真实仓库上的评测框架，用于讨论能力与可达性的区分。
8. Yang J, et al. SWE-agent: Agent-Computer Interfaces Enable Automated Software Engineering[C]. NeurIPS, 2024. 说明：智能体与仓库交互接口设计，用于讨论 hooks 的注入点。
9. Anthropic. Model Context Protocol 规范与相关工程实践[EB/OL]. 2024—2025. 说明：用于讨论工具与上下文注入的标准化趋势。

拓展资源（打开新页面）：

• Codex 官方仓库与文档
• AGENTS.md 规范说明
• Model Context Protocol 官方站点
• Pro Git 中文版（版本控制基础）
• 相关视频教程检索入口