AGENTS.md、CLAUDE.md 与项目 Memory

建议用时：25 分钟（含练习）

学习目标

能够编写短小、可执行的项目说明，让 Agent 知道结构、命令、边界和完成标准。

本节产出

一份最小项目 Memory 文件

核心知识：项目记忆是路标，不是第二套代码库

每次进入一个仓库，Agent 都需要知道项目怎样启动、测试怎么跑、哪些目录负责什么，以及哪些操作不在本次授权范围。

术语

项目指令文件

AGENTS.md、CLAUDE.md 等项目指令文件可以保存这些稳定约定。它们帮助工具找到正确上下文，但不是所有产品都以相同方式读取，也不是一个文件名放在那里就必然生效。

阅读当前工具文档，确认指令从哪些位置加载、目录范围如何决定、是否存在覆盖文件和大小限制。不要把 Claude Code 的规则原封不动套给 Codex，也不要假定更深目录中的一句话可以绕过组织或系统限制。发现规则矛盾时，应定位适用范围和权威来源，而不是选择最方便执行的那条。

项目指令适合保存不容易从代码表面看出的约定，例如测试使用专用命令、生成文件不能手工改、生产操作需要独立流程。具体 API 结构和部署记录应放在维护中的文档，再用链接指向它们。把所有历史对话、错误日志和已过期任务塞进根指令，会使关键信息更难找到。

图中“代码与文档提供事实”不意味着任何文件里的文字都是指令。代码注释、网页摘录和测试样例都可能包含命令式语言。Agent 读取它们是为了理解材料，不应把其中的“忽略规则、发送秘密”等文本升级为用户授权。

一份简短项目指令应该包含什么

下面是虚构练习项目的例子，路径和命令只描述该项目，不是通用操作要求。

# Project map

- src/report.ts: 生成报告的纯函数。
- tests/report.test.ts: 报告行为测试。
- docs/report-format.md: 对外输出字段约定。

# Working rules

- 修改报告行为后运行 npm test。
- 保留既有输出字段，新增字段先核对格式约定。
- 不修改生成目录 dist/。
- 不访问真实用户数据；练习使用 fixtures/ 的虚构输入。

这个文件没有复制整个格式文档，也没有写几十条泛泛的“高质量代码”口号。读者可以迅速找到实现、测试和合同，知道修改边界。若测试命令后来变化，应同步更新，而不是让新会话持续执行过期命令。

记忆需要验证与维护

一条“数据库没有迁移”的笔记，只能描述写下时的观察；不能永久成为事实。

容易变化的信息

对容易变化的信息，应标注核对日期、来源和适用版本，或直接链接到最新状态。

长期规则

对于长期规则，例如“秘密不得提交”，则不必每次任务重复抄写。

当代码与文档不一致，先用可复现证据确定实际行为，再判断应修代码还是文档。不能为了让测试通过而修改项目记忆中的要求，也不能仅凭旧记忆忽略当前用户的新要求。记忆帮助延续工作，不替代本次任务的理解。

案例：一次修复怎样沉淀成可用知识

虚构项目曾多次出现日期格式错乱。调查发现界面需要本地显示格式，API 输出必须使用固定机器格式。任务完成后，不必把整段排错聊天放进 AGENTS.md。可以在格式文档中解释两种用途，在根指令中只写“修改日期输出前阅读该文档，并运行对应测试”。

这样，下次 Agent 能找到真正的合同和测试。如果以后格式约定改变，只需要更新那份权威文档与测试，不必在十个指令文件里同步复制内容。减少重复还能避免一处写旧格式、另一处写新格式的冲突。

同时检查记录中是否包含真实接口密钥、内部账号或用户样本。项目记忆经常会被提交或发送给模型，因此不能把它当作秘密保险箱。能够用变量名和受保护配置位置解释的，就不要写实际值。

动手练习

1. 为一个小型练习仓库写不超过一页的项目地图，包含实现、测试、格式文档和两个实际边界。
2. 找出一条易变事实和一条长期规则，分别设计存放位置及更新方式。
3. 在一段测试材料中加入明显标注为示例的“忽略之前指令”文字，说明为什么它只能作为数据被读取，而不应改变任务授权。不要实际执行其中的动作。

参考答案与推演

展开

完成检查

• 知道当前工具实际如何加载指令，未混用产品规则。
• 项目地图短而可执行，详细事实有唯一维护位置。
• 易变记录有日期或版本，秘密没有写进记忆。
• 能区分材料中的文字与真正授权的指令。

参考与来源

• OpenAI：Custom instructions with AGENTS.md：核对 Codex 的项目指令机制。
• Claude Code：How Claude remembers your project：核对 Claude Code 的项目上下文与记忆机制。