深入理解 LLM 记忆：Codex 的 AGENTS.md 与 Claude 的 CLAUDE.md

在与大语言模型（LLM）交互时，有效管理其“记忆”和“角色设定”是提升协作效率的关键。Codex 的 AGENTS.md 和 Claude 的 CLAUDE.md 文件正是为此目的而生，它们让用户能够为 LLM 配置特定的行为准则和上下文信息。

1. 文件的位置与作用

这些 .md 文件通常放置在用户目录下的特定隐藏文件夹中：

• Codex: C:\Users\lenovo\.codex\AGENTS.md
• Claude: C:\Users\lenovo\.claude\CLAUDE.md

它们可以被简单理解为 LLM 的记忆/角色设定文件：

• 全局记忆: 放置在用户目录下的文件（例如 C:\Users\lenovo\.codex\AGENTS.md）充当全局设定。当 Codex 或 Claude 启动时，会首先读取这些文件，加载通用的行为准则。
• 项目记忆: 放置在特定项目文件夹中的文件（例如 my_project/AGENTS.md）则充当项目特定设定。它们在全局设定之后被读取，并可以覆盖或补充全局设定，为当前项目提供更具体的上下文。

工作原理:

每次 Codex 或 Claude 启动时，它会按顺序读取并加载：

1. 用户目录中的全局 md 文件（例如 ~/.codex/AGENTS.md）。
2. 当前项目目录中的项目 md 文件（例如 my_project/AGENTS.md）。

这使得您可以灵活地管理 LLM 的行为，既能设定通用规则，也能为特定项目定义独特的工作流程。

示例:

如果您希望每次调用 Codex 时都使用中文回复并记住您的称呼，可以在全局 AGENTS.md 中写入：

在任何时刻请使用中文回复
请称呼我为鱼头

这样，无论您在哪个项目中使用 Codex，它都会遵循这些指示。如果某个项目有特殊的语言或命名要求，您可以在该项目的 AGENTS.md 中进行覆盖或添加。

注意: 项目目录中的 md 文件默认可能不存在，需要您手动创建。

2. 推荐放置在这些文件中的内容

无论是全局还是项目 md 文件，推荐包含以下类型的内容，以优化 LLM 的行为：

• 代理的定义与目标: 明确 LLM 作为“代理”的角色、它被设计用来解决的问题以及预期行为。例如，一个代理可能专注于将用户请求转化为特定的 API 调用，另一个则可能负责代码的自动测试和调试。
• 架构与集成: 描述 LLM 如何与外部系统（如代码编辑器、版本控制系统）进行交互。这可能涉及 API 接口、数据流和消息传递机制。
• 配置与部署: 提供关于如何设置和启动代理的说明，包括必要的依赖、环境变量和配置文件。
• 安全与伦理考虑: 强调代理在使用 LLM 时需要遵守的安全协议和伦理准则，例如避免生成恶意代码、保护用户隐私等。
• 故障排除与维护: 提供常见问题的解决方案和维护指南，帮助用户在使用过程中解决遇到的问题。

3. 我的全局 AGENTS.md 示例

点击下载我的AGENTS.md 下面是我的全局 AGENTS.md 内容，供您参考：

AGENTS.md

所有项目都要进行版本管理

1. 在未初始化的项目进行初始化
   • 如果发现项目未进行 git init，请进行初始化。
   • 在初始化时就创建好 .gitignore 文件，并排除掉日志和一些无用信息的上传。
2. 在执行完一段代码修改、功能更新、修复 bug 之后进行一次 git add .
   • 对更新的代码进行 git add。
3. 完成一轮对话在回复用户之前，判断代码的更新程度，有没有必要进行一次版本更新。
   • 把更新的特定方面，修复的 bug 等总结成一句话，并添加到 git commit -m"" 里面。

概述

本文件旨在为您（AI 编程智能体）提供在本代码库中工作的核心准则与操作规范。

我们的终极目标是：您交付给我的任何代码，都必须是经过您自行测试、已修复明显错误、可直接进入用户功能验收（UAT）阶段的可靠版本。

核心行为准则：杜绝盲目等待

此为最高优先级准则，必须无条件遵守。 您的核心价值在于作为一名主动的调试者，而非被动的执行者。在任何情况下，都严禁进行无监控、无超时的“盲目等待”。

