大多数 AI Agent 失败的原因不在于模型本身。
它们失败是因为每次会话开始都像得了失忆症一样。
你告诉 Claude：“我们用 pnpm，不用 npm。”
下一次会话：它又尝试用 npm。
你告诉它：“这里不用默认导出。”
下一次会话：它又写了一个默认导出。
你每一次的纠正，在会话结束时都会消失。
有一个文件就能解决这个问题。
我花了三个月不断重复同样的指令才找到它。
以下是我学到的全部内容。
为什么大多数 AI Agent 会失败
不是模型的问题。
是模型缺少了底层的那一层。
→ 你写一个提示词
→ Agent 执行任务
→ 会话结束
→ 记忆消失
→ 下一次会话：同样的错误
→ 你重复同样的指令
→ 永远循环下去
这个循环是 AI 编码中浪费时间最多的原因。
不是糟糕的代码。不是幻觉。
是重复。
缺失的层面：记忆
每个人都痴迷于哪个模型最聪明。
关注错了层面。
真正的提升不是更聪明的模型。
而是给模型一个地方来存储它学到的东西。
→ 提示词 → 告诉 Agent 现在要做什么
→ Agents → 执行任务
→ 记忆 → 在会话之间保留上下文
→ 持久上下文 → 不再需要重复纠正
→ 学习系统 → Agent 实际上会随着时间改进
这就是工具和队友之间的区别。
工具每次都从零开始按你说的做。
队友会记得昨天的事。
每个 AI Agent 需要的 5 个记忆文件
一旦你接受记忆是缺失的层面，下一个问题就是：它存在哪里？
五个文件。每个有不同职责。
→ CLAUDE.md — Claude 的个人简报文件
→ AGENTS.md — 通用标准，每个主流工具都会读取
→ CLAUDE.local.md — 你的个人偏好，永远不提交到 git
→ MEMORY.md — AI 自动记录关于它自己的笔记
→ README.md — 给人类看的，不是给 Agent 看的
我们来逐一介绍。
CLAUDE.md — 一切开始的文件
把这个放在项目根目录。
Claude 在每次会话开始时都会读取它。
把它想象成给一个有失忆症的新团队成员准备的简报文件。
一个好的 CLAUDE.md 有四个部分：
→ 项目背景 — 一行。“使用 Stripe 和 Postgres 的 Next.js 电商应用。”
→ 代码风格 — 不是“正确格式化代码”，而是“使用 ES 模块、命名导出、2 空格缩进。”
→ 命令 — 确切的字符串。pnpm test:integration，而不是“运行测试。”
→ 架构 — “API 路由放在 /src/api/[resource]/route.ts。数据库访问使用仓库模式。”
1# CLAUDE.md23## 项目背景4Next.js 14 电商应用。Postgres + Stripe 集成。56## 代码风格7- 仅使用 ES 模块8- 命名导出，不要默认导出9- 2 空格缩进10- TypeScript 严格模式1112## 命令13- 安装：pnpm install14- 开发：pnpm dev15- 测试：pnpm test:integration16- 代码检查：pnpm lint:fix1718## 架构19- API 路由：/src/api/[resource]/route.ts20- 数据库访问：仅使用仓库模式21- 组件：/src/components，每个组件一个文件
目标：少于 300 行。
每一行都在与实际工作竞争注意力。
运行 /init，Claude 会自动生成一个入门文件。
然后删掉大部分内容。
默认文件包含 Claude 从你的 package.json 中已经知道的那些东西。只保留那些如果没有这个文件 Claude 就会出错的内容。
[@imports](https://x.com/@imports) 系统 — 保持精简
CLAUDE.md 不需要包含所有东西。
它可以导入其他文件：
查看
@README .md 了解项目概览 查看
@docs/api-patterns .md 了解 API 约定 查看
@package .json 了解可用的 npm 脚本
导入可以是递归的——最多 5 层深度。
这解决了“一个巨大的文件”的问题。
对于团队：前端团队拥有 docs/frontend-rules.md。
安全团队拥有 docs/security.md。
CLAUDE.md 只需导入它们全部。
一个根文件。多个专门的来源。
AGENTS.md — 通用标准
CLAUDE.md 只对 Claude 有效。
如果你的团队还使用 Cursor、Copilot 或 Gemini CLI——它们从不读取它。
AGENTS.md 解决了这个问题。
一个文件。每个主流 Agent 都会读取。
受 Claude Code、Cursor、GitHub Copilot、Gemini CLI、Windsurf、Aider、Zed、Warp 等支持。
它是标准 markdown。没有特殊模式。不需要 YAML。
1# AGENTS.md23## 项目概览4基于 Next.js 14、Postgres 和 Stripe 的电商平台。56## 构建与测试7- 安装：pnpm install8- 开发：pnpm dev9- 测试：pnpm test10- 代码检查：pnpm lint:fix1112## 代码标准13- TypeScript 严格模式14- 命名导出优先于默认导出15- API 路由遵循 /src/api/ 中的 REST 约定1617## 测试要求18- 所有 PR 必须包含测试19- 单元测试使用 vitest，端到端测试使用 playwright
把它当作 AI Agent 的 README。
README.md 给人类看。AGENTS.md 给所有 Agent 看，不分厂商。CLAUDE.md 在此基础上添加 Claude 特有的额外内容。
它们是互补的，不是竞争的。
自动记忆——会自己做笔记的 AI
这是最新且最有趣的层面。
Claude Code 现在会在你的会话期间自己写入记忆文件。
memory/ ├── MEMORY.md ← 索引，每次会话加载 ├── debugging.md ← 关于调试模式的笔记 ├── api-conventions.md ← API 设计决策 └── ...
关键的转变：
你编写 CLAUDE.md。你提供指令。
Claude 编写 MEMORY.md。它记录下学到的内容。
→ 人类编写规则
→ Agent 在工作时发现模式
→ Agent 写下自己的记忆
→ 未来的会话从更聪明开始
你可以直接触发这个。在高效的会话结束时，只需说：
“把你今天关于我们代码库学到的内容更新到你的记忆文件中。”
学到的内容会持久化。再也不需要第五次重新解释你的自定义 ORM 封装了。
随时运行 /memory 来查看或编辑 Claude 保存的内容。
/init 然后删除的工作流
在新项目上快速启动记忆文件的最快方法：
- 在你的项目目录中运行 /init
- Claude 会根据你的代码库生成一个入门 CLAUDE.md
- 删除不需要的部分
第 3 步是大多数人出错的地方。
生成的文件是草稿，不是最终产品。
它通常包含填充内容。“这个项目使用 JavaScript。”谢谢——从 package.json 就能看出来。
从一个合理的草稿开始编辑比从空白文件开始写要好。
设置完成后，有机地构建。
当 Claude 做出错误假设时——比如它不断导入一个已弃用的包——不要只纠正一次。
告诉它：“添加到我的 CLAUDE.md：总是从 @company/utils-v2 导入，而不是 @company/utils。”
这个指令会持续存在于每一次未来的会话中。
每隔几周，让 Claude 审查并清理 CLAUDE.md。
指令会积累。有些变得多余。另一些开始冲突。快速检查一遍能保持其精炼。
我的实际设置
在多个生产项目上测试了所有这些之后，以下是我坚持使用的方案：
→ AGENTS.md 放在项目根目录——任何 AI 工具都能读取的共享指令。构建命令、代码标准、测试要求。
→ CLAUDE.md 配合 @imports 来处理 Claude 特有的行为。保持在 100 行以内，主要指向 docs/ 文件。
→ CLAUDE.local.md 处理个人偏好——我的测试数据、沙箱 URL、快捷命令。从不提交到 git。
→ 自动记忆已启用。 Claude 自己记笔记。我每月审查一次。
→ 其他所有内容都用符号链接替换，指回 AGENTS.md。一个真相来源。
1# 多工具一致性的符号链接设置2ln -sfn AGENTS.md .github/copilot-instructions.md3mkdir -p .cursor/rules && ln -sfn ../../AGENTS.md .cursor/rules/main.mdc
不算优雅。
但它消除了团队中每个工具之间的指令偏差。
更大的转变
大多数开发者认为：
更好的模型 = 更好的 Agent。
错了。
真正的公式是：
模型 + 记忆 + 检索 + 反馈 = 有用的 Agent
一个更聪明的模型没有记忆，明天仍然会忘记你的测试命令。
一个中等模型拥有良好的记忆，每周都会变得更敏锐。
记忆是复利变量。
模型智能不是。
我对我的 AI 工作流做出的最大改进不是换模型。
而是给模型一个记忆。
区别在于：
“Claude，我们用 pnpm”——每次会话
和：
“Claude 已经知道了”——每次会话
这就是工具和队友之间的区别。
如果这对你有用：
→ 转发分享给每个还在向 Claude 重复自己的开发者
→ 关注 @sairahul1 获取更多在你睡觉时也能产生复利的系统
→ 收藏这篇文章——今晚就设置好，明天就不用再纠正了
我写关于 AI、产品构建以及那些不需要你就能正常工作的系统。