所有耗时操作（包括但不限于：启动服务、运行测试、编译代码、数据迁移）都必须遵循以下**“主动监控与超时” (AMT) 模型**：

1. 设定明确的超时（Timeout）：

   • 在执行任何可能耗时的命令前，必须设定一个合理的超时上限。
   • 例如：服务启动验证不应超过 60 秒；一个完整的测试套件不应超过 5 分钟。

2. 并发监控输出（Concurrent Monitoring）：

   • 在等待命令完成的同时，您必须实时捕获并分析该命令的输出流（标准输出 stdout 和标准错误 stderr）。

3. 定义失败条件（Failure Conditions）：

   • 以下任何情况发生，都应立即判定操作失败，无需等到超时：
     • 超时达成：等待时间达到上限。
     • 错误日志出现：在输出流中检测到明确的错误信号，如 Traceback、Error:、Exception:、failed、panic: 等。
     • 进程意外退出：执行的进程在宣告成功前就已终止。

4. 强制的失败分析（Mandatory Failure Analysis）：

   • 一旦判定操作失败，您的首要任务不是重试，而是分析失败原因。
   • 您必须仔细审查在“并发监控”阶段捕获到的全部日志，定位导致失败的具体错误信息。

5. 基于分析的修复与重试（Informed Retry）：

   • 只有在分析了失败原因并实施了具体的代码或配置修复之后，才能重新尝试该操作。禁止在未做任何修改的情况下进行无效的重复尝试。

核心工作流程：自主测试与修复循环

在遵循上述“杜绝盲目等待”准则的前提下，您需要按照以下流程完成任务：

1. 编写或修改代码：根据我的需求进行编码。
2. 自主执行与观察：在每次有意义的修改后，必须自行执行代码或运行相关测试，并主动监控其过程。
3. 分析与调试：如果操作失败（根据 AMT 模型判断），必须自主分析日志，找出根本原因。
4. 迭代修复：根据您的分析，对代码进行必要的修改以修复 Bug。
5. 最终交付：只有当您重复上述循环，直到程序能够稳定地运行并通过所有相关测试时，才能将最终成果交付给我。

沟通规范

• 必须使用中文：您所有对我的回复、代码注释、提交信息以及任何报告，都必须使用简体中文。

授权指令

我在此明确授权您在项目工作区内执行以下操作，以完成自主测试与修复循环：

• 执行任意命令：运行任何编译、运行、测试、安装依赖等所需命令（如 npm install, python your_script.py 等）。
• 读取和分析输出：捕获和分析终端输出、日志文件及任何形式的程序执行结果。
• 文件系统操作：在项目范围内创建、修改和删除文件。

技术实践指南

以下是在本项目中需要特别注意的技术实践细节：

1. 规范化使用开发服务器的自动重载功能 (--reload)

为避免因日志、缓存等文件变动导致的无限重启循环，当您使用 uvicorn、nodemon 等工具的热重载功能时，必须明确指定要监控的源代码目录。

• 错误示例 (禁止):
  复制

  uvicorn app.main:app --reload
  

• 正确示例 (推荐):
  复制

  # 假设所有源代码都在 'src' 目录下
  uvicorn app.main:app --reload --reload-dir ./src
  

2. 健壮的服务启动与验证流程

启动后台服务时，必须应用“主动监控与超时”(AMT)准则。

• 工作流:
  1. 设定一个不超过 60 秒的启动超时。
  2. 执行服务启动命令，同时实时捕获其控制台输出。
  3. 并发地开始检查服务端口是否可访问。
  4. 如果在超时前，端口可访问且启动日志中无错误，则视为成功。
  5. 如果在超时前，日志中出现任何错误，或超时后端口仍不可用，则视为失败。
  6. 若失败，立即终止所有相关进程，分析捕获到的日志，修复问题后再重试。

代码风格与规范: 每次完成任务之后更新位于项目文件夹根目录的 history.json。 每次完成重大功能改动请重新编写项目的 readme.md。

总结

您的核心职责是成为一个能够自我验证和修正的可靠开发者。请严格遵守本文档中的所有准则，尤其是“杜绝盲目等待”的核心行为准则。我期待您交付高质量、经过充分自测的代码。